google/adk-python

유연성과 제어력을 갖춘 정교한 AI 에이전트를 구축, 평가 및 배포하기 위한 오픈 소스 코드 우선(code-first) Python 프레임워크.

Agent Development Kit (ADK)는 소프트웨어 개발 원칙을 AI 에이전트 생성에 적용하는 유연하고 모듈식 프레임워크입니다. 간단한 작업부터 복잡한 시스템까지, 에이전트 워크플로우를 구축, 배포 및 오케스트레이션하는 과정을 단순화하도록 설계되었습니다. Gemini에 최적화되어 있지만, ADK는 모델에 구애받지 않고(model-agnostic), 배포 환경에 구애받지 않으며(deployment-agnostic), 다른 프레임워크와도 호환됩니다.

워크플로우 런타임 (Workflow Runtime): 라우팅, 팬아웃/팬인(fan-out/fan-in), 루프, 재시도(retry), 상태 관리(state management), 동적 노드(dynamic nodes), 인간 참여형(human-in-the-loop) 및 중첩 워크플로우를 지원하는 에이전트 애플리케이션을 위한 그래프 기반 실행 엔진.

태스크 API (Task API): 다중 턴 태스크 모드, 단일 턴 제어 출력, 혼합 위임 패턴(mixed delegation patterns), 인간 참여형, 워크플로우 노드로 사용되는 태스크 에이전트를 통한 구조화된 에이전트 간 위임.

모듈식 멀티 에이전트 시스템 (Modular Multi-Agent Systems): 여러 전문 에이전트를 유연한 계층 구조로 조합하여 확장 가능한 애플리케이션을 설계합니다.

풍부한 도구 생태계 (Rich Tool Ecosystem): 미리 구축된 도구, 사용자 정의 함수, OpenAPI 사양, MCP 도구를 활용하거나 기존 도구를 통합하여 에이전트에게 다양한 기능을 부여하며, 모든 것이 Google 생태계와의 긴밀한 통합을 위해 설계되었습니다.

코드 우선 개발 (Code-First Development): 에이전트 로직, 도구 및 오케스트레이션을 Python에 직접 정의하여 궁극적인 유연성, 테스트 용이성 및 버전 관리를 확보합니다.

에이전트 설정 (Agent Config): 코딩 없이 에이전트를 구축할 수 있습니다. Agent Config 기능을 확인해 보세요.

도구 확인 (Tool Confirmation): 명시적 확인과 사용자 정의 입력을 통해 도구 실행을 보호하는 인간 참여형(HITL) 흐름입니다.

어디서든 배포 (Deploy Anywhere): Cloud Run에서 에이전트를 쉽게 컨테이너화하고 배포하거나 Vertex AI Agent Engine으로 원활하게 확장할 수 있습니다.

최신 안정 버전의 ADK는 pip을 사용하여 설치할 수 있습니다.

:
pip install google-adk

요구 사항: Python 3.11 이상.

전이 의존성(transitive dependency) 보호를 위해 전용 제약 파일(constraints files)과 함께 설치하는 것을 권장합니다 (Python 3.11부터 3.14까지).

사용하는 Python 버전에 맞는 제약 파일을 선택하세요:

# 예시: Python 3.11의 경우
curl -o constraints-3.11.txt https://raw.githubusercontent.com/google/adk-python/main/constraints-3.11.txt
pip install google-adk -c constraints-3.11.txt
...

선택적 통합(optional integrations)을 설치하려면 다음 명령어를 사용할 수 있습니다:

pip install "google-adk[extensions]"

릴리스 주기는 대략 격주입니다.

버그 수정 및 새로운 기능은 먼저 GitHub의 main 브랜치에 병합됩니다. 아직 공식 PyPI 릴리스에 포함되지 않은 변경 사항에 접근해야 하는 경우, main 브랜치에서 직접 설치할 수 있습니다:

pip install git+https://github.com/google/adk-python.git@main

참고: 개발 버전은 최신 코드 커밋에서 직접 빌드됩니다. 최신 수정 사항과 기능을 포함하고 있지만, 안정화된 릴리스에는 없는 실험적인 변경 사항이나 버그를 포함할 수도 있습니다. 이는 주로 다가오는 변경 사항을 테스트하거나 공식적으로 출시되기 전에 중요한 수정 사항에 접근하는 데 사용하세요.

초보자 참고: ADK 애플리케이션은 두 가지 주요 클래스를 사용하여 구축됩니다: Agent (AI의 지침, 도구 및 동작을 정의)와 Workflow (그래프 기반 흐름에서 에이전트와 작업을 오케스트레이션).

from google.adk import Agent
root_agent = Agent(
name="greeting_agent",
...

from google.adk import Agent, Workflow
generate_fruit_agent = Agent(
name="generate_fruit_agent",
...

# 대화형 CLI
adk run path/to/my_agent
# 웹 UI (다중 에이전트 디렉터리 지원 또는 단일 에이전트 폴더 직접 지정 가능)
...

에이전트를 테스트, 평가, 디버그 및 시연하는 데 도움이 되는 내장 개발 UI입니다.

저장소 루트에서 번들된 평가 샘플을 실행하세요:

adk eval \
contributing/samples/evaluation/home_automation_agent \
contributing/samples/evaluation/basic_criteria/home_automation.evalset.json \
...

에이전트를 Docker 컨테이너로 로컬 배포하기:

adk deploy docker --with_ui <agent-folder>

Google Cloud에서 에이전트 배포하기 (Cloud Run)

adk deploy cloud_run --with_ui <agent-folder>

다음 환경 변수들을 adk 명령어에 설정하거나, 대신 .env 파일에 설정할 수 있습니다.

adk deploy cloud_run --with_ui --env GOOGLE_GENAI_USE_ENTERPRISE=1 <agent-folder>

시작하기: https://adk.dev/**가이드**: 에이전트, 도구(tools), 이벤트(events), 플러그인(plugins), 워크플로우(workflows)에 대한 작업 중심의 상세 설명은 docs/guides/를 참고하세요.샘플: 실행 가능한 예제 에이전트는 contributing/samples/를 참고하세요.

커뮤니티의 기여를 환영합니다! 버그 보고, 기능 요청, 문서 개선 또는 코드 기여 등 어떤 형태든 저희의 다음을 확인해 주세요:

• 일반 기여 가이드라인 및 흐름.
• 시작하기 위한 코드 기여 가이드라인.

저희는 ADK의 핵심 기능을 확장하는 커뮤니티 기여 도구, 서드파티 서비스 통합 및 배포 스크립트가 모이는 adk-python-community 레포지토리를 운영하고 있습니다.

LLM에 vibe 코딩을 통해 에이전트를 개발하고 싶다면, ADK 문서 사이트에 게시된 llms.txt와 llms-full.txt를 LLM의 컨텍스트로 사용할 수 있습니다. 전자는 요약본이고 후자는 LLM의 컨텍스트 창(context window)이 충분하다면 전체 정보를 담고 있습니다.

• [완료] ADK의 첫 번째 커뮤니티 미팅은 2025년 10월 15일 수요일에 열렸습니다. 녹화본과 발표 자료를 얻으려면 그룹에 참여하는 것을 잊지 마세요.

이 프로젝트는 Apache 2.0 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

즐거운 에이전트 구축 되시길!