英文原文正文为项目原始 README（英文），本站后续会翻译为中文，当前仅剔除图片与无关章节并统一排版。

代理开发工具包 (ADK) 2.0

   <a href="https://codewiki.google/github.com/google/adk-python"></a>

一个开源的、以代码为中心的 Python 框架，用于构建、评估和部署复杂的 AI 代理，提供灵活性和控制力。

重要链接: 文档, 示例 和 ADK Web。

ADK的其他语言版本：ADK Java、ADK Kotlin、ADK Go 和 ADK Typescript。

代理开发工具包（ADK）是一个灵活且模块化的框架，将软件开发原则应用于 AI 代理的创建。它旨在简化代理工作流的构建、部署和协调，从简单任务到复杂系统。虽然针对 Gemini 进行了优化，但 ADK 是模型无关、部署无关的，并且与其他框架兼容。

✨ 主要特点

• 工作流运行时：基于图形的执行引擎，用于为智能应用组合确定性执行流程，支持路由、分支/汇合、循环、重试、状态管理、动态节点、人工参与环节以及嵌套工作流。

• 任务 API：结构化的代理间任务委派，支持多轮任务模式、单轮受控输出、混合委派模式、人工参与环节，并将任务代理作为工作流节点。

• 模块化多代理系统：通过将多个专用代理组合为灵活的层级结构来设计可扩展应用。

• 丰富的工具生态系统：利用预构建工具、自定义函数、OpenAPI 规范、MCP 工具，或集成现有工具，为代理提供多样化功能，所有这些都可与 Google 生态系统紧密集成。

• 以代码为先的开发：直接在 Python 中定义代理逻辑、工具和编排，实现最大灵活性、可测试性及版本控制。

• 代理配置：无需编写代码即可构建代理。请查看 代理配置 功能。

• 工具确认：一个 工具确认流程（HITL），可通过明确确认和自定义输入来保护工具执行。

• 随处部署：轻松将代理容器化并部署到 Cloud Run，或使用 Vertex AI Agent Engine 实现无缝扩展。

🚀 安装

稳定版本（推荐）

您可以使用 pip 安装最新的 ADK 稳定版本：

pip install google-adk

要求: Python 3.10。

为了防止传递性依赖，我们建议使用我们的配套约束文件安装（适用于 Python 3.10 到 3.14）。

请选择与您的 Python 版本匹配的约束文件：

# For example, for Python 3.10
curl -o constraints-3.10.txt https://raw.githubusercontent.com/google/adk-python/main/constraints-3.10.txt
pip install google-adk -c constraints-3.10.txt
rm constraints-3.10.txt

要安装可选集成，您可以使用以下命令：

pip install "google-adk[extensions]"

发布节奏大约是每两周一次。

开发版本

错误修复和新功能首先合并到 GitHub 的主分支。如果您需要访问尚未包含在官方 PyPI 版本中的更改，您可以直接从主分支安装：

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",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant. Greet the user warmly.",
)

工作流

from google.adk import Agent, Workflow

generate_fruit_agent = Agent(
    name="generate_fruit_agent",
    instruction="Return the name of a random fruit. Return only the name.",
)

generate_benefit_agent = Agent(
    name="generate_benefit_agent",
    instruction="Tell me a health benefit about the specified fruit.",
)

root_agent = Workflow(
    name="root_agent",
    edges=[("START", generate_fruit_agent, generate_benefit_agent)],
)

本地运行

# Interactive CLI
adk run path/to/my_agent

# Web UI (supports multi-agent directories or pointing directly to a single agent folder)
adk web path/to/agents_dir

开发界面

内置开发界面，帮助您测试、评估、调试和展示您的代理。

评估代理

从仓库根目录运行捆绑的评估示例：

adk eval \
    contributing/samples/evaluation/home_automation_agent \
    contributing/samples/evaluation/basic_criteria/home_automation.evalset.json \
    --config_file_path contributing/samples/evaluation/basic_criteria/eval_config.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://google.github.io/adk-docs/
• 指南: 请参阅 docs/guides/ 了解面向任务的代理、工具、事件、插件和工作流的操作流程。
• 示例: 请参阅 contributing/samples/ 获取可运行的示例代理。

🤝 贡献

我们欢迎社区的贡献！无论是错误报告、功能请求、文档改进，还是代码贡献，请参阅我们的：

• 一般贡献指南和流程。
• 代码贡献指南 开始吧。

社区仓库

我们有 adk-python-community 仓库，这是一个由社区贡献的工具、第三方服务集成和部署脚本组成的不断增长的生态系统，用于扩展 ADK 的核心功能。

Vibe 编程

如果你想通过 Vibe 编程开发一个代理，llms.txt 和 llms-full.txt 可以作为 LLM 的上下文使用。前者是精简版，后者包含完整信息，以防你的 LLM 有足够大的上下文窗口。

社区活动

• [已完成] ADK 的第一次社区会议于 2025 年 10 月 15 日星期三举行。记得加入我们的群组以获取会议录音和幻灯片。

📄 许可证

本项目根据 Apache 2.0 许可证授权 — 详情请参见 LICENSE 文件。

快乐的代理构建!