Google ADK 실전 가이드 — Python·TypeScript로 AI 에이전트 만들기, LangChain·Mastra와 비교

설치 및 환경 설정
# 가상환경 생성 후 설치
python -m venv .venv && source .venv/bin/activate
pip install google-adk

# API 키 설정
export GOOGLE_API_KEY="your-gemini-api-key"

# 프로젝트 스캐폴딩 (선택)
adk create my_agent
# → my_agent/__init__.py, my_agent/agent.py, .env 생성

my_agent/agent.py — 기본 에이전트 정의
from google.adk.agents import Agent

# 커스텀 도구 정의
def get_weather(city: str) -> dict:
    """특정 도시의 현재 날씨를 반환한다."""
    # 실제로는 외부 API 호출
    return {"city": city, "temp_c": 22, "condition": "맑음"}

def search_docs(query: str) -> str:
    """내부 문서에서 관련 정보를 검색한다."""
    # 실제로는 벡터 DB 검색
    return f"'{query}'에 관한 문서 검색 결과..."

# 에이전트 정의
root_agent = Agent(
    name="assistant",
    model="gemini-2.0-flash",          # 또는 다른 모델
    description="날씨 조회와 문서 검색을 도와주는 어시스턴트",
    instruction="사용자 질문에 제공된 도구를 활용해 정확하게 답변해라. "
                "확실하지 않은 정보는 추측하지 말고 솔직하게 말해라.",
    tools=[get_weather, search_docs],   # 함수를 그대로 전달
)

로컬 실행 — 웹 UI 또는 CLI
# 방법 1: 웹 UI (adk web) — 브라우저에서 인터랙티브 테스트
adk web
# → http://localhost:8000 에서 채팅 인터페이스 제공

# 방법 2: CLI 실행
adk run my_agent

# 방법 3: Python 코드에서 직접 실행
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService

session_service = InMemorySessionService()
runner = Runner(
    agent=root_agent,
    app_name="my_agent",
    session_service=session_service
)

# 단일 쿼리 실행
from google.genai import types
async def run():
    session = await session_service.create_session(
        app_name="my_agent", user_id="user_1"
    )
    async for event in runner.run_async(
        user_id="user_1",
        session_id=session.id,
        new_message=types.Content(
            role="user",
            parts=[types.Part(text="서울 날씨 알려줘")]
        )
    ):
        if event.is_final_response():
            print(event.response.text)

TypeScript 설치 및 기본 에이전트
npm install @google/adk

# .env 파일
# GOOGLE_API_KEY=your-gemini-api-key

agent.ts — TypeScript 에이전트 정의
import { Agent, InMemorySessionService, Runner } from '@google/adk/agents';
import { Content, Part } from '@google/genai';

// 도구 정의 — JSDoc으로 설명을 명시해야 모델이 도구를 올바르게 사용한다
function getWeather(city: string): Record<string, unknown> {
  /** 특정 도시의 현재 날씨를 반환한다 */
  return { city, temp_c: 22, condition: 'sunny' };
}

// 에이전트 생성
const agent = new Agent({
  name: 'weather_agent',
  model: 'gemini-2.0-flash',
  description: '날씨 정보를 제공하는 에이전트',
  instruction: '사용자가 요청한 도시의 날씨를 getWeather 도구로 조회해 답변해라.',
  tools: [getWeather],
});

// 실행
async function main() {
  const sessionService = new InMemorySessionService();
  const runner = new Runner({
    agent,
    appName: 'weather_app',
    sessionService,
  });

  const session = await sessionService.createSession({
    appName: 'weather_app',
    userId: 'user_1',
  });

  const events = runner.runAsync({
    userId: 'user_1',
    sessionId: session.id,
    newMessage: new Content({
      role: 'user',
      parts: [new Part({ text: '서울 날씨 알려줘' })],
    }),
  });

  for await (const event of events) {
    if (event.isFinalResponse()) {
      console.log(event.response?.text);
    }
  }
}

main();

multi_agent/agent.py — 멀티 에이전트 구성
from google.adk.agents import Agent

# 전문 에이전트 1: 날씨 조회
weather_agent = Agent(
    name="weather_specialist",
    model="gemini-2.0-flash",
    description="날씨 정보 조회 전문 에이전트. 도시별 날씨, 예보, 기상 특보를 제공한다.",
    instruction="날씨 관련 질문에만 답변해라. 다른 주제는 다룰 수 없다고 명시해라.",
    tools=[get_weather_api],
)

# 전문 에이전트 2: 문서 검색
docs_agent = Agent(
    name="docs_specialist",
    description="내부 문서 및 지식베이스 검색 전문 에이전트.",
    model="gemini-2.0-flash",
    instruction="문서 검색 결과를 요약해서 제공해라. 출처를 항상 명시해라.",
    tools=[search_vector_db],
)

# 오케스트레이터 — 서브 에이전트를 도구로 사용
root_agent = Agent(
    name="orchestrator",
    model="gemini-2.0-flash",
    description="사용자 요청을 분석해 적절한 전문 에이전트에게 위임하는 오케스트레이터",
    instruction=(
        "사용자 요청을 분석해라. "
        "날씨 관련이면 weather_specialist에게 위임해라. "
        "문서 검색이면 docs_specialist에게 위임해라. "
        "결과를 통합해서 최종 답변을 작성해라."
    ),
    # 서브 에이전트를 도구로 등록
    agents=[weather_agent, docs_agent],
)

tests/eval_dataset.json — 평가 케이스 정의
[
  {
    "query": "서울 날씨 알려줘",
    "expected_tool_use": [
      {
        "tool_name": "get_weather",
        "tool_input": { "city": "서울" }
      }
    ],
    "reference": "서울의 현재 날씨 정보를 get_weather 도구로 조회해 제공해야 한다."
  },
  {
    "query": "Python asyncio 문서 찾아줘",
    "expected_tool_use": [
      {
        "tool_name": "search_docs",
        "tool_input": { "query": "Python asyncio" }
      }
    ],
    "reference": "asyncio 관련 문서를 검색해 출처와 함께 제공해야 한다."
  }
]

평가 실행 및 CI 설정
# 로컬 평가 실행
adk eval my_agent tests/eval_dataset.json

# 출력 예시:
# Evaluating 2 test cases...
# ✓ Test 1: tool_trajectory_avg_score=0.95, response_quality=0.88
# ✓ Test 2: tool_trajectory_avg_score=1.00, response_quality=0.92
# Overall: PASS (threshold: 0.8)

# --- .github/workflows/eval.yml ---
# name: Agent Evaluation
# on: [pull_request]
# jobs:
#   eval:
#     runs-on: ubuntu-latest
#     steps:
#       - uses: actions/checkout@v4
#       - run: pip install google-adk
#       - run: adk eval my_agent tests/eval_dataset.json --threshold 0.8

Vertex AI 배포 절차
# 1. gcloud 인증
gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID

# 2. Vertex AI API 활성화
gcloud services enable aiplatform.googleapis.com

# 3. 배포
adk deploy cloud_run my_agent \
  --project YOUR_PROJECT_ID \
  --region us-central1 \
  --service-name my-agent-service

# 또는 Vertex AI Agent Engine 직접 배포 (관리형 런타임)
adk deploy agent_engine my_agent \
  --project YOUR_PROJECT_ID \
  --region us-central1

# 4. 배포된 에이전트 호출 테스트
adk run --endpoint https://YOUR-ENDPOINT.run.app