Google ADK 완벽 가이드 2026: 코드로 지능형 AI 에이전트 구축

---

title: Google ADK 완벽 가이드 2026: 코드로 지능형 AI 에이전트 구축 date: 2026-03-27 authors: [kevinpeng] slug: google-adk-agent-development-kit-2026-ko categories: - AI 어시스턴트 tags: - Google ADK - AI 에이전트 - 오픈소스 프레임워크 - Python cover: https://res.makeronsite.com/freeaitool.com/047-google-adk-agent-development-kit-2026-cover.webp description: Google ADK (Agent Development Kit) 2026 완벽 튜토리얼: 설치 설정, 핵심 개념, 코드 예시, 모범 사례를 통해 개발자가 프로덕션 수준의 AI 에이전트 애플리케이션을 빠르게 구축할 수 있도록 지원합니다. lang: ko

---

Google ADK 란?

Google ADK (Agent Development Kit) 는 AI 에이전트를 실제 애플리케이션에 통합하고자 하는 개발자를 위해 Google 에서 출시한 오픈소스 AI 에이전트 개발 프레임워크입니다. LangChain, LlamaIndex 등의 프레임워크와 달리, ADK 는 "코드 우선"(code-first) 설계 철학을 채택하여 에이전트의 동작이 기존 소프트웨어처럼 예측 가능하고 테스트 가능하도록 합니다.

핵심 기능

• 코드 우선: 순수 Python 으로 에이전트 동작 정의, 복잡한 YAML 설정 불필요
• 타입 안전: Python 타입 힌트를 최대한 활용하여 IDE 자동 완성 및 오류 검사 제공
• 테스트 용이성: 에이전트 로직을 일반 함수처럼 유닛 테스트 가능
• 프로덕션 준비: 로깅, 모니터링, 오류 핸들링 등 프로덕션 환경 필수 기능 내장
• 멀티 모델 지원: Gemini, GPT-4, Claude 등 주요 대규모 언어 모델 지원

적용 시나리오

• 고객 서비스 챗봇
• 자동화 워크플로우 어시스턴트
• 데이터 분석 및 보고서 생성
• 코드 리뷰 및 프로그래밍 보조
• 기업 내부 지식 QA 시스템

설치 및 설정

환경 요구사항

• Python 3.10 이상
• pip 패키지 관리자
• Google Cloud 계정 (Gemini 모델 사용 시)

설치 단계

# 가상 환경 생성 (권장)
python3 -m venv adk-env
source adk-env/bin/activate  # Linux/macOS
# adk-env\Scripts\activate  # Windows

# Google ADK 설치
pip install google-adk

# 추가 의존성 설치 (필요 시)
pip install google-adk[cli]  # CLI 도구 포함
pip install google-adk[testing]  # 테스트 도구 포함

API 키 설정

# 방법 1: 환경 변수 사용 (개발 용도로 권장)
export GEMINI_API_KEY="your-api-key-here"

# 방법 2: Google Cloud 인증 파일 사용
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

# 방법 3: 코드에서 직접 설정 (프로덕션 환경 비권장)

핵심 개념

1. Agent (에이전트)

에이전트는 ADK 의 핵심 컴포넌트로, 사용자 입력을 수신하고 도구를 호출하며 응답을 생성하는 역할을 담당합니다.

from google.adk import Agent
from google.adk.models import Gemini

# 기본 에이전트 생성
agent = Agent(
    name="customer_support",
    model=Gemini(model="gemini-2.0-flash"),
    instruction="당신은 제품 문제 해결을 도와주는 전문 고객 지원 어시스턴트입니다.",
)

2. Tools (도구)

도구는 에이전트가 구체적인 작업을 수행하기 위해 호출할 수 있는 외부 함수입니다.

from google.adk import Tool
from google.adk.tools import FunctionTool

# 도구 함수 정의
def search_knowledge_base(query: str) -> str:
    """지식 베이스에서 관련 정보 검색"""
    # 실제 구현에서는 데이터베이스나 API 를 호출
    return f"'{query}' 검색 결과..."

# 도구 생성
search_tool = FunctionTool(
    func=search_knowledge_base,
    name="search_kb",
    description="제품 지식 베이스 검색",
)

# 에이전트에 도구 추가
agent.tools = [search_tool]

3. Sessions (세션)

세션은 사용자와 에이전트 간의 대화 기록을 관리하며, 멀티턴 대화를 지원합니다.

from google.adk import Session

# 세션 생성
session = Session(
    agent=agent,
    user_id="user_123",
)

# 메시지 전송
response = await session.send("제품이 켜지지 않습니다. 어떻게 해야 하나요?")
print(response.text)

4. Events (이벤트)

이벤트 시스템은 비동기 메시지 처리와 스트리밍 응답을 지원합니다.

from google.adk import Event

async def handle_event(event: Event):
    if event.type == "user_message":
        response = await session.send(event.content)
        await event.reply(response.text)

실전 예시

예시 1: 간단한 QA 봇

from google.adk import Agent, Session, Runner
from google.adk.models import Gemini

# 에이전트 생성
agent = Agent(
    name="faq_bot",
    model=Gemini(model="gemini-2.0-flash"),
    instruction="""당신은 제품 관련 질문에 답변하는 FAQ 봇입니다.
    - 답변은 간결하고 명확하게 유지
    - 답을 모르면 정직하게 알림
    - 관련 도움말 조언 제공""",
)

# 인터랙티브 세션 실행
async def main():
    runner = Runner(agent=agent)
    await runner.run_interactive()

# python3 faq_bot.py

예시 2: 도구를 사용한 데이터 분석 어시스턴트

from google.adk import Agent, Tool
from google.adk.tools import FunctionTool
from google.adk.models import Gemini
import pandas as pd

# 데이터 분석 도구 정의
def load_csv(file_path: str) -> dict:
    """CSV 파일을 로드하고 기본 정보 반환"""
    df = pd.read_csv(file_path)
    return {
        "rows": len(df),
        "columns": list(df.columns),
        "dtypes": df.dtypes.astype(str).to_dict(),
    }

def calculate_stats(file_path: str, column: str) -> dict:
    """지정된 열의 통계 정보 계산"""
    df = pd.read_csv(file_path)
    numeric_col = pd.to_numeric(df[column], errors="coerce")
    return {
        "mean": float(numeric_col.mean()),
        "median": float(numeric_col.median()),
        "std": float(numeric_col.std()),
        "min": float(numeric_col.min()),
        "max": float(numeric_col.max()),
    }

# 도구 생성
tools = [
    FunctionTool(func=load_csv, name="load_csv", description="CSV 파일 로드"),
    FunctionTool(func=calculate_stats, name="calc_stats", description="통계 정보 계산"),
]

# 에이전트 생성
agent = Agent(
    name="data_analyst",
    model=Gemini(model="gemini-2.0-flash"),
    instruction="당신은 데이터 분석 어시스턴트로, CSV 데이터 파일 분석을 도와줍니다.",
    tools=tools,
)

예시 3: 다중 에이전트 협업 시스템

from google.adk import Agent, Runner
from google.adk.models import Gemini

# 여러 전문 에이전트 생성
researcher = Agent(
    name="researcher",
    model=Gemini(model="gemini-2.0-flash"),
    instruction="당신은 정보 수집과 연구를 담당하며, 상세한 사실과 데이터를 제공합니다.",
)

writer = Agent(
    name="writer",
    model=Gemini(model="gemini-2.0-flash"),
    instruction="당신은 연구 결과를 구조화되고 읽기 쉬운 보고서로 정리하는 역할을 담당합니다.",
)

reviewer = Agent(
    name="reviewer",
    model=Gemini(model="gemini-2.0-flash"),
    instruction="당신은 보고서의 품질을 검토하여 정확성과 완전성을 확인하는 역할을 담당합니다.",
)

# 워크플로우로 여러 에이전트 오케스트레이션
async def collaborative_workflow(user_query: str):
    # 연구 단계
    research_result = await researcher.run(user_query)

    # 작성 단계
    draft = await writer.run(f"다음 연구 결과를 바탕으로 보고서를 작성하세요: {research_result}")

    # 검토 단계
    final_report = await reviewer.run(f"다음 보고서를 검토하고 개선하세요: {draft}")

    return final_report

고급 기능

스트리밍 응답

from google.adk import Agent, Session
from google.adk.models import Gemini

agent = Agent(
    name="streaming_bot",
    model=Gemini(model="gemini-2.0-flash"),
)

session = Session(agent=agent)

# 스트리밍 응답 처리
async for chunk in session.send_stream("AI 에 대한 이야기를 들려주세요"):
    print(chunk.text, end="", flush=True)

커스텀 미들웨어

from google.adk import Middleware

class LoggingMiddleware(Middleware):
    """모든 요청과 응답을 기록하는 로깅 미들웨어"""

    async def on_request(self, request):
        print(f"[REQUEST] {request.user_id}: {request.content}")
        return request

    async def on_response(self, response):
        print(f"[RESPONSE] {response.text[:100]}...")
        return response

# 미들웨어 추가
agent.middleware = [LoggingMiddleware()]

오류 핸들링 및 재시도

from google.adk import Agent
from google.adk.models import Gemini
from google.adk.retry import RetryConfig

agent = Agent(
    name="robust_bot",
    model=Gemini(model="gemini-2.0-flash"),
    retry_config=RetryConfig(
        max_retries=3,
        retry_delay=1.0,
        retry_on=[TimeoutError, ConnectionError],
    ),
)

모범 사례

1. 프롬프트 엔지니어링

# 좋은 예: 명확하고 구체적인 지시
agent = Agent(
    instruction="""당신은 전문 기술 지원 어시스턴트입니다.

    답변 규칙:
    1. 먼저 사용자의 문제를 이해했는지 확인
    2. 단계별 해결 방안 제공
    3. 문제가 복잡하면人工 지원 문의 제안
    4. 친절하고 전문적인 어조 유지""",
)

# 피해야 할 예: 모호하고 포괄적인 지시
agent = Agent(
    instruction="사용자의 문제 해결",  # 너무 모호
)

2. 도구 설계

# 좋은 예: 단일 책임, 명확한 문서화
def get_order_status(order_id: str) -> dict:
    """
    주문 상태 조회

    Args:
        order_id: 주문 번호 (형식: ORD-XXXXXX)

    Returns:
        status, estimated_delivery 등의 정보를 포함하는 딕셔너리
    """
    pass

# 피해야 할 예: 다기능, 과도한 파라미터
def handle_order(action: str, order_id: str, user_id: str, 
                 items: list, address: dict, payment: dict) -> dict:
    # 너무 복잡해서 유지보수 어려움
    pass

3. 테스트 전략

import pytest
from google.adk import Agent, Session

@pytest.fixture
def test_agent():
    return Agent(
        name="test_bot",
        model=Gemini(model="gemini-2.0-flash"),
        instruction="당신은 테스트 어시스턴트입니다",
    )

@pytest.mark.asyncio
async def test_agent_response(test_agent):
    session = Session(agent=test_agent)
    response = await session.send("안녕하세요")
    assert response.text is not None
    assert len(response.text) > 0

4. 성능 최적화

# 커넥션 풀 사용
from google.adk.models import Gemini

model = Gemini(
    model="gemini-2.0-flash",
    max_concurrent_requests=10,
    timeout=30.0,
)

# 자주 사용되는 응답 캐싱
from functools import lru_cache

@lru_cache(maxsize=100)
def get_faq_answer(question_hash: str) -> str:
    # 캐시 로직
    pass

배포 가이드

로컬 개발 서버

from google.adk import Agent, Runner
from google.adk.models import Gemini

agent = Agent(
    name="web_bot",
    model=Gemini(model="gemini-2.0-flash"),
)

# 웹 서버 시작
runner = Runner(agent=agent)
runner.serve(host="0.0.0.0", port=8000)

# 접속 http://localhost:8000

Docker 배포

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["python", "main.py"]

Google Cloud Run

# cloud-run.yaml
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: adk-agent
spec:
  template:
    spec:
      containers:
      - image: gcr.io/your-project/adk-agent
        env:
        - name: GEMINI_API_KEY
          valueFrom:
            secretKeyRef:
              name: api-keys
              key: gemini

자주 묻는 질문

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

A: ADK 는 코드 우선과 타입 안전을 중시하며, 프로그래밍 경험이 있는 개발자에게 적합합니다. LangChain 은 풍부한 사전 빌드 컴포넌트와 YAML 설정을 제공하여 빠른 프로토타이핑에 적합합니다.

Q2: 어떤 대규모 언어 모델을 지원하나요?

A: Google Gemini 시리즈 모델을 기본적으로 지원합니다. 커스텀 Provider 를 통해 OpenAI GPT, Anthropic Claude, 로컬 모델 등도 통합할 수 있습니다.

Q3: 에이전트 동작을 디버깅하려면 어떻게 해야 하나요?

A: ADK 내장 디버그 모드를 사용합니다:

from google.adk import Runner

runner = Runner(agent=agent, debug=True)
# 상세 로그가 콘솔에 출력됩니다

Q4: 프로덕션 환경에서 주의할 점은 무엇인가요?

A: - 환경 변수를 사용하여 API 키 관리 - 적절한レート 제한 설정 - 로깅 및 모니터링 구현 - 오류 핸들링 및 재시도 메커니즘 추가 - 충분한 부하 테스트 수행

요약

Google ADK 는 개발자가 프로덕션 수준의 AI 에이전트 애플리케이션을 구축할 수 있는 강력하고 유연한 도구를 제공합니다. 코드 우선 설계 철학으로 인해 에이전트 개발은 기존 소프트웨어 엔지니어링 관행에 더 가까워져 테스트, 유지보수, 확장이 용이해집니다.

다음 단계

1. 공식 문서 읽기
2. GitHub 샘플 저장소 참조
3. 개발자 커뮤니티 가입
4. 첫 번째 에이전트 프로젝트 구축 도전

---

관련 리소스:

• Google ADK 공식 문서
• GitHub 저장소
• 샘플 코드
• Gemini API 문서
• 개발자 커뮤니티