8. G-ADK Tool 활용[5](1/3) - BuiltInCodeExecutor(내장 실행기)를 로컬 환경에서 구현

Google ADK(Agent Development Kit)에서 제공하는 Code Execution(코드 실행 기능)의 세 가지 방법 중 첫 번째인 BuiltInCodeExecutor를 활용하는 에이전트 코드입니다.

1. BuiltInCodeExecutor의 핵심 개념 (Code Execution이란?)

LLM은 언어 모델 특성상 복잡한 다단계 산술 연산, 데이터 분석, 프로그래밍 로직 검증 등에서 가끔 실수를 하거나 환각(Hallucination)을 일으킬 수 있습니다. 이를 해결하기 위해 에이전트가 "말이나 생각으로만 답하지 않고, 직접 파이썬 코드를 작성해서 실행한 뒤 그 결과를 보고 답변하는 능력"을 부여하는 기술이 바로 Code Execution입니다.

그중 BuiltInCodeExecutor()는 ADK 내부에서 기본으로 제공하는 샌드박스 환경을 활용해, 에이전트가 생성한 파이썬 코드를 안전하게 실행하고 그 결과(출력값, 에러 등)를 다시 LLM에게 피드백해 주는 내장형 실행기입니다.

2. 코드 라인별 상세 해설

• from google.adk.code_executors import BuiltInCodeExecutor
  • ADK 라이브러리에서 기본 제공하는 코드 실행기 모듈을 불러옵니다. 이 모듈이 장착되면 에이전트는 텍스트 답변뿐만 아니라 파이썬 코드를 실행할 수 있는 역량을 갖추게 됩니다.
• model=os.getenv("GOOGLE_MODEL", "gemini-3.5-flash")
  • 환경 변수에서 모델명을 가져오며, 기본값으로 최신 Gemini 모델을 사용합니다. 코드를 짜고 결과를 해석해야 하므로 추론 능력이 뛰어난 모델과 조합할 때 시너지가 좋습니다.
• code_executor=BuiltInCodeExecutor()
  • [핵심 포인트] 에이전트에 파이썬 실행 엔진을 연결해 주는 설정입니다. 일반 툴(tools=[...])과 달리 code_executor라는 전용 파라미터 자리에 들어갑니다. 이를 통해 모델은 필요할 때마다 파이썬 스크립트를 작성하여 실행할 수 있는 권한을 얻습니다.
• instruction="당신은 수학 및 데이터 분석 전문가입니다..."
  • 에이전트에게 역할과 행동 지침을 부여합니다. 복잡한 계산이나 데이터 분석 요청이 들어왔을 때 머리로 계산하려 하지 말고, "반드시 직접 파이썬 코드를 작성하고 실행하여" 그라운드 트루스(정확한 결과값)를 도출하라는 엄격한 가이드라인을 제공합니다.

3. 요약 및 기대 효과

이 에이전트에게 *"1부터 100만까지의 소수의 합을 구해줘"*라거나 "주어진 CSV 데이터의 상관관계를 분석해줘" 같은 요청을 던지면, 에이전트는 머리로 추정하는 대신 파이썬 코드를 작성하고 BuiltInCodeExecutor로 실행한 뒤, 그 실행 결과(Standard Output)를 바탕으로 완벽하게 정확한 답변을 만들어내게 됩니다.

 

 

    import os

    from google.adk import Agent

    from google.adk.code_executors import BuiltInCodeExecutor

    coding_agent=Agent(

        model=os.getenv("GOOGLE_MODEL","gemini-3.5-flash"),

        name="coding_agent",

        code_executor=BuiltInCodeExecutor(),

        instruction=("당신은 수학 및 데이터 분석 전문가입니다. 복잡한 계산이나 로직이 필요한 경우, 직접 파이썬 코드를 작성하고 실행하여 정확한 결과값을 도출하세요."),

    )

    root_agent = coding_agent