2025年初谷歌正式开源了自家的智能体开发套件Agent Development KitADK这个动作直接把不少人的目光从各类通用Agent编排框架上拽了过来。ADK给我的第一印象是它不是一个强调“编排一切”的重框架而是一套更贴近工程直觉、强调可观测性和状态管理的轻量级开发工具。它把智能体开发拆得很干净用Agent类去组织业务逻辑用Tool去接外部能力用Session去管状态用一个统一的事件循环去跑整个会话。如果你正被各种Agent框架搞到选择困难或者已经上手过一些工具但还是搞不清内部组件怎么协作这篇内容会帮你建立一套判断标准一个成熟的智能体框架核心组件到底应该有哪些它们之间是怎么配合的。1. 为什么需要一套“智能体开发套件”架构设计的出发点1.1 大模型应用开发的三个老大难智能体开发跟传统后端开发不太一样。传统后端是“入参-处理-出参”的线性模型请求进来逻辑处理结果返回一次调用结束。智能体则是一个循环模型先决定要不要调用工具工具返回结果模型再基于结果继续推理直到它认为任务完成。这个循环本身不难理解难的是落到工程上有三个问题绕不开。第一个是上下文管理。LLM一次请求能接收的token有限但一个真实对话往往会拉得很长。你不能把整场历史都塞进模型输入又不能随意丢掉关键信息否则对话到一半智能体就像失忆了一样。第二个是工具接入。企业里大部分能力都封装成REST API、数据库查询、甚至命令行脚本智能体要调用它们就必须有一套统一机制去描述、注册、调用这些能力并且能把错误信息准确反馈给模型。第三个是可观测性。模型一步一步做了什么推理、调用了哪个工具、结果是什么这些过程如果不暴露出来出问题你连排查的入口都找不到只能对着黑盒干瞪眼。ADK的架构正是针对这三个问题设计的Session负责上下文管理Tool负责外接能力事件循环和Runner负责暴露运行全过程。这也是我评价一个Agent框架是否成熟的第一条标准它有没有把这三个问题当成一等公民来设计而不是靠开发者自己拼拼凑凑。1.2 整体架构的分层逻辑ADK的整体架构可以用一个剧组来类比。Agent是导演它决定这场戏怎么演指令怎么写、调用哪些工具、子任务交给谁。Tool是道具组和群演提供各种能力查数据库、调接口、读写文件。Session是场记把每一条指令、每一次工具调用结果、每一个中间状态都记录下来确保拍摄进度不丢。Runner则是执行导演兼现场监控它把导演的想法转成具体的执行动作并且让每个环节的进度都能被外部看到。这个分层带来的直接好处是解耦。你可以只改Agent的指令而不动状态存储逻辑你可以换掉底层模型而不影响工具层你甚至可以脱离业务代码单独查看一个会话的状态流转。我做过几个Demo之后最直观的感受是调试时间被大幅压缩。不再需要在日志里翻来翻去找哪一步出了问题直接看事件流就能定位是模型决策错了还是工具调用挂了还是状态清理逻辑有问题。还有一点值得说ADK的Agent是树状组合而不是简单的线性链式调用。一个根Agent下面可以挂多个子Agent根Agent负责整体调度子Agent负责具体领域的子任务。这种设计符合真实业务里的分工逻辑也让单个Agent的指令保持精简避免把几十条复杂业务规则堆到一个Prompt里最后谁也不知道模型会偏向哪条。1.3 与通用Agent框架的定位差异轻量、可观测、可嵌入拿一些人用过的主流Agent编排框架来对比ADK的定位差异挺明显。很多通用框架的价值在于调度灵活你可以把它当作一颗大脑什么流程都能编排代价是你要学习它的抽象概念并且出了问题往往要开着分布式追踪去查。ADK则更偏“默认约定”它预设了一套标准的运行循环、标准的状态机制、标准的事件流你在这个约定里写业务而不是从头搭建一套流程。这意味着两件事。第一上手成本低核心概念就那几样跑通Demo不用学很多抽象术语。第二可观测性天生就好因为所有会话都在框架的统一循环里跑事件是结构化的日志天然完整。但这也有代价如果你需要非常自定义的调度逻辑比如把多个模型组合成一个非Agent的奇怪管道ADK反而会显得不那么灵活。所以这个套件更适合的场景是业务逻辑清晰、需要跟外部系统打交道、并且后续要长期维护的项目。2. 核心组件逐个拆解Agent、Tool、Session、Artifact2.1 Agent类一切智能体的起点在ADK里一个智能体的起点是Agent类。你需要告诉它三件事它叫什么、它该遵循什么指令、它能用哪些工具。最基本的写法大致如下from google.adk.agents import Agent agent Agent( namecustomer_service, instruction( 你是一名电商平台的客服助手。请根据用户的订单状态和售后政策 耐心解答问题。如果用户需要查询订单请调用订单查询工具。 ), modelgemini-2.5-pro, tools[查询订单工具, 申请售后工具], )这里的instruction就是Agent的“岗位说明书”它决定了模型在对话里以什么身份、按什么准则去回复。注意指令写得越具体工具的使用边界越清晰模型就越不容易产生幻觉式调用。树状组合是让我觉得最有工程价值的设计。你可以创建一个根Agent它只负责判断用户意图然后派发给不同子Agent去处理比如一个负责售前咨询一个负责售后流程。这种结构有几个好处每个Agent只关注自己的领域指令不会越写越臃肿单个Agent的上下文里不会塞入不相关的工具描述token占用更可控团队协作时不同人维护不同的子Agent互不干扰。我实际用下来的经验是子Agent划分的粒度要以“独立职责”为准别为了拆而拆。如果一个子Agent只需要一个工具、一段简单指令就能完成任务那就没必要单独建一个类直接放在根Agent的工具列表里更省事。拆得细碎不仅增加调度开销还会让排查问题时得多跳好几层。2.2 Tool机制从Python函数到LLM工具Tool是智能体的手和脚。ADK里定义一个工具最直接的方式是写一个普通Python函数然后用装饰器标记一下。关键在于函数的类型注解和文档字符串因为框架会把这些信息自动组装成模型能理解的工具描述。from google.adk.tools import tool tool def get_order_status(order_id: str) - str: 根据订单号查询订单的当前状态。 Args: order_id: 用户提供的订单编号。 Returns: 订单状态的文字描述包含物流信息和预计送达时间。 status query_oms(order_id) return f订单状态{status[phase]}物流公司{status[carrier]}预计送达{status[eta]}这里面有个细节容易被忽略工具的返回值一定要是“对模型友好的、结构化的自然语言”。模型看到返回值后会基于它继续推理并组织给用户的回答。你返回一段JSON没问题但如果你返回一大坨火星文级别的原始日志模型很容易理解偏。我通常会在工具内部把关键信息过滤一遍再拼成一句简短、完整的话返回。这样比直接抛原始对象要稳得多。错误处理也一样。工具内部如果抛异常框架会把异常信息返回给模型模型可能就被错误栈带偏了。更稳妥的做法是在工具内部捕获异常返回一段人能看懂的错误描述tool def get_order_status(order_id: str) - str: ... try: data query_oms(order_id) except NotFoundError: return 未找到该订单请核对订单号。 except TimeoutError: return 订单系统当前响应较慢请稍后再试。 return f订单状态...这么处理后模型在遇到错误时还能继续对话给出安抚话术而不是直接报错。工具是智能体的能力边界这个边界上的代码质量直接决定了整个智能体的可用性。2.3 Session状态让智能体“记住”上下文Session是ADK里容易被新手低估的组件。很多人的第一反应是会话历史不是模型上下文里有吗为什么还要单独搞一个Session理由很实际。模型上下文里的对话历史只是Session的一部分。Session还要保存应用状态比如用户已经选了哪个商品、某个流程进行到哪一步、工具返回过什么关键结果。这些数据不一定适合塞回Prompt但它们确实是整个任务推进必需的“工作记忆”。Session把这些数据集中管理才能实现会话中断后恢复、不同入口之间的状态共享、以及多轮对话中的信息沉淀。ADK里Session的典型使用姿势是把状态存到一个dict里框架会自动帮你持久化。比如一个跨轮次收集信息的表单场景session.state.setdefault(order_info, {}) session.state[order_info][address] user_input这里注意一点会话上下文是有限的不可能无限增长。当对话轮数多了早期信息会被压缩或丢弃所以关键业务数据一定要主动落到Session的state里而不是依赖模型记得。我踩过的一个坑是把用户填好的收货地址只写在对话历史里结果上下文窗口一挤压模型就把地址忘了还得再问一遍用户。后来统一改成每次地址信息都写入state这个问题就消失了。Session还支持分节和恢复。这就像游戏存档你可以把一次较长的任务切成多个Session也可以让用户隔几天回来继续上一次的对话。工程上这意味着智能体不需要常驻内存它只需要在每次请求进来时加载对应Session跑完再存回去。对线上服务来说这种设计能省下不少成本。2.4 Artifact与MCP能力的边界与扩展除了工具调用智能体还有一个常见的需求生成并保存文件。ADK里用Artifact这个概念来管理这类产出物。它不只是一个文件路径而是一个带元数据的对象能记录是谁生成的、在什么时候生成的、属于哪个会话。比如让智能体生成一份Excel报表或PDF合同产出物会被登记成Artifact后续可以继续被引用、下载或覆盖。这种抽象对于“边聊边干活”的场景非常有用。用户让智能体写份周报智能体生成Markdown文件用户说“帮我改成PDF”智能体可以直接基于上一个Artifact继续处理而不是从头再生成一遍。MCP则是ADK用来接入外部工具生态的协议。简单说MCP把各种外部系统的能力描述成统一格式ADK作为客户端去发现、调用这些能力。这意味着你不需要为每个新的外部系统单独写一套适配代码只要对方提供MCP服务ADK就能直接接进来。有点像给智能体装了一个标准化的USB接口什么设备都能插只要对方遵守协议。我用MCP接过一个内部数据平台的查询服务过程确实比手动封装REST API顺畅得多。工具描述、参数结构、调用地址都由服务端发布ADK这边只需要注册一下端点就能自动获取。对团队来说这种扩展方式还带来一个额外好处工具定义离业务方更近维护成本更低。3. 从零搭建一个可运行的智能体实操与代码剖析3.1 环境准备与项目初始化实际操作从环境准备开始。假设你有一台能跑Python的机器版本建议3.10以上。安装ADK只需要一行命令pip install google-adk安装完成后推荐按下面的目录结构组织项目。这个结构不是强制的但按照职责分层放后面维护会舒服很多agent_project/ ├── agents/ │ └── customer_service.py ├── tools/ │ └── order_tools.py ├── main.py └── requirements.txtagents目录放Agent定义tools目录放工具函数main.py作为入口。这种拆分的好处是Agent定义和工具实现互不干扰。工具层的逻辑往往变化频繁比如接口换了、字段改了都在tools目录里解决不用动Agent定义。3.2 定义一个带工具的Agent下面用“订单查询助手”这个小项目把整个流程串起来。先定义工具# tools/order_tools.py from google.adk.tools import tool tool def get_order_status(order_id: str) - str: 查询订单状态。 Args: order_id: 用户提供的订单编号通常是纯数字字符串。 if not order_id.isdigit(): return 订单号格式不正确请确认后重试。 # 模拟查询结果真实项目这里替换成内部接口调用 return f订单 {order_id} 已发货预计明天送达。 tool def cancel_order(order_id: str) - str: 取消订单。 Args: order_id: 需要取消的订单编号。 return f订单 {order_id} 已取消退款将在1-3个工作日原路退回。这段代码里有两个点值得注意。一是每个工具都写了文档字符串参数含义写得清清楚楚这直接决定模型能否正确理解工具作用二是工具内部做了简单的输入校验避免把明显不合法的情况抛给下游系统。接下来定义Agent# agents/customer_service.py from google.adk.agents import Agent from tools.order_tools import get_order_status, cancel_order agent Agent( namecustomer_service, instruction( 你是一个电商客服助手。用户可能查询订单状态或申请取消订单。 查询订单时调用get_order_status取消订单时调用cancel_order。 正式回复时语言要友好简洁。 ), modelgemini-2.5-pro, tools[get_order_status, cancel_order], )这里没有写什么高深语法但每个字段的取舍都是有讲究的。instruction越具体模型越不容易乱来。我没有把工具名称写死在指令里让模型死记而是靠工具自身的文档描述让模型自动发现。这样工具列表即使增加几个指令也不用频繁改动。3.3 运行与调试三种Runner的使用姿势ADK提供了几种运行方式适用不同阶段。最常用的是直接跑命令行CLI适合快速验证单次对话。启动方式很简单adk run然后在终端里输入问题智能体就会开始推理并调用工具。这种方式对快速验证“工具调不通”“指令没生效”这类问题最直接。如果你需要更直观地观察Agent每一步的输入输出可以用Web UI模式adk webWeb UI的好处是能看到事件流。模型发了什么请求、工具返回了什么结果、Agent在哪个环节做了错误处理一目了然。这个可视化能力在做复杂多轮对话调试时几乎必不可少比翻终端日志强太多是我个人最推荐的调试方式。还有一种偏生产环境的用法是把ADK应用包装成OpenAPI接口通过HTTP对外提供服务。ADK自带相关的服务封装你只需要启动应用并暴露端口之后就可以用标准的HTTP客户端去调用。这种模式适合把智能体嵌进已有业务系统比如用在一个客服后台的工单创建页面里。三种Runner的选择其实就是一个判断CLI适合快速冒烟测试Web UI适合深度调试OpenAPI模式适合集成上线。我实际项目中常用的节奏是CLI先跑通核心流程再用Web UI观察一次完整对话的事件流确认决策和工具调用都符合预期最后才切到服务化模式对接业务方。3.4 部署与扩展思路当智能体要真正上线部署层面有几个问题需要提前考虑。第一是模型API的配额和限流多用户并发访问时如果模型接口被限流Agent会频繁重试体验很差。第二是Session持久化的存储位置。本地文件系统够用但多实例部署时就要换成共享存储否则用户请求被路由到不同实例Session对不上。第三是日志和监控。ADK的事件流是天然的结构化日志建议在发布环境里把事件全部采集下来这样线上出问题才能回溯。扩展方面一个比较实用的模式是“一个入口多个子Agent”。根Agent负责判断用户意图子Agent负责具体领域。比如订单查询、售后申请、优惠券核销各一个子Agent。这样每个子Agent可以独立迭代甚至可以由不同团队维护。我体验过这种模式的维护体验改动某个子Agent的指令完全不影响其他模块上线回归成本很低。4. 常见问题与排查技巧实录4.1 工具调用掉进“死循环”第一个常见问题是智能体反复调用同一个工具不往下走。典型的场景是智能体调用查询工具后返回结果里说“查不到”但模型不死心换个参数再查一遍来回五六次才放弃。这个问题根子通常在工具返回值上。返回值里没有给模型明确的“终止条件”。解决办法很简单在工具返回里加上明确的结论提示比如“这个订单号不存在请告知用户并提供下单方式不要再尝试查询”。模型看到“不要再尝试”的指令通常会及时收手。另外可以给Runner设置单次执行的最大轮数限制。ADK里可以通过相关超时参数控制超过轮数直接强制结束防止成本失控。4.2 会话失忆与上下文超限第二个常见问题是会话失忆。用户前面说到一半的信息后面再问相关细节智能体一脸茫然。排查时先确认Session有没有正确加载再确认关键状态是不是存在了Session的state里而不是只靠对话历史记忆。如果Session没问题但对话一长就失忆那大概率是上下文窗口碎片化导致的。模型只会保留最近的部分历史早先的细节被挤掉了。解决办法是把业务关键信息主动抽取到state中并考虑在长对话中把已完成环节的信息做“摘要化”。具体做法是每当一个子任务完成就用模型把结论精简成几句话存起来后续对话只引用摘要不翻原始记录。这样既保住了关键信息又控制了上下文长度。4.3 调试效率提升的实用技巧最后聊几个能让调试轻松很多的技巧。第一给工具写严格的入参校验。很多“工具调用失败”的问题根因不是工具逻辑错了而是模型生成了不合法参数。工具内部做一次类型和取值范围校验可以省掉大量排查时间。第二充分利用事件流。Web UI里一个完整会话的事件顺序是固定的模型请求发出工具调用请求工具返回结果模型再次请求。你要定位问题先找事件流里在哪一环节断了基本能锁定八成问题。第三写单测。ADK支持针对单个Agent和工具做单元测试把典型对话场景和典型工具输入固化下来每次改完代码跑一遍比每次都用真实模型试错效率高得多。我个人踩过几次坑之后的体会是这个套件最舒服的用法是把注意力集中在工具质量和指令设计上而把循环控制、状态持久化、事件记录这些脏活交给框架。只要Session用对、工具返回规范、调试时多利用事件流几个核心组件能配合得很顺。对于大多数想落地智能体功能、又不希望被过度复杂的调度抽象拖住的团队ADK是值得一试的选择。