代理开发工具包 (ADK)

一个开源的、代码优先的 Python 框架，用于构建、评估和部署具有灵活性和控制力的复杂 AI 代理。

重要链接： 文档, 示例, Java ADK, Go ADK & ADK Web.

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

---

🔥 最新动态

• 自定义服务注册 (Custom Service Registration): 添加服务注册表以提供通用方式来注册自定义服务实现，供 FastAPI 服务器使用。查看 简短说明。 (391628f)

• 回退 (Rewind): 添加将会话回退到前一次调用之前的能力 (9dce06f)。

• 新代码执行器 (New CodeExecutor): 引入新的 AgentEngineSandboxCodeExecutor 类，支持使用 Vertex AI 代码执行沙箱 API (Vertex AI Code Execution Sandbox API) 执行代理生成的代码 (ee39a89)

✨ 核心功能

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

• 代码优先开发: 直接在 Python 中定义代理逻辑、工具和编排，以获得最大的灵活性、可测试性和版本控制能力。

• 代理配置 (Agent Config): 无需编写代码即可构建代理。查看 代理配置 功能。

• 工具确认: 一种 工具确认流程（HITL，人在回路），可以通过显式确认和自定义输入来保护工具的执行。

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

• 随处部署: 轻松将代理容器化并在 Cloud Run 上部署，或与 Vertex AI 代理引擎无缝扩展。

🚀 安装

稳定版本（推荐）

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

pip install google-adk

发布周期大约为每两周一次。

此版本推荐给大多数用户，因为它代表了最新的官方发布。

开发版本

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

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

注意：开发版本直接从最新的代码提交构建。虽然它包含了最新的修复和功能，但也可能包含稳定版中没有的实验性更改或错误。主要用于测试即将到来的更改或在正式发布之前访问关键修复。

🤖 代理对代理 (A2A) 协议与 ADK 集成

对于远程代理间通信，ADK 集成了 A2A 协议。 查看此 示例 了解它们如何协同工作。

📚 文档

探索完整文档以获取构建、评估和部署代理的详细指南：

• 文档

🏁 功能亮点

定义单个代理：

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

root_agent = Agent(
    name="search_assistant",
    model="gemini-2.5-flash", # 或者您首选的 Gemini 模型
    instruction="You are a helpful assistant. Answer user questions using Google Search when needed.",
    description="An assistant that can search the web.",
    tools=[google_search]
)

定义多代理系统：

定义一个包含协调代理、问候代理和任务执行代理的多代理系统。然后 ADK 引擎和模型将指导代理协作完成任务。

from google.adk.agents import LlmAgent, BaseAgent

# Define individual agents
greeter = LlmAgent(name="greeter", model="gemini-2.5-flash", ...)
task_executor = LlmAgent(name="task_executor", model="gemini-2.5-flash", ...)

# Create parent agent and assign children via sub_agents
coordinator = LlmAgent(
    name="Coordinator",
    model="gemini-2.5-flash",
    description="I coordinate greetings and tasks.",
    sub_agents=[ # Assign sub_agents here
        greeter,
        task_executor
    ]
)

开发 UI

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

评估代理

adk eval \
    samples_for_testing/hello_world \
    samples_for_testing/hello_world/hello_world_eval_set_001.evalset.json

🤝 贡献

我们欢迎社区的贡献！无论是 Bug 报告、功能请求、文档改进还是代码贡献，请查看我们的

• 一般贡献指南和流程。
• 然后如果您想贡献代码，请阅读 代码贡献指南 开始。

社区仓库

我们拥有 adk-python-community 仓库，这里汇聚了不断增长的社区贡献工具、第三方服务集成和部署脚本，它们扩展了 ADK（Agent Development Kit）的核心功能。

Vibe Coding（氛围编码）

如果您希望通过 Vibe Coding（氛围编码）开发智能体，llms.txt 和 llms-full.txt 可用作 LLM（大型语言模型）的上下文。前者是摘要版本，后者包含完整信息，以防您的 LLM 拥有足够大的上下文窗口。

社区活动

• [已完成] ADK 首次社区会议于 2025 年 10 月 15 日星期三举行。请记得 加入我们的群组 以获取 会议录像 和 演示文稿。

📄 许可证

本项目采用 Apache 2.0 许可证授权 - 详见 LICENSE 文件。

---

快乐构建智能体！

adk-python 快速上手指南

adk-python 是 Google 推出的开源、代码优先的 Python 框架，旨在简化 AI Agent 的构建、评估和部署流程。它采用模块化设计，支持多智能体系统编排，模型无关（虽针对 Gemini 优化），并兼容多种部署环境。

环境准备

• 操作系统: Linux, macOS, Windows
• Python 版本: 建议 Python 3.9 或更高版本
• 依赖管理: 确保已安装 pip 包管理器
• 网络环境: 由于涉及 Google 相关资源，国内用户可能需要配置网络代理或使用镜像源以保证下载速度。

安装步骤

推荐使用稳定版进行开发。如果需要使用最新功能或修复，可安装开发版。

1. 安装稳定版（推荐）

pip install google-adk

💡 提示: 若下载速度较慢，建议使用国内镜像源，例如：

pip install google-adk -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装开发版

如需获取主分支的最新更新，可从 GitHub 直接安装：

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

基本使用

ADK 允许通过纯 Python 代码定义 Agent 及其逻辑。以下是最简单的单 Agent 定义示例：

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

root_agent = Agent(
    name="search_assistant",
    model="gemini-2.5-flash", # Or your preferred Gemini model
    instruction="You are a helpful assistant. Answer user questions using Google Search when needed.",
    description="An assistant that can search the web.",
    tools=[google_search]
)

下一步

• 多智能体系统: 可通过 LlmAgent 和 sub_agents 属性构建层级化的多 Agent 协作系统。
• 运行与评估: 使用内置的开发 UI 进行测试，或通过命令行运行评估脚本：

  adk eval \
      samples_for_testing/hello_world \
      samples_for_testing/hello_world/hello_world_eval_set_001.evalset.json
  

• 完整文档: 访问 官方文档 获取更多详细指南。