google-adk-python

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google ADK Python Skill

Google ADK Python 技能

You are an expert guide for Google's Agent Development Kit (ADK) Python - an open-source, code-first toolkit for building, evaluating, and deploying AI agents.

您是Google Agent开发工具包（ADK）Python版的专家向导——这是一个开源、代码优先的工具包，用于构建、评估和部署AI Agent。

When to Use This Skill

何时使用该技能

Use this skill when users need to:

Build AI agents with tool integration and orchestration capabilities
Create multi-agent systems with hierarchical coordination
Implement workflow agents (sequential, parallel, loop) for predictable pipelines
Integrate LLM-powered agents with Google Search, Code Execution, or custom tools
Deploy agents to Vertex AI Agent Engine, Cloud Run, or custom infrastructure
Evaluate and test agent performance systematically
Implement human-in-the-loop approval flows for tool execution

当用户需要以下功能时，可使用本技能：

构建具备工具集成和编排能力的AI Agent
创建带有分层协调机制的多Agent系统
实现工作流Agent（顺序、并行、循环）以构建可预测的管道
将基于LLM的Agent与Google Search、Code Execution或自定义工具集成
将Agent部署到Vertex AI Agent Engine、Cloud Run或自定义基础设施
系统化地评估和测试Agent性能
为工具执行实现人在环审批流程

Core Concepts

核心概念

Agent Types

Agent类型

LlmAgent: LLM-powered agents capable of dynamic routing and adaptive behavior

Define with name, model, instruction, description, and tools
Supports sub-agents for delegation and coordination
Intelligent decision-making based on context

Workflow Agents: Structured, predictable orchestration patterns

SequentialAgent: Execute agents in defined order
ParallelAgent: Run multiple agents concurrently
LoopAgent: Repeat execution with iteration logic

BaseAgent: Foundation for custom agent implementations

LlmAgent：基于LLM的Agent，具备动态路由和自适应行为

通过名称、模型、指令、描述和工具进行定义
支持子Agent以实现任务委派与协调
基于上下文进行智能决策

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

SequentialAgent：按定义顺序执行Agent
ParallelAgent：同时运行多个Agent
LoopAgent：结合迭代逻辑重复执行

BaseAgent：自定义Agent实现的基础框架

Key Components

关键组件

Tools Ecosystem:

Pre-built tools (google_search, code_execution)
Custom Python functions as tools
OpenAPI specification integration
Tool confirmation flows for human approval

Multi-Agent Architecture:

Hierarchical agent composition
Specialized agents for specific domains
Coordinator agents for delegation

工具生态系统：

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

多Agent架构：

分层Agent组合
针对特定领域的专用Agent
用于任务委派的协调Agent

Installation

安装

bash

undefined

bash

undefined

Stable release (recommended)

pip install google-adk

Development version (latest features)

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

undefined

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

undefined

Implementation Patterns

实现模式

Single Agent with Tools

带工具的单Agent

python

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]
)

python

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]
)

Multi-Agent System

多Agent系统

python

from google.adk.agents import LlmAgent

python

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.", )

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] )

undefined

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

undefined

Custom Tool Creation

自定义工具创建

python

from google.adk.tools import Tool

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

python

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] )

undefined

sum_tool = Tool.from_function(calculate_sum)

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

undefined

Sequential Workflow

顺序工作流

python

from google.adk.agents import SequentialAgent

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

python

from google.adk.agents import SequentialAgent

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

Parallel Workflow

并行工作流

python

from google.adk.agents import ParallelAgent

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

python

from google.adk.agents import ParallelAgent

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

Human-in-the-Loop

人在环流程

python

from google.adk.tools import google_search

python

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 )

undefined

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

undefined

Deployment Options

部署选项

Cloud Run Deployment

Cloud Run部署

bash

undefined

bash

undefined

Containerize agent

docker build -t my-agent .

Deploy to Cloud Run

gcloud run deploy my-agent --image my-agent

undefined

gcloud run deploy my-agent --image my-agent

undefined

Vertex AI Agent Engine

python

undefined

python

undefined

Deploy to Vertex AI for scalable agent hosting

Integrates with Google Cloud's managed infrastructure

undefined

undefined

Custom Infrastructure

自定义基础设施

python

undefined

python

undefined

Run agents locally or on custom servers

Full control over deployment environment

undefined

undefined

Model Support

模型支持

Optimized for Gemini:

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

Model Agnostic: While optimized for Gemini, ADK supports other LLM providers through standard APIs.

针对Gemini优化:

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

模型无关: 虽然针对Gemini优化，但ADK通过标准API支持其他LLM提供商。

Best Practices

最佳实践

Code-First Philosophy: Define agents in Python for version control, testing, and flexibility
Modular Design: Create specialized agents for specific domains, compose into systems
Tool Integration: Leverage pre-built tools, extend with custom functions
Evaluation: Test agents systematically against test cases
Safety: Implement confirmation flows for sensitive operations
Hierarchical Structure: Use coordinator agents for complex multi-agent workflows
Workflow Selection: Choose workflow agents for predictable pipelines, LLM agents for dynamic routing

代码优先理念: 用Python定义Agent，以实现版本控制、测试和灵活性
模块化设计: 为特定领域创建专用Agent，再组合成系统
工具集成: 利用预构建工具，通过自定义函数进行扩展
评估: 针对测试用例系统化地测试Agent
安全性: 为敏感操作实现确认流程
分层结构: 使用协调Agent处理复杂的多Agent工作流
工作流选择: 为可预测的管道选择工作流Agent，为动态路由选择LlmAgent

Common Use Cases

常见用例

Research Assistants: Web search + summarization + report generation
Code Assistants: Code execution + documentation + debugging
Customer Support: Query routing + knowledge base + escalation
Content Creation: Research + writing + editing pipelines
Data Analysis: Data fetching + processing + visualization
Task Automation: Multi-step workflows with conditional logic

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

Development UI

开发UI

ADK includes built-in interface for:

Testing agent behavior interactively
Debugging tool calls and responses
Evaluating agent performance
Iterating on agent design

ADK包含内置界面，用于：

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

Resources

资源

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

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

Implementation Workflow

实现工作流

When implementing ADK-based agents:

Define Requirements: Identify agent capabilities and tools needed
Choose Architecture: Single agent, multi-agent, or workflow-based
Select Tools: Pre-built, custom functions, or OpenAPI integrations
Implement Agents: Create agent definitions with instructions and tools
Test Locally: Use development UI for iteration
Add Evaluation: Create test cases for systematic validation
Deploy: Choose Cloud Run, Vertex AI, or custom infrastructure
Monitor: Track agent performance and iterate

Remember: ADK treats agent development like traditional software engineering - use version control, write tests, and follow engineering best practices.

在实现基于ADK的Agent时：

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

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