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。
按四件套走:是什么、怎么用、值得学什么、同类怎么比。
本文提纲
- 是什么:Agent Config 定位与最小可用 YAML
- 怎么用:tools 五种引用、MCP、skills、sub_agents、workflow graph、运行与加载
- 值得学什么:反射式字段映射、图验证前置、模块 denylist、skills 三级加载
- 同类比较: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 三天能改成自己的路由环。
参考文档与链接
- 官方文档:Build agents with Agent Config,Agent Config syntax reference
- 主仓库:google/adk-python(Apache 2.0,PyPI 包 google-adk,当前 2.14.1)
- Workflow graph 文档:Graph-based agent workflows(ADK Python/TypeScript/Go v2.0.0 起支持),源文件在仓库 docs/guides/workflow/graph/index.md
- Skills 文档:源文件在仓库 docs/guides/skills/skill/index.md,规范站点 agentskills.io
- YAML 样例:workflows/loop_config、multi_agent_basic_config
- 延伸阅读:Kaggle Gemma 4 Developer Agent 拆解:这题是啥,怎么解 — 本站同日文章,ADK Agent Config 在比赛里的实战形态
你的 agent 编排还全写在 Python 里吗?会放心把 YAML 图交给运营直接改吗?评论区聊聊你的选型。觉得有用点个赞。
作者: itech001
来源: 公众号:AI人工智能时代(the-ai-era)
网站: https://www.theaiera.top/
关注每日最新AI新闻和技术博客,主页有更多的文章的AI 技术参考:https://www.theaiera.top

浙公网安备 33010602011771号