Google ADK：Agent开发套件实战

可视化演示

展示ADK模块化架构、工具注册调用流程、多Agent协作拓扑。切换模式理解Google Agent开发套件从意图理解到部署监控的全链路设计。

框架全景：认识这台“后厨中枢”

一家智能餐厅后厨要想高效运转，不能只买一口锅。它需要燃气灶、刀具、冰箱、叫号大屏和一套排班表。Google ADK 就是给 AI Agent 准备的全套后厨设备：从理解顾客需求，到调用工具、记住偏好、协调多岗位厨师，再到最后出菜和检查是否超时，都在同一套系统里完成。这套设备的强大之处，在于它把零散的组件归纳成一个统一框架。

ADK 把 Agent 抽象成四个核心对象：模型、工具、会话状态和编排器。模型负责思考，工具负责行动，会话状态让它记住前文，编排器则决定每一步的先后顺序。开发时，你只需要声明这四者，ADK 会自动把零件组装成完整服务，像后厨设备已经接好水电，厨师插上电就能开工。

在实际项目中，ADK 深度集成 Gemini 模型，意味着你可以直接使用多模态输入、流式输出和函数调用能力。同时它提供从 Python 原型到生产部署的完整路径：本地调试与线上运行使用同一套代码，上线后交给 Cloud Run 或 Cloud Functions 托管。工具链还包括日志、追踪和评估模块，让 Agent 从“能跑”走向“能落地”。

想象后厨从采购到出菜都有了固定流程，ADK 就是把流程固化成软件的工程化框架。框架全景让你在写第一行代码前，就知道灶台、刀具、冰箱分别放在哪里。

意图理解：听懂顾客的弦外之音

顾客说“今儿人多，少放点盐”，后厨不仅要听懂内容，还要懂得这是“少盐”指令。意图理解是 Agent 的第一道工序。ADK 会让 Gemini 将用户输入映射成结构化的函数调用意图，而不是简单地做关键词匹配。同一种需求，用户说“查订单”还是“我的快递呢”，最终都能映射到同一个查询动作。

这里的关键是“函数调用映射”。模型输出一个结构化的动作，例如 query_order(order_id="9527")，就像服务员把顾客的话翻译成一张点菜单。同时，ADK 原生支持多模态输入：文本、图片、音频都可以作为点单方式。你发一张截图说“这个订单怎么回事”，Agent 也能看懂图里的订单号。

意图理解之后是流式输出。模型不是等整段话算完才回答，而是像主厨一边炒菜一边让服务员先上凉菜：首字延迟低，用户体感更接近真人对话。

顾客的语言千变万化，但后厨只需要听懂“加辣、免葱、多点饭”这几个关键动作。意图理解就是帮 Agent 从五花八门的话里，找到那个准确的动作按钮。

工具注册：给厨师挂上厨具清单

后厨的刀具、烤箱、食材都要有自己的“位置和用法说明”，否则厨师会拿错工具。工具是 Agent 与外部世界交互的窗口。在 ADK 中，你可以用装饰器或配置声明一个工具，每个工具包含四个要素：名字、描述、参数结构和执行函数。

工具注册表是一个动态注册中心，Agent 启动时把工具挂上去，运行时模型根据描述判断该用哪个工具，再根据参数 Schema 校验模型生成的入参是否合法。如果用户说“帮我订下周一去上海的机票”，模型可能生成 search_flights(departure="北京", arrival="上海", date="2026-01-19")，Schema 会确保日期格式正确。

工具调用失败时，ADK 不会粗暴结束对话，而是把错误信息回传给模型，让它尝试换一种方式重试。这就像厨师炒菜发现没盐，不是直接端上桌，而是立刻让帮厨补货再补救。

一个工具就是一张厨具卡，挂在后厨墙上。模型不一定看得懂每把刀的材质，但只要看清卡片上的用途说明和操作步骤，就能在正确的时机抽出正确的工具。

会话管理：记住老顾客的口味偏好

餐厅会记住老顾客的忌口和偏好：王先生不吃香菜，李女士要少辣。会话管理就是 Agent 的记忆库。ADK 提供 SessionState 对象，保存消息历史、工具调用结果和自定义变量。每次新请求都在旧状态上更新，让多轮对话像聊天一样连贯。

但上下文窗口是有限的，就像餐桌只有那么大，不能无限堆盘子。ADK 会做压缩和截断：把早期对话概括成摘要，丢弃过期的中间消息，保留关键信息。长会话还要支持持久化，把状态写入数据库，避免服务重启后顾客的记忆全部清零。

会话更新遵循一个简单逻辑：以上一轮工具的真实结果作为事实来源，而不是让模型凭空想象。这样即使模型回答有误，工具返回的订单状态、用户信息也能及时纠正对话方向。

会话状态就像一桌食客从进门到结账的完整记录。ADK 负责把“谁点的、加过几次菜、有什么忌口”都写在一本账上，顾客每一轮提问，都像在提醒服务员：“我刚才说的你还记得吧？”

多智能体协作：让宴席交给团队

宴席不是一位厨师从头包到尾，而是配菜、热炒、面点各司其职。复杂任务同样需要多个专职 Agent。ADK 支持异步委托：主 Agent 先分析请求，再把子任务拆给擅长对应领域的子 Agent，最后聚合所有结果，形成统一回答。

任务拆分要保证子任务互不重叠，才能避免两个厨师做同一道菜。协作拓扑可以是星型（主 Agent 统一调度）、层叠（逐级下发）或流水线（前一个 Agent 的输出是后一个的输入）。ADK 通过 sub_agents 配置和专用回调通道管理消息传递，主 Agent 不必关心每个子任务的具体实现。

这种模式特别适合“数据分析”类任务：先由一个 Agent 查数据库，一个 Agent 做图表，一个 Agent 写报告，最后主 Agent 把三份成果拼成完整答案。每个 Agent 的工具和指令都更聚焦，容易维护。

多人后厨讲究分工明确、配合默契。多 Agent 协作把这种默契编码到系统里：每个 Agent 专注一个岗位，主 Agent 负责统筹，最终把一盘盘菜拼成一桌完整宴席。

部署监控：后厨大厅的进度屏

后厨大厅有一块屏幕，显示每桌出菜进度和超时预警。Agent 上线只是第一步，ADK 部署到 Cloud Run 后，管理员需要日志、指标和追踪来保障服务质量。可用率是最直观的健康信号：系统在观测周期内有多少时间是正常出菜的。

每次请求都会生成追踪 ID，像给每桌客人一张排队小票，可以跨会话定位故障发生在哪一步：是意图理解慢，还是工具调用失败，或是流式推送中断。监控面板展示调用量、延迟分位数、错误率，设置告警规则后指标超阈值会自动通知负责人。

除了可用率，还要关注上下文长度分布和资源配额。如果同一时间涌入太多用户，Cloud Run 会自动扩容实例，但也需要设置最大并发避免账单爆炸。生产级 Agent 不是“写完代码就结束”，而是上线后持续观测、迭代。

部署监控就像后厨门口的电子屏：哪一桌等太久，哪道菜做失败，一眼看穿。ADK 让 Agent 的可观测性原生内置，你不必从零搭一套监控系统，而是直接看到“每个环节花了多久、错在哪里”。

AI 应用场景

Python 演示

import refrom typing import Callable  class KitchenAgent:    """极简版 ADK 演示：工具注册 + 意图理解 + 会话记忆"""     def __init__(self):        self.tools = {}        self.history = []     def register_tool(self, name: str, desc: str, func: Callable) -> None:        self.tools[name] = {"desc": desc, "func": func}     def understand(self, query: str) -> str:        if "查" in query and "订单" in query:            return "query_order"        if "点" in query and "菜" in query:            return "add_dish"        if "退" in query or "取消" in query:            return "cancel_order"        return "unknown"     def run(self, query: str) -> str:        intent = self.understand(query)        self.history.append((query, intent))        if intent in self.tools:            return self.tools[intent]["func"](query)        return "抱歉，我没听懂，请换个说法。"  def make_query_order():    def func(query: str) -> str:        match = re.search(r"\d+", query)        order_id = match.group(0) if match else "未知"        return f"订单 {order_id} 正在配送中。"    return func  def make_add_dish():    def func(query: str) -> str:        return "已为您加菜，请稍候上桌。"    return func  def make_cancel_order():    def func(query: str) -> str:        return "订单已提交取消申请。"    return func  def main() -> None:    agent = KitchenAgent()    agent.register_tool("query_order", "查询订单状态", make_query_order())    agent.register_tool("add_dish", "向订单添加菜品", make_add_dish())    agent.register_tool("cancel_order", "取消订单", make_cancel_order())     print(agent.run("帮我查一下订单 9527 到哪了？"))    print(agent.run("再加一份甜品"))    print(agent.run("我不想要了，取消吧"))    print("会话记忆：", agent.history)  if __name__ == "__main__":    main()

1. self.tools = {}创建一个动态注册中心，后面注册的工具都会放进来。
2. def register_tool(self, name, desc, func)对应 ADK 的工具注册，把名字、描述和函数绑定。
3. def understand(self, query)模拟意图理解，把口语映射到结构化动作。
4. self.history.append((query, intent))保存每一轮对话，模拟 SessionState 的记忆写入。
5. if intent in self.tools检查当前意图有没有对应的工具可用。
6. agent.register_tool("query_order", ...)像在 ADK 里声明一个 @tool，挂到注册中心。
7. print("会话记忆：", agent.history)展示多轮对话后的状态积累。

常见误区

面试题