ADK 的定位
ADK 的定位不是"再一个 Agent 库",而是一套带运行时、会话、评估与部署的完整栈 :Agent 是配置、Runner 是循环、Session 是状态、adk CLI 负责从本地调试到上线。它已进入 2.x(Python 2.14.x),并把 Agent 变成图节点------所以要先理解事件与状态怎么写回,再看多 Agent。
数据截止 2026-11-19对应 google-adk 2.14.x10 段代码 · 16 张表
它是什么:Agent 框架 + 运行时 + 工具链
四个 Agent 框架里,ADK 的差异在覆盖范围:它不只给你写 Agent 的类,还给了会话服务、记忆、评估器、CLI 与两条部署路径。代价是概念更多------事件、状态前缀、回调、动作,每一个都要理解对,否则会出现"看起来跑了但状态没存"。
4 种语言
Python / Java / Go / TypeScript,Python 能力最全
2.x 已 GA
Agent 成为图节点,事件新增 node_info/output
3 类 Agent
LlmAgent + 顺序/并行/循环三种工作流
1 套 CLI
create / run / web / api_server / eval / deploy
四种 Agent 框架的定位差异
| 维度 | Google ADK | LangGraph | OpenAI Agents SDK | Claude Agent SDK |
| 核心抽象 | Agent 层级 + 事件流 | 状态图 + checkpointer | Agent + Handoff | 成品 harness |
| 多 Agent | sub_agents / transfer / AgentTool | 节点与边自由组合 | handoff + as_tool | 子 Agent + 工具 |
| 模型 | Gemini 优先,可接 Claude / LiteLLM | 模型无关 | OpenAI 优先 | 仅 Claude |
| 运行时 | 自带 Runner + 三种 SessionService | 需自配持久化 | Session 较简 | 子进程 + 会话文件 |
| 评估与部署 | 内置 adk eval 与两条部署路径 |
需自建 | 自建 | 自建 |
|---|---|---|---|---|
| [表 1:四种 Agent 框架的定位差异] |
什么时候选它
三个信号:团队已经在 GCP 上 (Vertex、Cloud Run、BigQuery 数据源)、需要多语言 (Java/Go 服务里嵌 Agent)、需要开箱的评估与部署。如果只是要一个轻量 handoff 链,OpenAI 的 SDK 更省事;如果要精确控制每一步状态,LangGraph 更合适。
版本、安装与一个必须注意的差异
截至 2026-11-19,PyPI 上 google-adk 最新为 2.14.1 (2026-11-13),采用 Apache 2.0,要求 Python ≥ 3.11 1。2.0 GA 在 2026-05,Go 与 TypeScript 随后跟进;Java 仍停在 1.x 线(Maven 示例为 1.14.0)2。
terminal · 安装与版本确认
pip install google-adk
python -c "import google.adk, importlib.metadata as m; print(m.version('google-adk'))"
# 想留在 1.x(Python 3.10+ 仍可)
# pip install "google-adk~=1.0"
# 需要 GCP 相关能力(RAG 记忆、Vertex 服务)
# pip install "google-adk[gcp]"
版本与语言的三条事实
| 事实 | 细节 | 影响 |
| Python 版本门槛变了 | PyPI 写 ≥3.11,快速入门页仍写 3.10+ | 装不上时先升 Python,别怀疑镜像 |
| 2.0 有结构性变更 | Agent 继承 BaseNode;禁止直接 session.events.append;事件新增 node_info/output | 1.x 的覆写写法在 2.x 会被绕过 |
| 语言能力不对等 | Agent Runtime 部署、多数内置工具只在 Python | 多语言项目要先确认目标能力 |
|---|---|---|
| [表 2:版本与语言的三条事实] |
2.x 最容易被旧教程带偏的一处
2.0 起不能直接往 session.events 里 append ,必须通过 yield 事件(或 state_delta)写回。照抄 1.x 教程里"手动改 events 列表"的代码,会得到"状态没保存、下一轮读不到"的现象------不报错,但行为不对。
十分钟跑通:Agent + Runner + Session
最小可运行单元是四件东西:LlmAgent(角色)、InMemorySessionService(会话)、Runner(循环)、一条 types.Content(消息)。run_async 产出的是事件流 ,不是最终字符串6。官方快速入门走的也是这三步:建 Agent、建会话、跑 Runner8。
hello.py · 无工具版
import asyncio
from google.adk.agents import LlmAgent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types
agent = LlmAgent(
name="assistant",
model="gemini-flash-latest", # 用 -latest 别名,避免版本下线
instruction="你是简洁的中文助手,回答不超过三句话。",
)
session_service = InMemorySessionService()
runner = Runner(app_name="demo", agent=agent, session_service=session_service)
async def main():
session = await session_service.create_session(app_name="demo", user_id="u-1")
message = types.Content(role="user", parts=[types.Part(text="用一句话解释 ADK")])
async for event in runner.run_async(user_id="u-1", session_id=session.id, new_message=message):
if event.is_final_response():
print(event.content.parts[0].text)
asyncio.run(main())
在 Notebook / Colab 里别用 asyncio.run
Jupyter 已有运行中的事件循环,asyncio.run(...) 会报 "cannot be called from a running event loop"。在单元格里直接 await main(),或用 nest_asyncio(临时手段)。这个错误在新手问题里出现频率最高。
LlmAgent:六个字段决定 80% 的行为
LlmAgent 是配置对象,不持有状态。真正影响效果的是 name、instruction、tools、sub_agents、output_key、model 这六项;description 决定别的 Agent 会不会"想到你"3。
常用字段与注意点
| 字段 | 作用 | 注意 |
| name | 必填,唯一标识 | 会出现在事件 author 与 transfer 工具名里,用英文短名 |
| description | 给父 Agent / 其他 Agent 看的简介 | 多 Agent 时比 instruction 更影响"会不会被调用" |
| instruction | 系统提示,支持 {state_key} 模板 | 键缺失会报错,可写 {key?} 容错 |
| tools | 函数工具 / 内置工具 / AgentTool / MCP | 越多越容易误选,按角色裁剪 |
| sub_agents | 下级 Agent,自动获得 transfer 能力 | 一个 Agent 只能有一个父级,重复挂载会报错 |
| output_key | 把最终文本写进 state[key] | 下游用 {key} 读取,是 Agent 间传值最常用的方式 |
model |
模型名或包装类(LiteLlm 等) | 默认用 flash 类模型做路由与抽取更划算[10](#表 3:常用字段与注意点 字段 作用 注意 name 必填,唯一标识 会出现在事件 author 与 transfer 工具名里,用英文短名 description 给父 Agent / 其他 Agent 看的简介 多 Agent 时比 instruction 更影响"会不会被调用" instruction 系统提示,支持 {state_key} 模板 键缺失会报错,可写 {key?} 容错 tools 函数工具 / 内置工具 / AgentTool / MCP 越多越容易误选,按角色裁剪 sub_agents 下级 Agent,自动获得 transfer 能力 一个 Agent 只能有一个父级,重复挂载会报错 output_key 把最终文本写进 state[key] 下游用 {key} 读取,是 Agent 间传值最常用的方式 model 模型名或包装类(LiteLlm 等) 默认用 flash 类模型做路由与抽取更划算[10]) |
|---|---|---|
| [表 3:常用字段与注意点] |
global_instruction 已废弃
旧教程里的 global_instruction 在 2.x 被移除,取而代之的是 GlobalInstructionPlugin。如果照抄老代码发现参数不认,先查这一项------这是 1.x 迁移最典型的报错来源之一。
三种工作流 Agent:把"顺序"写进结构
多 Agent 不一定要靠模型决定顺序。SequentialAgent、ParallelAgent、LoopAgent 把流程固定下来,每个子 Agent 仍是独立的 LlmAgent21。
三种工作流的语义与坑
| 类型 | 语义 | 关键字段 | 常见坑 |
| SequentialAgent | 按顺序执行子 Agent | sub_agents | 前一步没写 output_key,后一步读不到 |
| ParallelAgent | 并发执行,全部完成再继续 | sub_agents | 共享同一 state,写同 key 会竞态 |
LoopAgent |
循环执行,直到条件满足 | max_iterations + escalate |
自身不判断终止,容易死循环 |
|---|---|---|---|
| [表 4:三种工作流的语义与坑] |
workflow.py · 顺序 + 循环的组合
from google.adk.agents import LlmAgent, LoopAgent, SequentialAgent
from google.adk.tools import ToolContext
def exit_loop(tool_context: ToolContext) -> dict:
"""表示评审已通过,结束循环。"""
tool_context.actions.escalate = True # 关键:让 LoopAgent 退出
return {"status": "done"}
draft = LlmAgent(name="drafter", model="gemini-flash-latest",
instruction="根据需求写一版方案,输出到 state。", output_key="draft")
review = LlmAgent(name="reviewer", model="gemini-flash-latest",
instruction="评审 {draft}。通过就调用 exit_loop,否则指出问题。",
tools=[exit_loop])
loop = LoopAgent(name="draft_loop", sub_agents=[draft, review], max_iterations=3)
pipeline = SequentialAgent(name="pipeline", sub_agents=[loop])
LoopAgent 自己不会停
它的终止条件只有两个:max_iterations 用完,或子 Agent 设置 actions.escalate=True。所以"评审通过就退出"必须由子 Agent 显式触发(常见做法是给一个 exit_loop 工具)。没有这个,就是跑到上限为止------支付的是真金白银。
工具:函数即工具,但 schema 由签名决定
ADK 把函数直接放进 tools 列表 就完成包装:它读函数名、docstring、类型注解与默认值生成 schema。注意整段 docstring 会作为工具唯一的描述,没有按参数分别描述的能力 ------所以参数含义要写进 docstring 正文12。
tools.py · 一个带上下文的函数工具
from google.adk.agents import LlmAgent
from google.adk.tools import ToolContext
def get_weather(city: str, tool_context: ToolContext) -> dict:
"""查询指定城市的当前天气。
city: 城市名,例如"杭州"。tool_context 由框架注入,不要放进参数注释。
"""
# 写 state 要走 context.state(会进入 state_delta),不要直接改 session
tool_context.state["last_city"] = city
return {"city": city, "temp_c": 24, "sky": "多云"}
agent = LlmAgent(
name="weather",
model="gemini-flash-latest",
instruction="用户问天气就调用 get_weather,不要凭记忆回答。",
tools=[get_weather],
)
| 类型 | 怎么用 | 限制 |
| 函数工具 | 函数放进 tools | *args/**kwargs 被忽略;返回非 dict 会被包成 {"result": ...} |
| 内置工具 | google_search、VertexAiSearchTool | google_search 仅 Gemini 2 系列,且通常要求它是唯一工具 |
| 代码执行 | code_executor=BuiltInCodeExecutor() | 是构造参数,不是放 tools 列表 |
| AgentTool | AgentTool(agent=expert) | 子 Agent 中间过程不进父上下文;与 transfer 语义不同 |
| MCP | McpToolset(connection_params=...) |
生产须在 agent.py 里同步定义,避免延迟建连失败[16](#表 5:五类工具的能力边界[11] 类型 怎么用 限制 函数工具 函数放进 tools *args/**kwargs 被忽略;返回非 dict 会被包成 {"result": ...} 内置工具 google_search、VertexAiSearchTool google_search 仅 Gemini 2 系列,且通常要求它是唯一工具 代码执行 code_executor=BuiltInCodeExecutor() 是构造参数,不是放 tools 列表 AgentTool AgentTool(agent=expert) 子 Agent 中间过程不进父上下文;与 transfer 语义不同 MCP McpToolset(connection_params=...) 生产须在 agent.py 里同步定义,避免延迟建连失败[16]) |
|---|---|---|
| [表 5:五类工具的能力边界[11](#表 5:五类工具的能力边界[11] 类型 怎么用 限制 函数工具 函数放进 tools *args/**kwargs 被忽略;返回非 dict 会被包成 {"result": ...} 内置工具 google_search、VertexAiSearchTool google_search 仅 Gemini 2 系列,且通常要求它是唯一工具 代码执行 code_executor=BuiltInCodeExecutor() 是构造参数,不是放 tools 列表 AgentTool AgentTool(agent=expert) 子 Agent 中间过程不进父上下文;与 transfer 语义不同 MCP McpToolset(connection_params=...) 生产须在 agent.py 里同步定义,避免延迟建连失败[16])] |
State 与 Session:四种前缀决定"活多久"
这是 ADK 最需要记牢的一张表。同一个 state 字典,靠前缀区分作用域:不写前缀只活在当前会话,user: 跨会话,app: 全应用共享,temp: 只活一次调用4。
state 前缀的语义
| 写法 | 作用域 | 典型用途 |
| state["k"] | 当前 session | 本轮任务的中间结果 |
| state["user:k"] | 同一用户的所有 session | 用户偏好、会员等级 |
| state["app:k"] | 整个应用跨用户 | 全局配置、开关 |
state["temp:k"] |
单次 invocation(含子 Agent 链) | 传参、临时标记,不落库 |
|---|---|---|
| [表 6:state 前缀的语义] |
| 实现 | 存储 | 适用 |
| InMemorySessionService | 进程内存 | 本地调试、单元测试;重启即丢 |
| DatabaseSessionService | 关系库 | 自建服务、要持久化 |
VertexAiSessionService |
托管 | 部署到 Google Cloud、多实例共享 |
|---|---|---|
| [### 三种 SessionService 的取舍 | ||
| 表 7:三种 SessionService 的取舍] |
改 session.state 不等于保存
直接 session.state["x"] = 1 只在内存里改了对象,不会产生持久化事件 。正确做法是在工具或回调里写 tool_context.state[...](框架会转成 state_delta),或让 Agent 用 output_key 写。这个区别决定了"下一轮能不能读到"。
Event 与 Actions:会话的"账本"
事件既是消息也是状态变更的载体。读事件时最该看两处:content(说了什么)与 actions(要改变什么)------包括 state_delta、artifact_delta、transfer_to_agent 与 escalate5。
Event 的关键字段
| 字段 | 含义 | 用途 |
| author | 谁产生的(Agent 名或 user) | 判断当前由哪个 Agent 作答 |
| content | 文本 / 函数调用等内容块 | 渲染对话、取最终答复 |
| partial | 是否为流式片段 | SSE 模式下拼接文本时要判断 |
| actions.state_delta | 本事件带来的状态变更 | 审计"谁改了哪个 key" |
| actions.transfer_to_agent | 控制权移交目标 | 多 Agent 路由的证据 |
actions.escalate |
请求终止循环/升级 | LoopAgent 的退出信号 |
|---|---|---|
| [表 8:Event 的关键字段] |
2.x 里事件还多了 node_info 与 output
因为 Agent 现在是图节点,事件需要标明"来自哪个节点、输出是什么"。写自定义 Agent 时如果只填 content 不填这两项,图层面的调试信息会缺失------不影响运行,但影响排查。
多 Agent:三种"让另一个 Agent 干活"的方式
ADK 有三种协作语义,选错会出现"子 Agent 说完话父 Agent 不接着干"或"父 Agent 把子 Agent 的中间过程全吞进上下文"。区别在控制权归属 与上下文是否共享 21。
三种协作方式的差别
| 方式 | 控制权 | 上下文 | 适用 |
| sub_agents(transfer) | 移交给子 Agent,子 Agent 直接回复用户 | 共享 session,历史连续 | 分流、客服转专家 |
| AgentTool | 留在父 Agent,结果作为工具返回值 | 子 Agent 独立,只回传结论 | 可复用专家、需要父级统一出口 |
| 工作流 Agent | 由结构决定,不靠模型判断 | 共享 state | 顺序固定、并行汇总 |
|---|---|---|---|
| [表 9:三种协作方式的差别] |
multi_agent.py · 分流 + 专家即工具
from google.adk.agents import LlmAgent
from google.adk.tools.agent_tool import AgentTool
billing = LlmAgent(
name="billing",
description="处理退款、账单与发票。不处理技术故障。",
model="gemini-flash-latest",
instruction="先核对订单号,再给结论。",
)
tech = LlmAgent(
name="tech",
description="处理登录失败、报错、白屏。不处理退款。",
model="gemini-flash-latest",
instruction="先查知识库,再给三步排查建议。",
)
# 方式一:交接(transfer)------父级把控制权交出去
triage = LlmAgent(
name="triage",
description="客服前台,负责判断意图并分流。",
model="gemini-flash-latest",
instruction="判断意图后交给对应专家,不要自己处理。",
sub_agents=[billing, tech],
)
# 方式二:专家即工具------父级保留控制权,只取结论
writer = LlmAgent(
name="writer",
model="gemini-flash-latest",
instruction="调用 billing_expert 拿到结论,再整理成给用户的正式答复。",
tools=[AgentTool(agent=billing, name="billing_expert")],
)
一个 Agent 只能有一个父级
把同一个实例挂到两个父 Agent 的 sub_agents 下会直接抛 ValueError。要复用就新建一个实例 ,或用 AgentTool 包一层------后者本来就允许多处引用,因为它是"调用"而不是"归属"。
如果协作对象在另一个进程或另一个组织 ,用 A2A:把 Agent 暴露成 A2A server,另一方作为客户端调用。语义上相当于把 AgentTool 延伸到网络边界,但多了一层身份与协议约定24。Python 支持最完整,其它语言仍在实验阶段。
回调:六个位置,返回值决定"放行还是接管"
回调是 ADK 唯一的"代码级拦截点"。规则只有一条但要记准:返回 None(或假值)表示不干预;返回对应类型的真值就接管并终止后续回调链 。参数名必须精确匹配,否则不会被识别13。
六类回调的返回约定
| 回调 | 参数 | 返回什么才算接管 | 效果 |
| before_agent | callback_context | Content | 跳过该 Agent 的核心逻辑 |
| after_agent | callback_context | Content | 替换该 Agent 的输出 |
| before_model | callback_context, llm_request | LlmResponse | 跳过本次模型调用(可做缓存/护栏) |
| after_model | callback_context, llm_response | LlmResponse | 改写模型输出 |
| before_tool | tool, args, tool_context | dict | 跳过工具执行,直接返回该 dict |
after_tool |
tool, args, tool_context, tool_response |
dict |
替换工具返回值 |
|---|---|---|---|
| [表 10:六类回调的返回约定] |
guards.py · 用回调做两道拦截
from google.adk.agents.callback_context import CallbackContext
from google.adk.models import LlmResponse # 若报导入错误,查 models.llm_response
from google.genai import types
def before_tool_guard(tool, args, tool_context):
"""危险工具直接拦下;返回 dict 就代表"不执行工具,用它当结果"。"""
if tool.name in {"delete_file", "run_shell"}:
return {"error": "只读模式禁止该操作", "tool": tool.name}
return None # 不干预,继续执行工具
def before_model_guard(callback_context: CallbackContext, llm_request):
"""命中敏感词时直接给一段固定回复,跳过模型调用。"""
text = str(llm_request)
if "身份证" in text:
return LlmResponse(
content=types.Content(role="model", parts=[types.Part(text="请不要在对话中提供身份证号。")]),
)
return None
triage = LlmAgent(
name="triage", model="gemini-flash-latest", instruction="分流并回答。",
before_tool_callback=before_tool_guard,
before_model_callback=before_model_guard,
)
最常见的两种错
① 返回类型不匹配 :在 before_model 里返回 dict、在 before_tool 里返回 LlmResponse,都不会生效,还很难排查。② 忘记 return None :函数隐式返回 None 没问题,但如果你写了 return 之前的分支却没覆盖所有路径,某些情况下会返回 False 之类的假值------恰好"不干预",看起来正常,实则是巧合。
上下文与文件:tool_context 那一层
工具里需要"业务依赖"时,别用全局变量,用类型注解让框架注入:tool_context: ToolContext。它提供 state、actions(如 escalate)与 artifact 读写方法,对模型不可见 15。
tool_context 提供的四类能力
| 能力 | 用法 | 注意 |
| 读状态 | tool_context.state["user:tier"] | 带前缀读,语义见第 7 节 |
| 写状态 | tool_context.state["k"] = v | 会进 state_delta,这才算保存 |
| 控制流 | tool_context.actions.escalate = True | LoopAgent 的退出信号 |
| 文件 | save_artifact(name, part) / load_artifact(name) |
同名自动递增版本,返回版本号 |
|---|---|---|
| [表 11:tool_context 提供的四类能力] |
Artifact 适合放大对象(报告、图片、CSV)。
内容用 types.Part(inline_data=types.Blob(data=..., mime_type=...)) 包装;Runner(artifact_service=...) 决定存在内存还是 GCS。要跨实例共享就换 GcsArtifactService,否则容器重启即丢。
记忆:把"会话历史"变成"可检索的知识"
Session 是当前对话的账本,Memory 是跨会话的检索库。典型流程是:一次会话结束 → add_session_to_memory(session) → 下次召回转成 search_memory,再由 load_memory 工具暴露给模型14。
三种 MemoryService 的取舍
| 实现 | 检索方式 | 适用 |
| InMemoryMemoryService | 关键词匹配 | 开发验证;无持久化、语义弱 |
| VertexAiMemoryBankService | LLM 抽取 + 语义检索 | 生产;需要托管运行时实例 |
VertexAiRagMemoryService |
RAG 检索 | 已有语料库;需装 google-adk[gcp] |
|---|---|---|
| [表 12:三种 MemoryService 的取舍] |
memory.py · 写入与召回
from google.adk.memory import InMemoryMemoryService
from google.adk.runners import Runner
memory_service = InMemoryMemoryService()
runner = Runner(app_name="demo", agent=agent,
session_service=session_service, memory_service=memory_service)
# 一轮对话结束后把整段会话写入记忆
session = await session_service.get_session(app_name="demo", user_id="u-1", session_id=session.id)
await memory_service.add_session_to_memory(session)
# 下一次对话里,Agent 通过 load_memory 工具检索(需把该工具加进 tools)
别把 Memory 当缓存
它的价值是"跨会话记住事实与偏好",不是"省 token"。把整段对话无脑灌进去,检索质量会随噪声下降。实践上只写入有长期价值的结论(用户偏好、已确认的决策),并给条目打标签。
流式:三种模式,只有一种给前端用
RunConfig.streaming_mode 有三个值:NONE(默认,整段返回)、SSE(增量事件,适合打字机)、BIDI(双向,保留给 run_live())1723。注意 run_async 不读 BIDI------传了也不会变成双向。
stream.py · SSE 增量输出
from google.adk.agents.run_config import RunConfig, StreamingMode
run_config = RunConfig(streaming_mode=StreamingMode.SSE)
async for event in runner.run_async(
user_id="u-1", session_id=session.id, new_message=message, run_config=run_config
):
if event.partial and event.content and event.content.parts:
# 片段:直接 append 到前端缓冲区,不要覆盖
print(event.content.parts[0].text or "", end="", flush=True)
elif event.is_final_response():
# 收尾:用完整文本替换缓冲区,避免拼接口径不一致
print("\n[final]", event.content.parts[0].text)
Live API
Live API(语音/视频双向)是实验特性,需要 run_live() 与 response_modalities=AUDIO 之类的配置,且必须先创建 session,否则抛 SessionNotFoundError。没有实时语音需求就不要碰这条路径。
评估:把"感觉还行"变成可比较的数字
ADK 内置评估器:adk eval 跑数据集,输出指标;adk test 用 pytest 跑单条用例。数据集有两种粒度:完整 evalset(含多轮与工具轨迹)与轻量 *.test.json18。
terminal · 跑评估
# 基本用法:模块路径 + 一个或多个 evalset
adk eval ./agent.py ./tests/evalset.json --print_detailed_results
# 用配置指定指标与阈值
adk eval ./agent.py ./tests/evalset.json --config_file_path=eval_config.json
# 轻量回归:pytest 风格
adk test ./tests
| 指标 | 衡量什么 | 适合 |
| tool_trajectory_avg_score | 工具调用序列是否符合预期 | 流程类 Agent 的首选,最稳定 |
| response_match_score | 文本相似度 | 固定问答;对措辞变化敏感 |
| final_response_match_v2 | 语义匹配 | 开放式回答,比字面匹配宽容 |
rubric_based_* |
按评分细则判质量 | 主观质量;成本较高 |
|---|---|---|
| [### 四类常用指标的取舍 | ||
| 表 13:四类常用指标的取舍] |
评测从轨迹开始
先断言"该调的工具调了、不该调的没调",再断言"回答好不好"。原因是轨迹断言不随模型措辞漂移,改提示词时能立刻看出有没有破坏流程;而文本相似度会在你换模型后集体失效。
部署:两条路,一个必须先配的东西
adk deploy cloud_run 把 Agent 打成容器,adk deploy agent_engine 部署到托管运行时。两条路都默认回落内存服务 ------不显式指定会话与文件存储,实例一回收数据就没了1920。CLI 的完整子命令是 create / run / web / api_server / eval / deploy,另有 telemetry 开关7。
terminal · 部署命令
# Cloud Run:注意把三个服务都指到外部存储
adk deploy cloud_run --project=my-proj --region=asia-east1 \
--service_name=adk-demo \
--session_service_uri=postgresql://... \
--artifact_service_uri=gs://my-bucket/artifacts \
--memory_service_uri=agentengine://...
# Agent Runtime(托管):仅 Python
adk deploy agent_engine --project=my-proj --region=asia-east1 \
--display_name=adk-demo
# 本地开发用 web,不要用于生产
adk web
| 维度 | Cloud Run | Agent Runtime |
| 形态 | 你自己的容器 | 托管服务 |
| 会话/文件 | 自己配 URI,否则内存 | 平台提供 |
| 语言 | Python(容器内任意) | 当前仅 Python |
| 适合 | 已有 GCP 运维体系、要自定义 | 想少运维、接受平台约束 |
|---|---|---|
| [### 两条部署路径的差别 | ||
| 表 14:两条部署路径的差别] |
三个部署期的高频问题
① 会话丢失 :忘了 --session_service_uri,表现为"每次请求都是新对话"。② 冷启动 :Cloud Run 缩容到 0,首个请求要等容器起来,交互式产品要设 min-instances。③ 认证混用 :Gemini API Key 与 Vertex 模式(GOOGLE_CLOUD_PROJECT / GOOGLE_CLOUD_LOCATION + 企业开关)只能二选一,混用会鉴权失败。
十二个坑:按遇到概率排序
现象、根因、修法
| 现象 | 根因 | 修法 |
| Notebook 里报事件循环错误 | asyncio.run 与已有循环冲突 | 单元格内直接 await main() |
| 状态下一轮读不到 | 直接改 session.state,没走 state_delta | 用 tool_context.state 或 output_key |
| LoopAgent 跑到上限才停 | 没有退出信号 | 子 Agent 里设 actions.escalate=True |
| 回调写了却不生效 | 返回类型不对,或参数名不匹配 | 按表 10 的类型返回,参数名逐字对齐 |
| 子 Agent 说完父级不继续说 | 用了 sub_agents(移交),却期望返回 | 要返回就用 AgentTool |
| 同一 Agent 挂两个父级报 ValueError | 层级关系是一对多禁止 | 新建实例,或用 AgentTool 复用 |
| ParallelAgent 结果互相覆盖 | 并发写同一个 state key | 每个分支写不同 key,或写 temp: |
| 工具参数 schema 缺失 | 用了 *args/**kwargs,或没有类型注解 | 写显式参数与注解,docstring 补参数说明 |
| 模型 404 | 模型名写错或已下线 | 用 -latest 别名,部署前核对可用列表 |
| SessionNotFoundError | 没先 create_session 就 run_live | 先建会话;部署到托管后确认依赖版本 |
| 上线后会话全丢 | 用了 InMemory 服务 | 配 Database/Vertex 会话服务与 GCS artifact |
把 adk web 当生产服务 |
它是开发调试工具 | 生产用 adk api_server 或部署到 Cloud Run / Runtime |
|---|---|---|
| [表 15:现象、根因、修法] |
六个高难问题:需要设计,不是改参数
① 多 Agent 拓扑与"谁来收尾"
移交(transfer)之后,子 Agent 直接面向用户,父 Agent 不再参与。这在"专家答复需要统一格式"的产品里会变成问题:前台想统一口吻,但控制权已经交出去了。解法是把专家包成 AgentTool,让父 Agent 保留出口;或者接受"专家直接说",并给每个专家写统一的输出规范。
② 状态一致性与并发
ParallelAgent 共享 state,两个分支写同一个 key 就是竞态,且不报错。工程上要建立约定:并行分支只写自己命名空间下的 key ,汇总节点再合并。更稳妥的做法是用 temp: 传中间值、用 output_key 落最终值。
③ 成本控制
三个放大器:循环 Agent 的迭代、移交链的长度、工具 schema 的体积。LoopAgent.max_iterations 是硬闸门,但真正的成本来自"每轮都带全部历史与全部工具"。按角色拆分工具集、把长材料交给 AgentTool 子 Agent、路由用 flash 类模型,是最有效的三招。
④ 认证与多租户
Gemini API Key 模式简单但不适合多租户;Vertex 模式能用 IAM 与配额,但要求项目、区域、企业开关全部配对。多租户还要保证 user_id 与会话服务的作用域一致------否则会出现"用户 A 读到 B 的 user: 状态"。
⑤ 评估体系
adk eval 提供了指标,但数据集要自己维护。可行路径:把线上真实失败样例固化成 evalset,先只断言工具轨迹,再逐步加语义指标。没有"改动前后跑同一批"的机制,调提示词就是盲改。
⑥ 1.x → 2.x 迁移
2.0 把 Agent 变成图节点、禁止直接 append 事件、新增 node_info/output。迁移时最容易忽略的是自定义 Agent 的覆写点 :旧版 _run_async_impl 之类的写法在新版会被绕过,表现为"代码在跑但没生效"。迁移清单应以官方 2.0 变更页为准,并补齐一次全量回归。
学习路线与验收清单五阶段路线
五阶段路线
| 阶段 | 做什么 | 验收 |
| 1 · 跑通 | 单 Agent + 两个函数工具 | 用 adk web 能在浏览器里对话 |
| 2 · 状态 | 用 output_key 串两个 Agent | 第二轮能读到第一轮的结论 |
| 3 · 多 Agent | 分流 + 两个专家,一个用 transfer、一个用 AgentTool | 能说清两者控制权差异 |
| 4 · 拦截 | before_tool 拦危险操作、before_model 拦敏感词 | 拦截后对话能继续而不是崩 |
| 5 · 上线 | 换持久化会话 + 跑 adk eval + 部署 Cloud Run |
重启后会话还在,评估有基线 |
|---|---|---|
| [表 16:五阶段路线] |
- 能说清
LlmAgent与工作流 Agent 的区别,以及什么时候不该用 LoopAgent。 - 记住 state 的四种前缀,并知道为什么不能直接改
session.state。 - 能解释 transfer 与 AgentTool 在控制权和上下文上的差别。
- 能写出"拦截并给出原因"的
before_tool_callback,知道返回 dict 的含义。 - 知道
run_async产出的是事件流,最终答复要判is_final_response()。 - 知道
BIDI只对run_live有效。 - 部署时能说出三个必须指向外部存储的服务(session / artifact / memory)。
- 知道
adk web只用于开发调试。
一句话收尾
ADK 的学习曲线不在 API,而在三个"看不见的写回" :状态要靠 state_delta、控制权要靠 transfer、终止要靠 escalate。这三件事理解对了,剩下的都是配置与部署。
说明:
事实取自 Google ADK 官方文档与 PyPI(访问于 2026-11-19)。文档中 PyPI 与快速入门页对 Python 版本要求不一致(≥3.11 vs 3.10+),本文以 PyPI 为准并已标注;2.x 中 output_key、include_contents 等字段的文档展示位置有差异,output_key 已在会话状态文档中确认可用,include_contents 未在 2.x 页面确认。