Google ADK 用 YAML 建 agent:工具、MCP、skills 与 workflow graph

Google ADK 用 YAML 建 agent:工具、MCP、skills 与 workflow graph

写个 agent 要开 Python 工程的日子在 Google 这边翻篇了:一个 root_agent.yaml,从模型、指令、工具、MCP 服务器、skills 一直到多 agent 有向图,全部声明式写完,CI 里改个 YAML 就换掉整套路由。

ADK(Agent Development Kit)是 Google 的开源 agent 框架,google/adk-python 到我查的 2026 年 11 月 18 日有 22,260 stars,Apache 2.0 协议,PyPI 最新版 google-adk 2.14.1。它的 Agent Config 特性让你用一个 YAML 文件组装并运行完整 agent,官方说法是 "build an ADK workflow without writing code"。上一篇拆 Kaggle Gemma 4 赛题时提过,比赛的 agent.yaml 走的就是 ADK Agent Config 规范,这篇把这个格式本身拆透:基础字段、tools 的五种挂法、MCP 和 skills 怎么接、sub_agents 怎么委派,以及 ADK 2.0 新出的 graph-based workflow engine 怎么直接在 YAML 里写 nodes 和 edges。

按四件套走:是什么、怎么用、值得学什么、同类怎么比。

本文提纲

  1. 是什么:Agent Config 定位与最小可用 YAML
  2. 怎么用:tools 五种引用、MCP、skills、sub_agents、workflow graph、运行与加载
  3. 值得学什么:反射式字段映射、图验证前置、模块 denylist、skills 三级加载
  4. 同类比较:Python 版 ADK、LangGraph、Kaggle 封闭 harness

是什么:一个 YAML 就是一个 agent

Agent Config 的定位写在文档第一句:用 YAML 文本文件代替代码来组装 ADK workflow。适用场景也很明确:workflow 形状比底层代码变得更频繁的时候,CI/CD 流水线、按租户路由、运营人员不改包发版就能调图。

最小可用配置只要四个字段:

# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json
agent_class: LlmAgent
name: assistant_agent
model: gemini-flash-latest
instruction: You are an agent to help answer users' various questions.

agent_class 决定建哪类 agent,默认 LlmAgent,可选的还有三个编排类:LoopAgent(带 max_iterations 的循环)、ParallelAgent(子 agent 并行跑)、SequentialAgent(子 agent 顺序跑),以及 ADK 2.0 的 Workflow(有向图,下文细说)。instruction 是系统提示词,model 不设则从祖先 agent 继承。

生成骨架一条命令:adk create --type=config my_agent,产出 root_agent.yaml 和 .env,.env 里放 GOOGLE_API_KEY 或 Vertex 项目的环境变量。注意这个特性还是 Experimental 状态,目前只支持 Gemini 模型,第三方模型接入在做。

官方还贴心地在 YAML 头部放了一行 schema 注释,VS Code 的 yaml-language-server 会直接对每行字段做补全和校验,写错了立刻飘红。

怎么用:六种部件逐个挂

六种部件全部挂在一个 root_agent.yaml 上,加载后变成活 agent:

MERMAID_BLOCK_0

一,内置工具:一行 name

tools 列表里写 name 就能挂 ADK 自带工具,比如搜索:

tools:
  - name: google_search

Agent Config 目前确认支持的内置工具有 13 个左右:google_search、google_maps_grounding、load_artifacts、url_context、exit_loop、preload_memory、get_user_choice、enterprise_web_search、load_web_page、AgentTool、LongRunningFunctionTool、McpToolset、ExampleTool。其中 AgentTool 很特别,它让一个 agent 把另一个 agent 当工具调,参数直接引用 YAML:

tools:
  - name: AgentTool
    args:
      agent: ./another_agent.yaml
      skip_summarization: true

二,自定义工具:函数、类、工厂函数三种引用

自己写的工具按"全限定名"引用,相当于 import 路径:

tools:
  - name: ma_llm.check_prime        # 函数工具
  - name: my_package.my_module.my_tool_class    # 工具类,配 args 即构造参数
    args:
      my_tool_arg1: value1
  - name: my_package.my_module.my_tool_function # 工厂函数,返回 BaseTool

工厂函数的签名约定是 def my_function(args: ToolArgsConfig) -> BaseTool,YAML 里的 args 原样传进去。

三,MCP:官方姿势是 Python 定义、YAML 引用

MCP 服务器连接参数(stdio 命令、环境变量、认证头)本身是嵌套对象,官方推荐的写法是在 Python 文件里定义好 toolset 实例:

# tools.py
my_mcp_toolset = MCPToolset(
    connection_params=StdioServerParameters(
        command="npx",
        args=["-y", "@notionhq/notion-mcp-server"],
        env={"OPENAPI_MCP_HEADERS": NOTION_HEADERS},
    )
)

然后 YAML 里一行引用:

tools:
  - name: tools.my_mcp_toolset

逻辑分界线很清楚:声明性强的部分(挂哪个工具、什么参数)留在 YAML,连接细节(密钥、命令行)留在 Python 和 .env 里,不进版本库。

四,skills:SKILL.md 三级加载

skills 是 ADK 2.0 引入的懒加载知识包,一个 skill 是一个文件夹:

weather-skill/
  SKILL.md          # 必需:YAML frontmatter + markdown 指令
  references/       # 可选:参考文档
  scripts/          # 可选:可执行脚本
  assets/           # 可选:数据文件

加载遵循三级原则:模型的上下文里平时只放每个 skill 的 name 和 description(一级,几十个 skill 的目录成本几乎为零);模型判断某个 skill 跟当前任务相关后才读 SKILL.md 正文(二级);正文让它去取的具体文件和脚本再按名字单独加载(三级)。SKILL.md 的 frontmatter 校验很严:name 必须是小写 kebab-case、不超过 64 字符、必须等于目录名;description 非空且不超过 1024 字符,错了直接 ValueError。

接入 agent 时用 SkillToolset 包一层,同样是 Python 定义实例、YAML 引用的套路。toolset 会向模型发布 list_skills、load_skill、load_skill_resource、run_skill_script 四个工具,模型靠调工具逐级取内容。Kaggle Gemma 4 赛题提交包里的 skills 目录(SKILL.md 加 scripts 加 resources)就是这个规范的同款结构,两边是同一个设计思想的两次落地。

五,sub_agents:config_path 引用兄弟文件

根 agent 用 sub_agents 把活儿委派出去,每个子 agent 一个 YAML 文件:

agent_class: LlmAgent
name: root_agent
instruction: |
  You are a learning assistant. Delegate coding questions to
  code_tutor_agent and math questions to math_tutor_agent.
sub_agents:
  - config_path: code_tutor_agent.yaml
  - config_path: math_tutor_agent.yaml

根 agent 靠读子 agent 的 description 决定转给谁,所以 description 写得好坏直接决定路由质量。子 agent 文件里也可以再挂自己的 sub_agents,形成树;sub_agents 的引用除了 config_path 还可以是 code,即 Python 全限定名,两种都能混着用。

六,workflow graph:ADK 2.0 的非线性编排

这是 2.0 的新东西:graph-based workflow engine,支持把 nodes 和 edges 直接写在 YAML 里,由 loader 解析成 workflow graph 执行对象。写法是 agent_class: Workflow 加一个 edges 列表,官方仓库里的真实样例(loop_config,一个"生成标题、评估、不达标就打回重写"的反馈环)长这样:

agent_class: Workflow
name: root_agent
edges:
  - - START
    - .agent.process_input
    - generate_headline.yaml
    - evaluate_headline.yaml
    - .agent.route_headline
  - - .agent.route_headline
    - unrelated: generate_headline.yaml

edges 里每个条目是三种形态之一:

形态 长相 语义
链 - - START - a.yaml - b.yaml 相邻两项连成一条边,顺序执行
路由映射 refund: refund_handler.yaml 键是 route 名,源节点发这个 route 就走这条边;值是列表则扇出
显式边 from_node: classifier to_node: x.yaml route: refund 全量写法,前两种是它的缩写

节点位置上可以出现五种东西:START 哨兵、同文件里已经定义过的节点名、别的 YAML 的相对路径、Python 函数全限定名(自动包成 FunctionNode,节点名取函数名)、以及 inline mapping 就地定义一个小 agent。注意一个坑:inline 列表 [a, b] 在边里永远是扇出而不是链,想写链必须用 block 形式换行排。

整张图在 Workflow 实例化时就要过十关验证:节点名唯一、START 必在且无入边、START 出边不带 route、所有节点从 START 可达、无重复边、DEFAULT_ROUTE 不能和其他 route 混列、纯无条件环直接拒绝(条件环是合法的,这正是 loop 样例的写法)、上下游 schema 静态匹配、chat 模式的 LlmAgent 只能紧跟 START、节点自身还要校验它可能发出的 route 都有边接住。结构错误在写图阶段就报,不留到运行中。

运行、加载与安全

跑起来有四条路:adk web 起 UI、adk run 终端交互、adk api_server 起 HTTP 服务、代码里 config_agent_utils.from_config("root_agent.yaml") 直接拿到 agent 实例。目录约定是 {agent_name}/root_agent.yaml,CLI 找不到 Python 定义(init.py 或 agent.py)时才回退到 YAML,所以同一个目录可以从 Python 平滑迁到 YAML,但迁移期间 Python 定义必须删干净,否则它永远赢。部署上 Cloud Run 和 Agent Runtime 的流程与代码版 agent 完全一致。

安全设计有两层。带 _code 后缀的引用(函数、callback、schema)在 import 前要过模块 denylist,而且封的是整个标准库,官方理由很直白:精选黑名单守不住,cProfile.run、timeit.timeit 都能执行字符串,每个 Python 版本还可能加新的。文件引用拒绝绝对路径,只能碰兄弟和后代文件。丑话是官方自己说的:denylist 覆盖不了第三方包的执行入口,能指名任意模块的 config 要当可信输入对待;而且 args 键的 denylist 目前默认关闭(_ENFORCE_YAML_KEY_DENYLIST 是 False),默认拒绝还在路上,加载不受控配置的宿主要自己打开。

值得学什么

反射式字段映射是最省维护的设计。 loader 不为每个类写专属解析器,而是读目标类的字段注解,把 YAML 值逐一解析成字段期望的类型。类里加一个字段,YAML 立刻就能配,没有"解析器忘了更新"这种 bug。自研配置系统时这个模式能砍掉一整层胶水代码。

图校验前置到实例化时刻。 十条规则在 Workflow 构造时全查一遍,配错的结构当场死,而不是跑一半才炸。错误信息也讲究:包在 Pydantic ValidationError 里,但 ValidationError 是 ValueError 子类,except ValueError 照样接得住。给流程引擎做设计时,"错早点、错清楚"这一条值回票价。

skills 的三级懒加载是 token 经济学。 目录级 20 个 skill 的常驻成本接近零,指令体和资源只在相关性确认后进上下文。跟之前拆过的微软 TokenEconomizer 一个思路的两端:那边从会话历史学经验,这边把知识结构化成分层目录,共同敌人都是每 turn 的死权重 token。

连 Gemini 模型都有 schema 级补全。 文件头一行 schema 注释就把 yaml-language-server 变成专属校验器,这种一行成本的开发体验投资,比自己写 docs 提升大得多。

同类比较

方案 声明式程度 长处 短处
ADK Agent Config agent 全字段加 graph edges 全 YAML 一文件成军,CLI 到部署全链路 锁 Gemini,MCP/skills 复杂配置仍要 Python 落地
ADK Python API 纯代码 表达力最强,动态生成 graph 方便 改形状要发版,非程序员碰不了
LangGraph 图用 Python API 描述 生态大,checkpoint 成熟 无 YAML 一级格式,图结构散在代码里
Kaggle Gemma 4 harness YAML 声明加沙箱全托管 比赛环境公平可控 私有格式,出不了赛场

选型判断:已经在 Google 栈上(Gemini、Cloud Run、Vertex),Agent Config 直接用,graph 场景优先 YAML 而不是 Python,改图成本一个数量级的差距;要跨模型跨厂商,ADK 的模型锁是硬伤,LangGraph 或自建更稳;纯想在生产里管多 agent 路由,这套 YAML 图加 CLI 目录约定加部署同代码版三件事凑齐,已经是同类里最顺手的之一。要抄作业,官方 samples 仓库里有整套 config 样例,loop_config 三天能改成自己的路由环。

参考文档与链接

你的 agent 编排还全写在 Python 里吗?会放心把 YAML 图交给运营直接改吗?评论区聊聊你的选型。觉得有用点个赞。


作者: itech001
来源: 公众号:AI人工智能时代(the-ai-era)
网站: https://www.theaiera.top/
关注每日最新AI新闻和技术博客,主页有更多的文章的AI 技术参考:https://www.theaiera.top

posted @ 2026-11-18 22:38  iTech  阅读(2)  评论(0)    收藏  举报