Google ADK 튜토리얼: AI 에이전트 구축부터 프로덕션 배포까지

Google ADK 튜토리얼: AI 에이전트 구축부터 프로덕션 배포까지

Google의 Agent Development Kit(ADK)는 다중 에이전트 시스템을 마침내 접근하기 쉽게 만들어주는 프레임워크입니다. LangChain이나 CrewAI로 AI 에이전트를 만들다가 프레임워크와 싸우는 느낌이 들었다면, 이 Google ADK 튜토리얼은 첫 번째 에이전트 구축부터 Cloud Run 배포까지 모든 과정을 안내합니다.

Google ADK란 무엇이며 왜 주목해야 할까요?

Google의 Agent Development Kit(ADK)는 AI 에이전트를 구축, 평가 및 배포하기 위한 오픈소스 Python 프레임워크입니다. 2025년에 출시된 이 프레임워크는 Gemini에 최적화되어 있지만 LiteLLM을 통해 100개 이상의 모델을 지원합니다. ADK의 가장 강력한 기능은 별도의 접착 코드(glue code) 없이 다른 에이전트에 작업을 위임할 수 있는 네이티브 다중 에이전트 오케스트레이션입니다.

LangChain, CrewAI, 그리고 이제 ADK로 에이전트를 만들어 본 경험으로 볼 때, ADK의 두드러진 장점은 적절한 부분에서 확고한 의견(opinionated)을 제시한다는 점입니다. 프로젝트 구조, 내장된 개발 UI, 배포 명령어를 제공하여 기본적인 에이전트를 실행하기 위해 다섯 개의 라이브러리를 이어 붙일 필요가 없습니다.

LangChain이 범용 스위스 아미 나이프라면, ADK는 다중 에이전트 워크플로우를 위해 Google이 직접 만든 전용 공구 상자입니다. CrewAI는 역할 기반 에이전트가 협력한다는 철학에서 ADK와 비슷하지만, ADK는 내장된 평가 기능, 네이티브 Gemini 최적화, 그리고 한 번의 명령어로 Cloud Run에 배포하는 기능을 통해 한 단계 더 나아갑니다. 심층적인 비교 분석은 에이전트 프레임워크 심층 비교를 참조하세요.

ADK는 누구를 위한 것일까요? 구조화된 다중 에이전트 시스템을 원하는 Python 개발자, 이미 Google Cloud나 Gemini를 사용하는 팀, 그리고 보일러플레이트 오케스트레이션 로직 작성에 지친 모든 사람을 위한 것입니다.

프레임워크별 주요 특징을 한눈에 비교해 보겠습니다:

요약하자면, "아이디어"에서 "배포된 다중 에이전트 시스템"까지 가장 빠르게 도달하고 싶다면 현재 ADK를 따라잡기 어렵습니다.

사전 준비 사항 및 Google ADK 설치

Google ADK를 시작하려면 Python 3.9+, Gemini API 키(Google AI Studio에서 무료 티어 이용 가능), 그리고 google-adk 패키지가 필요합니다. pip install google-adk로 설치하고, API 키를 환경 변수로 설정하면 5분 이내에 첫 번째 에이전트를 구축할 준비가 됩니다.

설정 체크리스트는 다음과 같습니다:

• Python 3.9+ (완전한 타입 힌트 지원을 위해 3.10+ 권장)
• Gemini API 키, aistudio.google.com에서 무료로 발급받으세요. 무료 티어는 분당 15개의 요청을 허용하므로 개발용으로 충분합니다.
• pip (속도를 원한다면 uv도 좋습니다. uv pip install google-adk 역시 작동합니다)

패키지를 설치하고 키를 설정하세요:

pip install google-adk

# Set your API key (add to .bashrc/.zshrc for persistence)
export GOOGLE_API_KEY="your-api-key-here"

ADK는 특정 폴더 구조를 요구합니다. 각 에이전트는 자체 패키지 디렉터리에 위치해야 합니다:

my_agent/
  __init__.py    # Exports root_agent
  agent.py       # Agent definition
.env             # Optional: GOOGLE_API_KEY=your-key

폴더 이름이 에이전트의 패키지 이름이 되므로 설명적인 이름을 선택하세요. test나 agent라고 명명하면 Python의 import 시스템과 혼동을 일으킬 수 있습니다.

프로 팁: uv를 사용한다면, 먼저 uv venv && source .venv/bin/activate로 가상 환경을 생성하세요. 의존성 해결 측면에서 일반 pip보다 заметно 빠릅니다.

첫 번째 Google ADK 에이전트 구축하기

첫 번째 ADK 에이전트에는 이름, 모델(예: gemini-2.0-flash), 그리고 지시문(instruction) 문자열이라는 세 가지 요소만 필요합니다. 이를 agent.py에 정의하고 __init__.py가 있는 폴더 안에 배치한 후, adk web을 실행하면 브라우저 UI에서 에이전트와 채팅할 수 있습니다. 전체 설정에는 Python 코드 약 10줄이면 충분합니다.

my_agent라는 폴더를 만들고 두 개의 파일을 추가하세요. 먼저, 에이전트 정의 파일입니다:

# my_agent/agent.py
from google.adk.agents import LlmAgent

root_agent = LlmAgent(
    name="my_assistant",
    model="gemini-2.0-flash",
    instruction="""You are a helpful coding assistant. 
    You explain concepts clearly and provide working code examples.
    Keep responses concise but thorough.""",
    description="A coding assistant that explains concepts and writes code"
)

그다음 에이전트를 export하는 init 파일입니다:

# my_agent/__init__.py
from .agent import root_agent

변수 이름이 중요합니다. ADK는 구체적으로 root_agent를 찾습니다. 이를 누락하면 이유를 설명하지 않는 "agent not found" 오류가 발생합니다.

이제 실행해 보세요. 두 가지 옵션이 있습니다:

# CLI mode -- chat in your terminal
adk run my_agent

# Web UI mode -- opens a browser interface
adk web my_agent

adk web 인터페이스는 실제로 매우 유용합니다. 전체 대화 추적, 에이전트가 호출한 도구, 모델이 받은 입력 및 반환한 출력을 보여줍니다. 에이전트를 위한 Chrome DevTools라고 생각하시면 됩니다. 나중에 다중 에이전트 시스템을 구축할 때 위임 흐름을 이해하는 데 필수적입니다.

동작 방식이 어떻게 변하는지 확인하기 위해 지시문을 수정해 보세요. 해적 역할을 부여하거나 하이쿠 형식으로만 응답하도록 설정해 보세요. 지시문이 동작을 형성하는 방식을 이해하는 것은 이 튜토리얼의 나머지 부분을 위한 기초가 됩니다.

Google ADK 에이전트에 맞춤형 도구 추가하기

ADK 에이전트는 도구를 부여받을 때 진정한 가치를 발휘합니다. 명확한 docstring이 있는 Python 함수를 정의하면 ADK가 이를 자동으로 에이전트가 호출할 수 있는 도구로 변환합니다. docstring은 매우 중요한데, 이는 모델에게 도구의 기능과 사용 시기를 알려주기 때문입니다. ADK에는 Google 검색 및 코드 실행과 같은 내장 도구도 포함되어 있습니다.

도구는 에이전트의 손과 같습니다. 도구가 없으면 에이전트는 대화만 할 수 있지만, 도구가 있으면 데이터베이스 조회, API 호출, 계산 수행 및 외부 시스템과의 상호작용이 가능합니다. 함수 호출이 내부적으로 어떻게 작동하는지 알고 싶다면 별도의 심층 가이드를 참조하세요.

사용자 정의 함수 도구

주식 가격을 조회하는 도구의 실용적인 예시는 다음과 같습니다:

# my_agent/agent.py
from google.adk.agents import LlmAgent

def get_stock_price(ticker: str) -> dict:
    """Get the current stock price for a given ticker symbol.
    
    Args:
        ticker: The stock ticker symbol (e.g., 'AAPL', 'GOOGL', 'MSFT')
    
    Returns:
        A dictionary with the ticker and its current price.
    """
    # In production, you'd call a real API here
    mock_prices = {"AAPL": 198.50, "GOOGL": 175.20, "MSFT": 425.80}
    price = mock_prices.get(ticker.upper(), None)
    if price:
        return {"ticker": ticker.upper(), "price": price, "currency": "USD"}
    return {"error": f"Ticker {ticker} not found"}

root_agent = LlmAgent(
    name="finance_assistant",
    model="gemini-2.0-flash",
    instruction="You help users check stock prices. Use the get_stock_price tool when asked about any stock.",
    tools=[get_stock_price],
    description="A financial assistant that looks up stock prices"
)

타입 힌트와 docstring에 주목하세요. 이들은 선택 사항이 아닙니다. ADK는 이를 사용하여 모델이 보는 도구 스키마를 생성합니다. docstring을 생략하면 모델은 언제 함수를 호출해야 할지 알지 못합니다. 타입 힌트를 생략하면 서명 오류가 발생합니다.

내장 도구 (Google 검색, 코드 실행)

ADK에는 코드 작성 없이 바로 사용할 수 있는 도구가 포함되어 있습니다:

from google.adk.agents import LlmAgent
from google.adk.tools import google_search, code_execution

root_agent = LlmAgent(
    name="research_agent",
    model="gemini-2.0-flash",
    instruction="You research topics using Google Search and can run Python code to analyze data.",
    tools=[google_search, code_execution],
    description="A research agent with search and code execution capabilities"
)

google_search는 에이전트가 실시간으로 웹을 검색할 수 있게 합니다. code_execution은 계산을 실행할 수 있는 샌드박스 처리된 Python 환경을 제공합니다. 이 두 가지だけでも 놀라울 정도로 많은 사용 사례를 커버합니다.

다중 에이전트 시스템: Google ADK 에이전트의 작업 위임 방식

ADK의 다중 에이전트 시스템은 작업을 특화된 하위 에이전트(sub-agents)에게 위임하는 루트 에이전트를 사용합니다. 각 하위 에이전트는 연구, 작성, 코딩 등 하나의 도메인을 처리합니다. 루트 에이전트는 사용자의 요청에 따라 어떤 하위 에이전트를 호출할지 결정합니다. 또한 하나의 에이전트가 함수처럼 다른 에이전트를 호출하는 '에이전트-as-툴(agent-as-tool)' 패턴도 사용할 수 있습니다. Google의 다중 에이전트 시스템 공식 블로그에서는 아키텍처 패턴에 대해 더 깊이 다루고 있습니다.

이를 전문가에게 업무를 위임하는 프로젝트 매니저라고 생각해 보세요. 루트 에이전트는 사용자의 요청을 읽고, 어느 전문가가 처리해야 할지 판단하여 적절히 라우팅합니다. 전문가들은 서로에 대해 알지 못하며, 단순히 자신의 일을 수행하고 결과를 보고합니다.

루트 에이전트 + 하위 에이전트 패턴

연구 에이전트와 작성 에이전트에 위임하는 루트 에이전트의 작동 예시는 다음과 같습니다:

from google.adk.agents import LlmAgent
from google.adk.tools import google_search

# Sub-agent 1: handles research
research_agent = LlmAgent(
    name="researcher",
    model="gemini-2.0-flash",
    instruction="You research topics thoroughly using Google Search. Return factual, well-sourced information.",
    tools=[google_search],
    description="Researches topics and returns factual information"
)

# Sub-agent 2: handles writing
writing_agent = LlmAgent(
    name="writer",
    model="gemini-2.0-flash",
    instruction="You write clear, engaging content based on provided information. Focus on readability and accuracy.",
    description="Writes polished content from research notes"
)

# Root agent: delegates to the right sub-agent
root_agent = LlmAgent(
    name="content_manager",
    model="gemini-2.0-flash",
    instruction="""You manage content creation. 
    - When the user wants information gathered, delegate to the researcher.
    - When the user wants content written or edited, delegate to the writer.
    - You can chain both: research first, then write.""",
    sub_agents=[research_agent, writing_agent],
    description="Manages content creation by delegating to research and writing specialists"
)

각 하위 에이전트의 description 필드는 루트 에이전트가 그들의 기능을 이해하는 방식입니다. 명확한 설명을 작성하세요. 모호한 설명은 잘못된 라우팅 결정을 초래합니다.

에이전트-as-툴 패턴

때로는 한 에이전트가 다른 에이전트를 호출하는 방식을 더 세밀하게 제어하고 싶을 수 있습니다. 에이전트-as-툴 패턴은 하위 에이전트를 호출 가능한 도구로 감싸습니다:

from google.adk.tools import agent_tool

research_tool = agent_tool.AgentTool(agent=research_agent)

root_agent = LlmAgent(
    name="writer_with_research",
    model="gemini-2.0-flash",
    instruction="You write articles. Use the research tool to gather facts before writing.",
    tools=[research_tool],
    description="A writer that can research topics on demand"
)

루트 에이전트가 완전히 제어를 위임하기를 원할 때는 하위 에이전트를 사용하고, 호출하는 에이전트가 주도권을 유지하면서 하위 에이전트의 출력을 입력으로만 사용하고자 할 때는 에이전트-as-툴을 사용하세요. 에이전트가 공유 컨텍스트를 필요로 하는 시스템을 구축 중이라면 에이전트 메모리 아키텍처 종합 가이드를 참조하세요.

워크플로우 에이전트: 순차, 병렬 및 루프

LLM 기반 위임 외에도 ADK는 결정론적 오케스트레이션을 위해 세 가지 유형의 워크플로우 에이전트를 제공합니다. SequentialAgent는 하위 에이전트를 차례대로 실행하고, ParallelAgent는 동시에 실행하며, LoopAgent는 조건이 충족될 때까지 시퀀스를 반복합니다. 이러한 에이전트는 LLM이 결정하도록 맡기는 대신 예측 가능한 실행 순서가 필요할 때 유용합니다.

이 구별은 중요합니다. LLM 기반 위임(위의 sub_agents 패턴)은 모델이 호출 대상을 선택하도록 하지만, 워크플로우 에이전트는 프로그래밍적 제어를 제공합니다. 실행 순서가 사전에 정해진 경우 워크플로우 에이전트를 사용하세요.

from google.adk.agents import SequentialAgent, ParallelAgent, LlmAgent

# Three agents that must run in order
research_agent = LlmAgent(name="researcher", model="gemini-2.0-flash",
    instruction="Research the given topic.", description="Researches topics")
    
draft_agent = LlmAgent(name="drafter", model="gemini-2.0-flash",
    instruction="Write a draft based on the research.", description="Writes drafts")
    
review_agent = LlmAgent(name="reviewer", model="gemini-2.0-flash",
    instruction="Review the draft for accuracy and clarity.", description="Reviews content")

# Pipeline: research -> draft -> review
content_pipeline = SequentialAgent(
    name="content_pipeline",
    sub_agents=[research_agent, draft_agent, review_agent],
    description="Runs a complete content creation pipeline"
)

동시에 실행할 수 있는 독립적인 작업의 경우 ParallelAgent는 실제 시간을 절약해 줍니다:

# Three data fetchers that run concurrently
fetch_news = LlmAgent(name="news_fetcher", model="gemini-2.0-flash",
    instruction="Fetch latest tech news.", description="Fetches news")
    
fetch_stocks = LlmAgent(name="stock_fetcher", model="gemini-2.0-flash",
    instruction="Fetch stock market summary.", description="Fetches stocks")
    
fetch_weather = LlmAgent(name="weather_fetcher", model="gemini-2.0-flash",
    instruction="Fetch weather forecast.", description="Fetches weather")

morning_briefing = ParallelAgent(
    name="morning_briefing",
    sub_agents=[fetch_news, fetch_stocks, fetch_weather],
    description="Gathers morning briefing data in parallel"
)

상태 및 메모리 관리

ADK는 두 수준에서 에이전트 상태를 관리합니다: 세션 상태(대화 중 수집된 사용자 선호도와 같이 대화 내의 데이터)와 메모리 서비스(대화 간에 지속되는 데이터). 세션 상태는 context.state를 통해 액세스되는 간단한 키-값 저장소입니다. 메모리는 프로덕션 환경에서 InMemoryMemoryService나 VertexAIMemoryBankService와 같은 서비스를 사용합니다.

세션 상태가 더 단순합니다. 이는 각 대화에 첨부된 딕셔너리입니다:

from google.adk.agents import LlmAgent

def save_preference(key: str, value: str, context) -> str:
    """Save a user preference to session state.
    
    Args:
        key: The preference name (e.g., 'language', 'theme')
        value: The preference value
        context: The ADK context object
    
    Returns:
        Confirmation message
    """
    context.state[key] = value
    return f"Saved preference: {key} = {value}"

def get_preference(key: str, context) -> str:
    """Retrieve a user preference from session state.
    
    Args:
        key: The preference name to look up
        context: The ADK context object
    
    Returns:
        The preference value or a not-found message
    """
    value = context.state.get(key, "Not set")
    return f"{key} = {value}"

root_agent = LlmAgent(
    name="personalized_assistant",
    model="gemini-2.0-flash",
    instruction="You remember user preferences. Save them when told, recall them when asked.",
    tools=[save_preference, get_preference],
    description="An assistant that remembers user preferences"
)

대화 간 메모리, 즉 에이전트가 지난 화요일의 사용자를 기억하는 종류의 기능을 위해서는 메모리 서비스가 필요합니다:

from google.adk.memory import InMemoryMemoryService

# For development (data lost on restart)
memory_service = InMemoryMemoryService()

# For production, use VertexAIMemoryBankService
# memory_service = VertexAIMemoryBankService(project="your-project")

메모리와 세션 상태는 언제 사용해야 할까요? 단일 대화 내에서의 정보(쇼핑 카트, 현재 작업 컨텍스트)라면 세션 상태를 사용하세요. 대화 사이에서도 유지되어야 하는 정보(사용자 선호도, 과거 상호작용)라면 메모리 서비스를 사용하세요. 프로덕션 패턴에 대해서는 에이전트 메모리 아키텍처 종합 가이드를 확인하세요.

콜백: 에이전트 동작 제어

ADK 콜백은 네 가지 지점에서 에이전트 동작을 가로채고 수정할 수 있게 해줍니다: before_model_callback(LLM 호출 전), after_model_callback(LLM 응답 후), before_tool_callback(도구 실행 전), 그리고 after_tool_callback(도구 결과 후). 이를 입력 검증, 안전 필터링, 로깅 또는 사용자에게 도달하기 전 응답 수정에 활용하세요.

콜백은 가드레일을 추가하는 곳입니다. 이를 에이전트의 미들웨어라고 생각하세요. 모든 요청과 응답이 이를 통과하며, 당신은 무엇이든 검사, 수정 또는 차단할 수 있습니다.

from google.adk.agents import LlmAgent

def safety_filter(callback_context, llm_request):
    """Block requests containing harmful content patterns."""
    user_message = str(llm_request)
    blocked_patterns = ["ignore your instructions", "pretend you are"]
    
    for pattern in blocked_patterns:
        if pattern.lower() in user_message.lower():
            # Return a response directly, skipping the model call
            return {"blocked": True, "reason": "Request matched safety filter"}
    
    # Return None to proceed normally
    return None

def log_tool_usage(callback_context, tool_name, tool_result):
    """Log every tool call for monitoring."""
    print(f"[TOOL LOG] {tool_name}: {tool_result}")
    return None  # Don't modify the result

root_agent = LlmAgent(
    name="safe_assistant",
    model="gemini-2.0-flash",
    instruction="You are a helpful assistant.",
    before_model_callback=safety_filter,
    after_tool_callback=log_tool_usage,
    description="A safety-filtered assistant with tool logging"
)

before_model_callback은 프로덕션 환경에서 가장 중요합니다. 이는 모든 LLM 호출 전에 실행되어 프롬프트 인젝션을 차단하거나 입력을 검증하거나 시스템 컨텍스트를 추가할 기회를 제공합니다. 응답 객체를 반환하면 ADK는 모델 단계를 완전히 건너뜁니다. 요청을 통과시키려면 None을 반환하세요. 더 많은 패턴은 LLM 안전 가드레일을 위한 심층 패턴을 참조하세요.

ADK 에이전트 테스트 및 평가

ADK에는 두 가지 평가자 유형을 갖춘 내장 평가 프레임워크가 포함되어 있습니다. ResponseEvaluator는 에이전트의 최종 답변이 정확한지 확인하고, TrajectoryEvaluator는 에이전트가 올바른 단계로 진행했으며 올바른 순서로 올바른 도구를 호출했는지 검증합니다. JSON 파일로 테스트 케이스를 작성하고 pytest로 실행하여 배포 전 회귀(regression)를 잡으세요.

왜 에이전트 테스트에 신경 써야 할까요?因为它们是非确定性的(non-deterministic). 동일한 입력이 다른 출력을 생성할 수 있으며, 지시문의 작은 변경이 도구 호출을 미묘하게 깨뜨릴 수 있습니다. 우리의 경험상, 최종 출력 품질만으로 테스트된 에이전트보다 궤적 평가(trajectory evaluation)를 통과한 에이전트가 프로덕션 환경에서 훨씬 더 신뢰할 수 있습니다. 광범위한 평가 전략은 LLM 평가 전략 가이드를 참조하세요.

테스트 케이스는 JSON 파일에 작성합니다:

[
  {
    "input": "What's the stock price of AAPL?",
    "expected_output": "198.50",
    "expected_trajectory": [
      {"tool_name": "get_stock_price", "args": {"ticker": "AAPL"}}
    ]
  },
  {
    "input": "Compare AAPL and GOOGL prices",
    "expected_output": "AAPL.*198.*GOOGL.*175",
    "expected_trajectory": [
      {"tool_name": "get_stock_price", "args": {"ticker": "AAPL"}},
      {"tool_name": "get_stock_price", "args": {"ticker": "GOOGL"}}
    ]
  }
]

그런 다음 pytest로 평가를 실행하세요. ADK Python 저장소에는 전체 평가 API 참조가 있습니다:

# test_agent.py
import pytest
from google.adk.evaluation import ResponseEvaluator, TrajectoryEvaluator

def test_stock_agent_response():
    evaluator = ResponseEvaluator(agent=root_agent)
    results = evaluator.evaluate("test_cases.json")
    
    assert results.pass_rate >= 0.8, f"Response pass rate too low: {results.pass_rate}"

def test_stock_agent_trajectory():
    evaluator = TrajectoryEvaluator(agent=root_agent)
    results = evaluator.evaluate("test_cases.json")
    
    assert results.pass_rate >= 0.9, f"Trajectory pass rate too low: {results.pass_rate}"

pytest test_agent.py -v로 실행하세요. 중요도에 따라 임계값을 설정하세요. 창의적 글쓰기 에이전트라면 응답 정확도 80%도 괜찮을 수 있지만, 금융 데이터를 처리하는 경우라면 95% 이상이 필요할 것입니다.

Google ADK 에이전트를 프로덕션에 배포하기

한 번의 명령어로 ADK 에이전트를 Google Cloud Run에 배포하세요: adk deploy cloud_run --project YOUR_PROJECT --region us-central1. ADK는 코드를 패키징하고, 컨테이너를 빌드하며, 서버리스 엔드포인트를 실행합니다. 관리형 호스팅을 위해서는 Vertex AI Agent Engine을 사용하세요. 커스텀 인프라의 경우 ADK는 Docker 컨테이너화도 지원합니다.

우리는 내부 도구를 위해 Cloud Run에 ADK 에이전트를 배포했으며, 콜드 스타트 시간이 놀랍도록 빠릅니다. 기본 에이전트의 경우 3초 미만입니다. 프로덕션 시스템을 위해서는 프로덕션 에이전트 모니터링 도구와 함께 배포하는 것을 고려하세요.

Cloud Run에 배포 (대부분의 경우 권장)

Cloud Run이 가장 간단한 경로입니다. 한 번의 명령어로 HTTPS 엔드포인트와 함께 에이전트가_live_ 상태가 됩니다:

adk deploy cloud_run \
  --project your-gcp-project-id \
  --region us-central1 \
  --service-name my-agent-service \
  --with_ui

--with_ui 플래그는 에이전트와 함께 ADK Web 인터페이스를 배포하므로, 프로덕션 환경에서 테스트할 수 있는 브라우저 기반 채팅을 얻을 수 있습니다. 백그라운드에서 ADK는 컨테이너 이미지를 빌드하고, Google Artifact Registry에 푸시하며, Cloud Run 서비스를 생성합니다. 전체 배포 흐름은 ADK용 Google Cloud Run 퀵스타트에 문서화되어 있습니다.

커스텀 인프라를 위한 최소한의 Dockerfile은 다음과 같습니다:

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8080
CMD ["adk", "api_server", "--port", "8080", "my_agent"]

대안: Vertex AI Agent Engine

관리형 확장, 모니터링 및 버전 관리가 필요한 엔터프라이즈 팀의 경우 Vertex AI Agent Engine이 인프라를 완전히 처리합니다. 유연성과 편의성을 트레이드오프하며, 관리할 컨테이너가 없고 자동 확장 및 내장 분석 기능이 제공됩니다.

비용 고려 사항

알아두어야 할 실제 숫자는 다음과 같습니다:

• Gemini API 무료 티어: 분당 15회 요청, 하루 100만 토큰. 개발 및 가벼운 데모에 충분합니다.
• Gemini 2.0 Flash (유료): 입력 토큰 100만 개당 $0.10, 출력 토큰 100만 개당 $0.40. 프로덕션용으로 충분히 저렴합니다.
• Cloud Run 무료 티어: 월 200만 회 요청, 360,000 GB-초의 컴퓨팅 리소스. 하루 1,000회 요청을 처리하는 기본 에이전트는 무료 티어 범위 내에 잘 머무릅니다.
• 최적화 팁: 간단한 라우팅이나 포맷팅을 수행하는 하위 에이전트에는 gemini-2.0-pro가 아닌 gemini-2.0-flash를 사용하세요. 복잡한 추론을 수행하는 에이전트에만 더 강력한 모델을 예약하세요.

Techsy의 AI 에이전트 개발 접근 방식

Techsy에서는 ADK, LangGraph, CrewAI를 사용하여 고객사를 위한 다중 에이전트 시스템을 구축해 왔습니다. 프레임워크 선택은 귀하의 스택에 따라 달라집니다. 이미 Google Cloud를 사용 중이라면 ADK는 많은 통합 마찰을 제거해 줍니다. 첫날부터 다중 공급자 LLM 지원이 필요하다면 LangGraph가 더 큰 유연성을 제공합니다.

우리의 일반적인 참여 과정은 아키텍처 컨설팅으로 시작하여 사용 사례를 적절한 에이전트 패턴에 매핑한 후, 프로토타입 개발 및 Cloud Run 배포로 이어집니다. 우리는 나중에 리팩토링하는 대신 upfront에 아키텍처를 올바르게 설계함으로써 팀이 2-3주를 절약할 수 있다는 것을 발견했습니다.

팀을 위한 AI 에이전트를 구축하시나요? 무료 상담 받기를 통해 적절한 프레임워크와 배포 전략을 선택하도록 도와드리겠습니다.

일반적인 오류 및 문제 해결

ADK를 처음 시작할 때 우리가 가장 자주 마주치는 오류들입니다. 디버깅 시간을 절약하세요:

디버깅 팁: 여기서 adk web은 당신의 가장 좋은 친구입니다. 실시간으로 전체 대화 추적, 모든 모델 호출, 도구 호출 및 에이전트 위임을 보여줍니다. 다중 에이전트 시스템에서 문제가 발생하면 웹 UI는 체인이 정확히 어디에서 끊어졌는지 보여줍니다.

FAQ

Google ADK란 무엇인가요?

Google의 Agent Development Kit(ADK)는 AI 에이전트를 구축, 평가 및 배포하기 위한 오픈소스 Python 프레임워크입니다. Google Gemini 모델에 최적화되어 있지만 LiteLLM 통합을 통해 100개 이상의 LLM을 지원합니다. ADK의 핵심 강점은 내장된 도구, 개발 UI 및 한 번의 명령어로 Cloud Run에 배포할 수 있는 네이티브 다중 에이전트 오케스트레이션입니다.

Google ADK는 무료로 사용할 수 있나요?

예. ADK 자체는 Apache 2.0 라이선스 하에 오픈소스입니다. Gemini API 키가 필요하며, 이는 분당 15회 요청과 하루 100만 토큰을 제공하는 무료 티어가 있습니다. 클라우드 배포 비용은 호스팅 선택에 따라 다르며, Cloud Run의 무료 티어는 월 200만 회 요청을 커버합니다.

Google ADK와 LangChain의 차이점은 무엇인가요?

ADK는 네이티브 다중 에이전트 오케스트레이션과 내장된 배포 도구를 갖춘 Gemini 최적화의 Google 견해(opinionated) 프레임워크입니다. LangChain은 모델에 구애받지 않으며 더 넓은 타사 통합을 제공하지만 복잡성이 훨씬 높습니다. ADK는 빠른 배포를 원하는 Gemini 우선 팀에 적합하며, LangChain은 최대 유연성이 필요한 다중 공급자 설정에 적합합니다.

Google ADK는 다중 에이전트 시스템을 지원하나요?

예, 그리고 이는 ADK의 대표 기능입니다. 사용자 요청에 따라 특화된 하위 에이전트에 위임하는 루트 에이전트를 생성합니다. ADK는 또한 결정론적 워크플로우 오케스트레이션을 위해 SequentialAgent, ParallelAgent 및 LoopAgent를 제공합니다. 에이전트-as-툴 패턴을 사용하면 에이전트가 다른 에이전트를 호출 가능한 함수처럼 호출할 수 있습니다.

Google ADK 에이전트를 어떻게 배포하나요?

Google Cloud Run에 서버리스 배포를 위해 adk deploy cloud_run --project YOUR_PROJECT --region us-central1을 실행하세요. 브라우저 기반 채팅 인터페이스를 포함하려면 --with_ui를 추가하세요. 관리형 호스팅을 위해 Vertex AI Agent Engine에 배포하거나, 커스텀 인프라를 위해 Docker 컨테이너를 빌드할 수도 있습니다.

Google ADK는 Gemini 이외의 모델을 사용할 수 있나요?

예. ADK는 LiteLLM 통합을 통해 Anthropic Claude, OpenAI GPT-4, Meta Llama 및 Mistral을 포함한 100개 이상의 모델을 지원합니다. 모델 매개변수를 LiteLLM 모델 문자열로 설정하세요. 예를 들어, litellm/anthropic/claude-3-sonnet 또는 litellm/openai/gpt-4o입니다. Gemini 모델은 LiteLLM 접두사 없이 네이티브로 작동합니다.

ADK Web UI란 무엇인가요?

adk web your_agent_folder로 실행되는 브라우저 기반 디버깅 인터페이스입니다. 실시간 대화 추적, 도구 호출, 에이전트 위임 체인 및 상태 변화를 표시합니다. 웹 UI는 어느 하위 에이전트가 각 요청을 처리했는지 정확히 보여주므로 다중 에이전트 시스템 디버깅에 필수적입니다.

Google ADK는 MCP(Model Context Protocol)를 지원하나요?

예. ADK는 네이티브 Model Context Protocol 지원을 갖추고 있어, 에이전트가 외부 도구 및 데이터 소스를 위해 MCP 호환 도구 서버에 연결할 수 있게 합니다.这使得 ADK 에이전트가 성장하는 MCP 생태계와 상호 운용 가능해집니다. 프로토콜에 대한 배경 지식은 MCP 가이드를 참조하세요.

ADK 에이전트를 어떻게 테스트하나요?

ADK에는 내장된 평가자가 포함되어 있습니다. 예상 답변 against 출력 품질을 확인하는 ResponseEvaluator와 에이전트가 올바른 순서로 올바른 도구를 호출했는지 검증하는 TrajectoryEvaluator입니다. 입력, 예상 출력 및 예상 도구 호출 시퀀스를 정의하는 JSON 파일로 테스트 케이스를 작성한 후 pytest로 실행하세요.

Google ADK는 어떤 Python 버전을 요구하나요?

ADK는 Python 3.9 이상을 요구합니다. ADK가 타입 힌트를 사용하여 도구 스키마를 생성하기 때문에 완전한 타입 힌팅 지원을 위해 Python 3.10+가 권장됩니다. Python 3.11 또는 3.12는 에이전트 워크로드에 의미 있는 성능 향상도 제공합니다. pip install google-adk로 설치하세요.