[LLM] Agent Development Kit (ADK)

Agent Development Kit(이하 ADK)는 구글에서 발표한 에이전트 개발용 프레임워크다.
채팅으로 대표되는 LLM 에이전트 개발용으로 만들어졌다.

현재는 Python과 Java 정도만 지원된다. 메인은 당연히 Python이다.

구글에서 제공하는 Gemini나 vertex API를 주로 쓴다는 가정 하에 친절하게 꾸며놓은 모양새다. 물론 Gemini에 종속된 구조는 아니라서 Claude나 GPT 같은 LLM 모델들과도 통합이 가능하긴 하다.

여기서는 개략적인 사용 구조와 기본적인 예제 정도만을 다뤄본다.

구조

기본적인 구조나 방법론 자체는 비교적 간단한 편이다.
별도의 에이전트 단위를 클래스 단위로 정의하고, 그걸 필요에 따라서 연결하고 상호간에 호출할 수 있게 엮어주는 것이 골자다.

그 외에도 이것저것 지원하긴 한다.
tool 관리 기능도 있고, 개발/디버깅 보조용 도구들을 약간 지원한다.

설치

설치 자체는 간단하다. 단일 종속성으로 바로 사용할 수 있다.

uv add google-adk

크기는 340mb쯤 된다. 떡칠을 하도 해대서 좀 비대한 편이다.

프로젝트 기본 구조

먼저, LLM을 사용하기 위한 API Key를 준비해야 한다.
GCP API를 통해서 Gemini를 쓴다면, 이렇게 .env 파일을 통해서 GOOGLE_API_KEY 환경변수로 키를 설정할 수 있다.

이건 프로젝트 루트 경로에 있어도 되고, 에이전트별 별도 디렉터리에 있어도 된다.

그리고 이게 프로젝트의 기본적인 형태다.
에이전트마다 폴더를 만들고, agent.py라는 기본 진입점 파일을 추가한다.

각 agent.py에는 다음과 같이 에이전트 정의가 들어가면 된다.

from google.adk.agents import Agent

root_agent = Agent(
    name="hello_agent",
    model="gemini-2.0-flash",
    description=("Agent to say hello."),
    instruction=(
        "You are an agent who handles greetings and basic daily conversations."
    ),
    tools=[],
)

description은 대략적인 agent의 역할을 명시하고, instruction은 세부적인 지시사항들은 정의하는 부분이다.
tools는 외부 소스나 뭐 그런걸 추가하는건데, 그건 추후에 다시 정리해보겠다.

기본 사용법: adk CLI

adk CLI를 통해서 제어하는 것을 권장한다.

adk web을 사용하면, 현재 디렉터리 기준으로 에이전트 구성을 읽어서 디버그용 페이지를 생성해준다.

그러면 이런 잘 꾸며진 페이지가 뜨고

에이전트를 골라서 실행할 수 있으며

즉시 돌려보면서 테스트할 수 있다.

api_server 명령을 사용하면 저기서 그냥 API 서버만 실행되게 할 수 있다.

좀 뭐가 많긴 하다.

프롬프트 설정 - instruction

LLM의 행동 방식을 제어하려면, instruction 필드를 통해서 프롬프트를 설정하면 된다.

동작 방식 자체는 단순하다.

만약 프롬프트를 동적으로 관리하고 싶다면, before_model_callback 등을 통해서 state를 조작하고, state variable 기반으로 프롬프트 텍스트가 변경되게끔 만들 수 있다.
여기서는 자세한 것까지는 다루지 않고 넘어간다.

Tools

tools는 ADK에서 외부 소스에 접근하기 위한 수단이다.
데이터베이스에 접근하다거나, 날씨나 시간 정보를 가져온다거나 하는, LLM 자체적으로 획득할 수 없는 소스를 연결하기 위한 수단이다.

예를 들어, 시간 정보를 LLM에 주고 싶다면 이런 식으로 tool을 정의할 수 있다.

함수 내 구현이 어떻게 되는지는 그다지 중요하지 않다.
함수 내 코멘트를 통해서 해당 tool 함수의 동작과, 입력/출력값을 잘 정의하는 것이 중요하다.

그리고 저걸 tools에 넘겨주면 끝이다.

그러면 Agent가 저 코멘트에 기반해서, 필요하다고 판단되는 tool을 자율적으로 호출하는 것이다.

그러고 나서 실행해보면

이런 식으로 호출해서 LLM이 내부적으로 받아다가 쓰게 된다.

멀티 에이전트 구성

이런 에이전트 프레임워크를 쓰는 주요한 이유 중 하나가, 여러개의 에이전트로 구성된 멀티 에이전트 시스템을 구성하고 관리하기 위한 것이다.

from google.adk.agents import Agent

dev_agent = Agent(
    name="dev_agent",
    model="gemini-2.0-flash",
    description=("Agent informing about programming"),
    instruction="""
        1. You are an agent who handles programming-related queries.
        2. You must always answer about programming.
        """,
    tools=[],
)

food_agent = Agent(
    name="food_agent",
    model="gemini-2.0-flash",
    description=("Agent informing about food"),
    instruction="""
        1. You are an agent who handles food-related queries.
        2. You must always answer about food.
        """,
    tools=[],
)

root_agent = Agent(
    name="root_agent",
    model="gemini-2.0-flash",
    description=("Root agent"),
    instruction="""
        1. You are the root agent.
        2. You must always answer about programming or food.
        """,
    tools=[],
    sub_agents=[dev_agent, food_agent],
)

이런 식으로, 어떤 에이전트가 다른 에이전트를 호출하게 하려면 sub_agents로 다른 에이전트 정의를 구겨넣으면 된다.
이 경우에는 "개발"과 "음식"에 대한 에이전트를 별도로 정의하고, root 에이전트가 상황에 따라서 필요한 경우 호출할 수 있게 했다.

그러면 이런 식으로 root => food의 순서로 에이전트를 호출해서 결과를 도출할 것이다.

옆에 실행 로그도 이벤트로 확인 가능하다.

참조
https://developers.googleblog.com/en/agent-development-kit-easy-to-build-multi-agent-applications/
https://google.github.io/adk-docs/agents/llm-agents/
https://dev.to/masahide/smarter-adk-prompts-inject-state-and-artifact-data-dynamically-placeholders-2dcm