Google ADK 学习指南

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 页面确认。

相关推荐
郝学胜-神的一滴41 分钟前
Effective Python 条款35:用类封装替代生成器异常注入
开发语言·人工智能·python·金融·pandas·scikit-learn·matplotlib
塑料铲子42 分钟前
你的 Skill 越多越蠢?Token 上下文爆炸的求生指南
机器学习·agent
LK_071 小时前
【力扣】142. 环形链表 II |Python
python·leetcode·链表
wuyk5551 小时前
Python办公自动化-第02讲-Excel文件认知与四大库选型
开发语言·python·excel
qinglongcn1 小时前
四面统一:记忆/Session/观测/Cron
agent·ai编程
货拉拉技术1 小时前
AI Agent 如何进入实时交易系统:货拉拉的三个实践与一套工程方法论
后端·架构·agent
qinglongcn1 小时前
从 metadata 键到独立列
agent·ai编程
小龙66662 小时前
给 Agent 一张地图,而不是一座迷宫:前端 monorepo 目录结构重构实录
前端·agent