google-adk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Agent Development Kit (ADK)

Google ADK is a Python framework for building, orchestrating, and evaluating LLM-powered agents. It provides structured patterns for single agents, multi-agent pipelines, custom tools, session state, safety controls, and evaluation.

Google ADK是一个用于构建、编排和评估基于LLM的Agent的Python框架。它为单Agent、多Agent流水线、自定义工具、会话状态、安全控制和评估提供了结构化模式。

Core Concepts

核心概念

LLM Agent

The fundamental building block is

LlmAgent

(aliased as

Agent

python

from google.adk.agents import LlmAgent

agent = LlmAgent(
    name="research_agent",          # unique, snake_case
    model="gemini-2.5-flash",
    description="Searches and summarizes research papers.",  # used for multi-agent routing
    instruction="You are a research assistant. ...",         # most critical field
    tools=[search_tool, summarize_tool],
)

Key fields:

Field	Purpose
`name`	Unique identifier; used for agent transfer
`description`	Shown to parent agents for routing decisions
`model`	Gemini model string (e.g. `gemini-2.5-flash` )
`instruction`	System prompt — the most critical field
`tools`	List of callable tools or `FunctionTool` instances
`output_key`	Write agent response to `session.state[key]`
`output_schema`	Pydantic model for structured JSON output
`include_contents`	`'default'` or `'none'` (stateless agents)

最基础的构建块是

LlmAgent

（别名

Agent

）：

python

from google.adk.agents import LlmAgent

agent = LlmAgent(
    name="research_agent",          # 唯一标识，采用蛇形命名法
    model="gemini-2.5-flash",
    description="Searches and summarizes research papers.",  # 用于多Agent路由
    instruction="You are a research assistant. ...",         # 最关键的字段
    tools=[search_tool, summarize_tool],
)

关键字段说明：

字段	用途
`name`	唯一标识符；用于Agent间的控制权转移
`description`	供父Agent参考以做出路由决策
`model`	Gemini模型字符串（例如 `gemini-2.5-flash` ）
`instruction`	系统提示词 — 最关键的配置字段
`tools`	可调用工具或 `FunctionTool` 实例的列表
`output_key`	将Agent响应写入 `session.state[key]`
`output_schema`	用于结构化JSON输出的Pydantic模型
`include_contents`	`'default'` 或 `'none'` （无状态Agent）

Instructions

提示词配置

Instructions are the most important configuration. Write them clearly:

Use markdown formatting (headers, bullets, code blocks)
Provide few-shot examples for complex behaviors
Guide tool selection explicitly: "Use
```
search_tool
```
when the user asks about..."
Inject state values with
```
{state_key}
```
or artifact values with
```
{artifact.name}
```
Keep instructions specific and task-scoped; avoid generic prompts

python

instruction="""
You are a customer support agent for Acme Corp.

提示词是最重要的配置项，需清晰编写：

使用Markdown格式（标题、项目符号、代码块）
针对复杂行为提供少量示例
明确指导工具选择：“当用户询问...时，使用
```
search_tool
```
”
通过
```
{state_key}
```
注入状态值，或通过
```
{artifact.name}
```
注入工件值
保持提示词具体且任务聚焦；避免通用化提示

python

instruction="""
You are a customer support agent for Acme Corp.

Behavior

Greet the user by name using {user_name}
For billing questions, always use
```
lookup_invoice
```
before responding
Escalate to human if sentiment is negative three times in a row

Greet the user by name using {user_name}
For billing questions, always use
```
lookup_invoice
```
before responding
Escalate to human if sentiment is negative three times in a row

Examples

User: "What's my balance?" Action: Call lookup_invoice(account_id="{account_id}") """,

undefined

User: "What's my balance?" Action: Call lookup_invoice(account_id="{account_id}") """,

undefined

Structured Output

结构化输出

Use

output_schema

when a downstream step requires machine-readable JSON:

python

from pydantic import BaseModel

class Report(BaseModel):
    title: str
    summary: str
    confidence: float

agent = LlmAgent(
    ...,
    output_schema=Report,
    output_key="report",     # writes JSON to session.state["report"]
)

Avoid combining

output_schema

with

tools

unless using Gemini 3.0+.

当下游步骤需要机器可读的JSON时，使用

output_schema

：

python

from pydantic import BaseModel

class Report(BaseModel):
    title: str
    summary: str
    confidence: float

agent = LlmAgent(
    ...,
    output_schema=Report,
    output_key="report",     # 将JSON写入session.state["report"]
)

除非使用Gemini 3.0+，否则避免同时使用

output_schema

和

tools

。

Function Tools

函数工具

Python functions are automatically wrapped as tools. The docstring becomes the tool description — write it carefully.

python

def get_weather(city: str, units: str = "celsius") -> dict:
    """Get current weather for a city.

    Args:
        city: The city name to look up.
        units: Temperature units, either 'celsius' or 'fahrenheit'.

    Returns:
        dict with keys: temperature, condition, humidity.
    """
    # implementation ...
    return {"temperature": 22, "condition": "sunny", "humidity": 60}

Rules:

Required params: typed, no default → model must supply them
Optional params: typed with default or
```
Optional[T] = None
```
Return type: always
```
dict
```
; include a
```
"status"
```
key (
```
"success"
```
/
```
"error"
```
)
*args
/
**kwargs
: ignored by ADK schema generation — avoid them
Make return values descriptive; the LLM reads them to decide next steps

Python函数会被自动包装为工具。文档字符串将成为工具描述 — 需仔细编写。

python

def get_weather(city: str, units: str = "celsius") -> dict:
    """Get current weather for a city.

    Args:
        city: The city name to look up.
        units: Temperature units, either 'celsius' or 'fahrenheit'.

    Returns:
        dict with keys: temperature, condition, humidity.
    """
    # 实现代码 ...
    return {"temperature": 22, "condition": "sunny", "humidity": 60}

规则：

必填参数：带类型标注，无默认值 → 模型必须提供这些参数
可选参数：带类型标注且有默认值，或为
```
Optional[T] = None
```
返回类型：必须为
```
dict
```
；需包含
```
"status"
```
键（
```
"success"
```
/
```
"error"
```
）
*args
/
**kwargs
：ADK schema生成会忽略这些参数 — 避免使用
使返回值具有描述性；LLM会读取这些值以决定后续步骤

Passing Data Between Tools

工具间传递数据

Use

session.state

with the

temp:

prefix for transient inter-tool data:

python

from google.adk.tools import ToolContext

def store_result(data: str, tool_context: ToolContext) -> dict:
    """Store intermediate result for downstream tools."""
    tool_context.state["temp:last_result"] = data
    return {"status": "success"}

def read_result(tool_context: ToolContext) -> dict:
    """Read the stored intermediate result."""
    value = tool_context.state.get("temp:last_result", "")
    return {"status": "success", "result": value}

使用带

temp:

前缀的

session.state

存储工具间的临时数据：

python

from google.adk.tools import ToolContext

def store_result(data: str, tool_context: ToolContext) -> dict:
    """Store intermediate result for downstream tools."""
    tool_context.state["temp:last_result"] = data
    return {"status": "success"}

def read_result(tool_context: ToolContext) -> dict:
    """Read the stored intermediate result."""
    value = tool_context.state.get("temp:last_result", "")
    return {"status": "success", "result": value}

Long-Running and Agent Tools

长时运行工具与Agent工具

python

from google.adk.tools import LongRunningFunctionTool, AgentTool

python

from google.adk.tools import LongRunningFunctionTool, AgentTool

Wrap async/long-running operations

包装异步/长时运行操作

slow_tool = LongRunningFunctionTool(func=run_batch_job)

Invoke a sub-agent as an explicit tool call

将子Agent作为显式工具调用

sub_agent_tool = AgentTool(agent=specialist_agent)

undefined

sub_agent_tool = AgentTool(agent=specialist_agent)

undefined

Multi-Agent Systems

多Agent系统

Hierarchy

层级结构

Compose agents using

sub_agents

. Each agent can have only one parent.

python

orchestrator = LlmAgent(
    name="orchestrator",
    model="gemini-2.5-flash",
    instruction="Route tasks to the appropriate specialist.",
    sub_agents=[research_agent, writer_agent, reviewer_agent],
)

使用

sub_agents

组合Agent。每个Agent只能有一个父Agent。

python

orchestrator = LlmAgent(
    name="orchestrator",
    model="gemini-2.5-flash",
    instruction="Route tasks to the appropriate specialist.",
    sub_agents=[research_agent, writer_agent, reviewer_agent],
)

Sequential Pipeline

顺序流水线

SequentialAgent

runs sub-agents in order. Pass data via

output_key

→

{state_key}

python

from google.adk.agents import SequentialAgent

pipeline = SequentialAgent(
    name="report_pipeline",
    sub_agents=[
        LlmAgent(name="researcher", ..., output_key="research_notes"),
        LlmAgent(name="writer",
                 instruction="Write a report based on: {research_notes}",
                 output_key="draft"),
        LlmAgent(name="reviewer",
                 instruction="Review this draft: {draft}"),
    ],
)

SequentialAgent

按顺序运行子Agent。通过

output_key

→

{state_key}

传递数据：

python

from google.adk.agents import SequentialAgent

pipeline = SequentialAgent(
    name="report_pipeline",
    sub_agents=[
        LlmAgent(name="researcher", ..., output_key="research_notes"),
        LlmAgent(name="writer",
                 instruction="Write a report based on: {research_notes}",
                 output_key="draft"),
        LlmAgent(name="reviewer",
                 instruction="Review this draft: {draft}"),
    ],
)

Parallel Pipeline

并行流水线

ParallelAgent

runs sub-agents concurrently. Use distinct

output_key

values to avoid race conditions:

python

from google.adk.agents import ParallelAgent

parallel = ParallelAgent(
    name="multi_search",
    sub_agents=[
        LlmAgent(name="web_searcher",   ..., output_key="web_results"),
        LlmAgent(name="doc_searcher",   ..., output_key="doc_results"),
        LlmAgent(name="db_searcher",    ..., output_key="db_results"),
    ],
)

ParallelAgent

并发运行子Agent。使用不同的

output_key

值以避免竞态条件：

python

from google.adk.agents import ParallelAgent

parallel = ParallelAgent(
    name="multi_search",
    sub_agents=[
        LlmAgent(name="web_searcher",   ..., output_key="web_results"),
        LlmAgent(name="doc_searcher",   ..., output_key="doc_results"),
        LlmAgent(name="db_searcher",    ..., output_key="db_results"),
    ],
)

Loop Pipeline

循环流水线

LoopAgent

repeats until

max_iterations

is reached or a sub-agent raises

escalate=True

python

from google.adk.agents import LoopAgent

refiner = LoopAgent(
    name="refinement_loop",
    max_iterations=5,
    sub_agents=[draft_agent, critic_agent],
)

LoopAgent

重复运行，直到达到

max_iterations

或子Agent抛出

escalate=True

：

python

from google.adk.agents import LoopAgent

refiner = LoopAgent(
    name="refinement_loop",
    max_iterations=5,
    sub_agents=[draft_agent, critic_agent],
)

LLM-Driven Transfer

LLM驱动的控制权转移

An LLM agent can transfer control by calling

transfer_to_agent(agent_name="...")

. For this to work reliably, every agent must have a clear

description

field.

LLM Agent可通过调用

transfer_to_agent(agent_name="...")

转移控制权。为确保此功能可靠运行，每个Agent必须有清晰的

description

字段。

Session State

会话状态

Session state is a

dict

persisted across turns. Keys follow naming conventions:

Prefix	Scope	Example
(none)	Persistent across session	`"user_name"`
`temp:`	Current turn only	`"temp:search_results"`
`user:`	User-level across sessions	`"user:preferences"`
`app:`	Application-level global	`"app:config"`

Access state from tools via

ToolContext

, from agents via

{state_key}

in instructions.

会话状态是一个跨轮次持久化的

dict

。键遵循命名约定：

前缀	作用域	示例
（无）	跨会话持久化	`"user_name"`
`temp:`	仅当前轮次	`"temp:search_results"`
`user:`	跨会话的用户级	`"user:preferences"`
`app:`	应用级全局	`"app:config"`

可通过

ToolContext

从工具中访问状态，或通过提示词中的

{state_key}

从Agent中访问状态。

Safety

安全

In-Tool Guardrails

工具内防护

Use

ToolContext

to enforce policies deterministically before the LLM sees results:

python

def sensitive_lookup(query: str, tool_context: ToolContext) -> dict:
    """Look up sensitive records."""
    if not tool_context.state.get("user:verified"):
        return {"status": "error", "message": "User not verified."}
    # proceed with lookup ...

使用

ToolContext

在LLM看到结果前确定性地执行策略：

python

def sensitive_lookup(query: str, tool_context: ToolContext) -> dict:
    """Look up sensitive records."""
    if not tool_context.state.get("user:verified"):
        return {"status": "error", "message": "用户未验证。"}
    # 继续执行查询 ...

Callbacks

回调函数

Use

before_tool_callback

to validate tool arguments before execution:

python

from google.adk.tools import ToolContext

def validate_args(tool_name: str, args: dict, tool_context: ToolContext):
    if tool_name == "delete_record" and not args.get("confirm"):
        raise ValueError("delete_record requires confirm=True")

agent = LlmAgent(..., before_tool_callback=validate_args)

使用

before_tool_callback

在执行前验证工具参数：

python

from google.adk.tools import ToolContext

def validate_args(tool_name: str, args: dict, tool_context: ToolContext):
    if tool_name == "delete_record" and not args.get("confirm"):
        raise ValueError("delete_record需要传入confirm=True")

agent = LlmAgent(..., before_tool_callback=validate_args)

Built-in Safety

内置安全机制

Configure Gemini's content filters via

generate_content_config

python

from google.genai.types import GenerateContentConfig, SafetySetting, HarmCategory, HarmBlockThreshold

agent = LlmAgent(
    ...,
    generate_content_config=GenerateContentConfig(
        temperature=0.2,
        max_output_tokens=2048,
        safety_settings=[
            SafetySetting(
                category=HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
                threshold=HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
            )
        ],
    ),
)

通过

generate_content_config

配置Gemini的内容过滤器：

python

from google.genai.types import GenerateContentConfig, SafetySetting, HarmCategory, HarmBlockThreshold

agent = LlmAgent(
    ...,
    generate_content_config=GenerateContentConfig(
        temperature=0.2,
        max_output_tokens=2048,
        safety_settings=[
            SafetySetting(
                category=HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
                threshold=HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
            )
        ],
    ),
)

Evaluation

评估

ADK supports two evaluation file formats:

Format	File	Use
Unit tests	`.test.json`	Single-turn, deterministic assertions
Integration tests	`.evalset.json`	Multi-turn conversation flows

Run evaluations:

bash

undefined

ADK支持两种评估文件格式：

格式	文件	用途
单元测试	`.test.json`	单轮次、确定性断言
集成测试	`.evalset.json`	多轮次对话流程

运行评估：

bash

undefined

Launch interactive web UI

启动交互式Web UI

adk web

CLI evaluation

CLI评估

adk eval path/to/agent path/to/tests.evalset.json

pytest integration

pytest集成

pytest tests/ -k "eval"


Key metrics:

| Metric | Description |
|---|---|
| `tool_trajectory_avg_score` | Exact match on tool call sequence |
| `response_match_score` | ROUGE-1 similarity to expected response |
| `final_response_match_v2` | LLM-based semantic match |
| `hallucinations_v1` | Detects fabricated facts |
| `safety_v1` | Flags safety violations |

pytest tests/ -k "eval"


关键指标：

| 指标 | 描述 |
|---|---|
| `tool_trajectory_avg_score` | 工具调用序列的精确匹配度 |
| `response_match_score` | 与预期响应的ROUGE-1相似度 |
| `final_response_match_v2` | 基于LLM的语义匹配度 |
| `hallucinations_v1` | 检测编造的事实 |
| `safety_v1` | 标记安全违规行为 |

Quick Reference

快速参考

Install:

bash

pip install google-adk

Minimal agent:

python

from google.adk.agents import LlmAgent

agent = LlmAgent(
    name="my_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant.",
)

Run locally:

bash

adk web          # web UI
adk run          # CLI interactive
adk api_server   # REST API server

Planners (for complex reasoning):

```
BuiltInPlanner
```
— uses Gemini's native thinking capability
```
PlanReActPlanner
```
— plan→act→reason loop for non-thinking models

安装:

bash

pip install google-adk

最小化Agent:

python

from google.adk.agents import LlmAgent

agent = LlmAgent(
    name="my_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant.",
)

本地运行:

bash

adk web          # Web UI
adk run          # CLI交互式运行
adk api_server   # REST API服务器

规划器（用于复杂推理）:

```
BuiltInPlanner
```
— 使用Gemini原生的思考能力
```
PlanReActPlanner
```
— 针对无思考能力模型的“规划→执行→推理”循环

Additional Resources

额外资源

references/agent-design.md
— Detailed LLM agent configuration, multi-agent patterns, and orchestration strategies
references/tools-and-sessions.md
— Function tool patterns, session state management, artifacts, and memory
references/safety-and-evaluation.md
— Safety architecture, guardrail patterns, and evaluation framework details

references/agent-design.md
— 详细的LLM Agent配置、多Agent模式和编排策略
references/tools-and-sessions.md
— 函数工具模式、会话状态管理、工件和内存
references/safety-and-evaluation.md
— 安全架构、防护模式和评估框架细节