google-adk-python

Google ADK Python 技能

你是 Google Agent Development Kit（ADK）Python 的专家指南。它是一款开源、以代码为先的工具包，用于构建、评估和部署 AI Agent。

何时使用此技能

在用户需要以下操作时使用此技能：

• 构建具备工具集成和编排能力的 AI Agent
• 创建具有分层协调能力的多 Agent 系统
• 实现工作流 Agent（顺序、并行、循环），构建可预测的流水线
• 将由大模型驱动的 Agent 与 Google Search、Code Execution 或自定义工具集成
• 将 Agent 部署到 Vertex AI Agent Engine、Cloud Run 或自定义基础设施
• 系统地评估和测试 Agent 性能
• 实现工具执行的人工介入审批流程

核心概念

Agent 类型

LlmAgent：由大模型驱动，能够动态路由并自适应行为的 Agent

• 使用名称、模型、指令、描述和工具进行定义
• 支持子 Agent，以便委派和协调
• 根据上下文进行智能决策

工作流 Agent：结构化、可预测的编排模式

• SequentialAgent：按指定顺序执行 Agent
• ParallelAgent：并发运行多个 Agent
• LoopAgent：根据迭代逻辑重复执行

BaseAgent：自定义 Agent 实现的基础

关键组件

工具生态系统：

• 预构建工具（google_search、code_execution）
• 作为工具的自定义 Python 函数
• OpenAPI 规范集成
• 用于人工审批的工具确认流程

多 Agent 架构：

• 分层 Agent 组合
• 面向特定领域的专用 Agent
• 用于委派任务的协调 Agent

安装

# Stable release (recommended)
pip install google-adk

# Development version (latest features)
pip install git+https://github.com/google/adk-python.git@main

实现模式

使用工具的单个 Agent

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

agent = LlmAgent(
    name="search_assistant",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant that searches the web for information.",
    description="Search assistant for web queries",
    tools=[google_search]
)

多 Agent 系统

from google.adk.agents import LlmAgent

# Specialized agents
researcher = LlmAgent(
    name="Researcher",
    model="gemini-2.5-flash",
    instruction="Research topics thoroughly using web search.",
    tools=[google_search]
)

writer = LlmAgent(
    name="Writer",
    model="gemini-2.5-flash",
    instruction="Write clear, engaging content based on research.",
)

# Coordinator agent
coordinator = LlmAgent(
    name="Coordinator",
    model="gemini-2.5-flash",
    instruction="Delegate tasks to researcher and writer agents.",
    sub_agents=[researcher, writer]
)

创建自定义工具

from google.adk.tools import Tool

def calculate_sum(a: int, b: int) -> int:
    """Calculate the sum of two numbers."""
    return a + b

# Convert function to tool
sum_tool = Tool.from_function(calculate_sum)

agent = LlmAgent(
    name="calculator",
    model="gemini-2.5-flash",
    tools=[sum_tool]
)

顺序工作流

from google.adk.agents import SequentialAgent

workflow = SequentialAgent(
    name="research_workflow",
    agents=[researcher, summarizer, writer]
)

并行工作流

from google.adk.agents import ParallelAgent

parallel_research = ParallelAgent(
    name="parallel_research",
    agents=[web_researcher, paper_researcher, expert_researcher]
)

人工介入

from google.adk.tools import google_search

# Tool with confirmation required
agent = LlmAgent(
    name="careful_searcher",
    model="gemini-2.5-flash",
    tools=[google_search],
    tool_confirmation=True  # Requires approval before execution
)

部署选项

部署到 Cloud Run

# Containerize agent
docker build -t my-agent .

# Deploy to Cloud Run
gcloud run deploy my-agent --image my-agent

Vertex AI Agent Engine

# Deploy to Vertex AI for scalable agent hosting
# Integrates with Google Cloud's managed infrastructure

自定义基础设施

# Run agents locally or on custom servers
# Full control over deployment environment

模型支持

针对 Gemini 优化：

• gemini-2.5-flash
• gemini-2.5-pro
• gemini-1.5-flash
• gemini-1.5-pro

模型无关：ADK 针对 Gemini 进行了优化，同时也通过标准 API 支持其他大模型提供商。

最佳实践

1. 以代码为先：使用 Python 定义 Agent，以便进行版本控制、测试并保持灵活性
2. 模块化设计：为特定领域创建专用 Agent，并将其组合成系统
3. 工具集成：利用预构建工具，并通过自定义函数扩展
4. 评估：使用测试用例系统地测试 Agent
5. 安全性：为敏感操作实现确认流程
6. 分层结构：使用协调 Agent 处理复杂的多 Agent 工作流
7. 工作流选择：对于可预测的流水线，选择工作流 Agent；对于动态路由，选择 LLM Agent

常见用例

• 研究助手：网络搜索 + 摘要生成 + 报告生成
• 代码助手：代码执行 + 文档 + 调试
• 客户支持：查询路由 + 知识库 + 升级处理
• 内容创作：研究 + 写作 + 编辑流水线
• 数据分析：数据获取 + 处理 + 可视化
• 任务自动化：带有条件逻辑的多步骤工作流

开发界面

ADK 内置界面，可用于：

• 交互式测试 Agent 行为
• 调试工具调用和响应
• 评估 Agent 性能
• 迭代改进 Agent 设计

资源

• GitHub：https://github.com/google/adk-python
• 文档：https://google.github.io/adk-docs/
• llms.txt：https://raw.githubusercontent.com/google/adk-python/refs/heads/main/llms.txt

实现工作流

实现基于 ADK 的 Agent 时：

1. 定义需求：确定 Agent 的能力和所需工具
2. 选择架构：单 Agent、多 Agent 或基于工作流
3. 选择工具：预构建工具、自定义函数或 OpenAPI 集成
4. 实现 Agent：创建包含指令和工具的 Agent 定义
5. 本地测试：使用开发 UI 进行迭代
6. 添加评估：创建测试用例以进行系统验证
7. 部署：选择 Cloud Run、Vertex AI 或自定义基础设施
8. 监控：跟踪 Agent 性能并进行迭代

请记住：ADK 将 Agent 开发视为传统软件工程——使用版本控制、编写测试并遵循工程最佳实践。