adk-python 实践指南：用 YAML 配置搭建"编写-评审-重构"顺序执行的多 Agent 流水线
【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python
本文基于 multi_agent_seq_config 示例 展开，讲解如何用纯 YAML 配置在 adk-python 中定义一个顺序（Sequential）多 Agent 流水线：由快速廉价模型先写初版代码、再由同类模型做代码评审、最后由更强更慢的模型完成最终修订。读完本文，你能掌握SequentialAgent的配置结构、output_key在子 Agent 之间传递数据的底层机制，以及如何用adk run直接加载并运行这类配置型示例。
1. 示例定位：一个配置驱动的顺序工作流
示例位于 contributing/samples/multi_agent/multi_agent_seq_config，官方文档对其定位是"A multi-agent setup with a sequential workflow"（一个带顺序工作流的多 Agent 配置）。整个过程分三步：
- 由一个基于廉价快速模型的 Agent 写出初始版本代码；
- 由一个基于相同廉价快速模型的 Agent 评审代码；
- 由一个基于更聪明但更慢模型的 Agent 写出最终修订版。
官方给出的示例查询是：
Write a quicksort method in python
这个设计的要点在于按任务价值分配模型档位：初稿与评审对模型智力要求不高，用 flash 档模型控制成本与延迟；只有最后一步"吸收评审意见并产出成品"才升级到 pro 档模型。
目录结构
contributing/samples/multi_agent/multi_agent_seq_config/ ├── README.md ├── root_agent.yaml # 根 Agent：SequentialAgent，声明三个子 Agent └── sub_agents/ ├── code_writer_agent.yaml # 第 1 步：写初版代码 ├── code_reviewer_agent.yaml # 第 2 步：代码评审 └── code_refactorer_agent.yaml # 第 3 步：基于评审意见重构整条流水线没有任何 Python 业务代码，完全由 YAML 配置驱动——这正是该示例（目录名中的config后缀）要演示的核心能力。
2. 根配置：root_agent.yaml
根配置文件 全文如下（省略 License 注释）：
# yaml-language-server: $schema=https://raw.githubusercontent.com/google/adk-python/refs/heads/main/src/google/adk/agents/config_schemas/AgentConfig.json agent_class: SequentialAgent name: CodePipelineAgent description: Executes a sequence of code writing, reviewing, and refactoring. sub_agents: - config_path: sub_agents/code_writer_agent.yaml - config_path: sub_agents/code_reviewer_agent.yaml - config_path: sub_agents/code_refactorer_agent.yaml关键字段说明：
| 字段 | 取值 | 作用 |
|---|---|---|
agent_class | SequentialAgent | 声明 Agent 类型，配置加载器据此实例化顺序执行的 shell Agent |
name | CodePipelineAgent | 流水线名称，也用作 agent state 的键名 |
description | — | 对流水线的整体描述 |
sub_agents[].config_path | 相对路径 | 通过引用外部 YAML 文件声明子 Agent，按列表顺序执行 |
注意第一行yaml-language-server: $schema注释：它把编辑器的 schema 校验指向仓库内置的 AgentConfig.json，在 IDE 中编辑这些 YAML 时可获得字段级补全与错误提示。
sub_agents采用引用式声明而非内联定义，使得每个子 Agent 的配置独立成文件、可复用、可单独演进。列表中的顺序即执行顺序，这是SequentialAgent语义的直接体现。
3. 三个子 Agent 配置逐字段解析
三个子 Agent 都是LlmAgent，差异在于模型档位、指令与输出键。
3.1 第一步：CodeWriterAgent（写初稿）
code_writer_agent.yaml：
agent_class: LlmAgent name: CodeWriterAgent model: gemini-2.5-flash description: Writes initial Python code based on a specification. instruction: | You are a Python Code Generator. Based *only* on the user's request, write Python code that fulfills the requirement. Output *only* the complete Python code block, enclosed in triple backticks (```python ... ```). Do not add any other text before or after the code block. output_key: generated_codemodel: gemini-2.5-flash：快速低成本模型，承担对智力要求不高的初稿任务；- 指令中"Outputonlythe complete Python code block"这类严格输出约束很关键：它保证模型输出是可直接被下游解析的纯代码块，避免解释性文字污染产物；
output_key: generated_code：将该 Agent 的最终文本输出写入会话状态的generated_code键，供后续 Agent 使用。
3.2 第二步：CodeReviewerAgent（评审）
code_reviewer_agent.yaml：
agent_class: LlmAgent name: CodeReviewerAgent model: gemini-2.5-flash description: Reviews code and provides feedback. instruction: | You are an expert Python Code Reviewer. Your task is to provide constructive feedback on the provided code. **Code to Review:** ```python {generated_code}Review Criteria:
- Correctness:Does the code work as intended? Are there logic errors?
- Readability:Is the code clear and easy to understand? Follows PEP 8 style guidelines?
- Efficiency:Is the code reasonably efficient? Any obvious performance bottlenecks?
- Edge Cases:Does the code handle potential edge cases or invalid inputs gracefully?
- Best Practices:Does the code follow common Python best practices?
Output:Provide your feedback as a concise, bulleted list. Focus on the most important points for improvement. If the code is excellent and requires no changes, simply state: "No major issues found." Outputonlythe review comments or the "No major issues" statement. output_key: review_comments
这里有两个值得注意的细节： 1. **指令模板占位符 `{generated_code}`**：instruction 里直接用花括号引用上游 Agent 的 `output_key`。运行时框架会用会话状态中的对应值填充该占位符，从而把第一步的产物"注入"到评审 Agent 的提示词中——多 Agent 间的数据传递就是靠 `output_key` + 指令占位符这对机制完成的，无需任何胶水代码。 2. **兜底分支**："If the code is excellent and requires no changes, simply state: 'No major issues found.'" 为第三步的"无问题则原样返回"提供了明确的信号值。 ### 3.3 第三步：CodeRefactorerAgent（重构，升级模型） [code_refactorer_agent.yaml](https://link.gitcode.com/i/9dad58da7669bc95e0906362681262b9)： ```yaml agent_class: LlmAgent name: CodeRefactorerAgent model: gemini-2.5-pro description: Refactors code based on review comments. instruction: | You are a Python Code Refactoring AI. Your goal is to improve the given Python code based on the provided review comments. **Original Code:** ```python {generated_code} ``` **Review Comments:** {review_comments} **Task:** Carefully apply the suggestions from the review comments to refactor the original code. If the review comments state "No major issues found," return the original code unchanged. Ensure the final code is complete, functional, and includes necessary imports and docstrings. **Output:** Output *only* the final, refactored Python code block, enclosed in triple backticks (```python ... ```). Do not add any other text before or after the code block. output_key: refactored_codemodel: gemini-2.5-pro：这是流水线中唯一使用 pro 档模型的 Agent，把"更聪明更慢"的能力集中花在最终产出上；- 指令同时引用了
{generated_code}和{review_comments}两个状态键，即最后一步能看到"原始初稿 + 全部评审意见"两份上下文； - 明确约定了"若评审意见为 No major issues found 则原样返回"，使整个流水线在代码质量已达标时幂等收敛（输出与初稿一致），这是一个很实用的健壮性设计。
3.4 数据流总览
三步串联后的状态键变化如下：
用户输入 ──▶ CodeWriterAgent(gemini-2.5-flash) │ state["generated_code"] = 初版代码 ▼ CodeReviewerAgent(gemini-2.5-flash) │ 读取 {generated_code} │ state["review_comments"] = 评审意见 ▼ CodeRefactorerAgent(gemini-2.5-pro) │ 读取 {generated_code} + {review_comments} └ state["refactored_code"] = 最终代码（用户可见输出）4. 源码印证：output_key 如何变成下游的输入
示例的"配置魔法"背后是两条清晰的源码链路：
（1）output_key 写入会话状态。在 LlmAgent 实现 中，当 Agent 配置了output_key时，模型最终响应文本会被写入event.actions.state_delta[self.output_key]（第 1104 行），流式场景下还有专门的累加逻辑（约第 1109-1145 行）确保完整拼接后再落盘。这些state_delta最终合入会话状态，成为后续 Agent 可读取的session.state。
（2）指令占位符从会话状态填充。框架在每次调用模型前会对 instruction 模板做状态注入，相关工具见 instructions_utils.py 中的inject_session_state（模块 docstring 明确其职责是"Populates values in the instruction template, e.g. state, artifact, etc."）。这就是{generated_code}、{review_comments}能被解析为真实代码与评审文本的机制。
output_key在回调中的可见性也有专门测试覆盖，见 test_output_key_visibility.py（其中第 137 行附近还包含SequentialAgent场景的用例），可用来验证你的自定义流水线里output_key写入时机是否符合预期。
5. SequentialAgent 执行机制与版本注意事项
SequentialAgent的完整实现位于 sequential_agent.py，几个关键行为值得了解：
顺序执行与事件透传。核心循环在_run_async_impl（L110-L147）：按sub_agents列表顺序逐个run_async执行，透传每个子 Agent 产生的所有Event；若某子 Agent 触发了暂停（如人工确认/请求输入），则跳过后续子 Agent 直接返回，等待恢复。
可恢复执行（resume）。通过实验性的SequentialAgentState（L81-L86）把"当前执行到哪个子 Agent"持久化在 agent state 中，配合_get_start_index（L149-L172）在恢复时从断点继续，而不是从头重跑整条流水线。若发现状态中记录的子 Agent 已被从配置中删除，会记 warning 并从头开始。
Live 模式的完成信号。在音视频流式（live）场景下，框架无法从流本身判断子 Agent 何时"完成"，因此_run_live_impl（L174 起）会给每个LlmAgent子 Agent 动态注入一个task_completed工具并追加指令，由模型调用该工具来声明任务结束，流水线随即移交下一个 Agent。
弃用提示（重要）。从源码结构看，SequentialAgent类本身带有@deprecated标记（L89-L100）："SequentialAgent is deprecated in favor of Workflow and will be removed in a future version. Workflow cannot yet be used as an LlmAgent sub-agent."；对应的 SequentialAgentConfig 同样标注弃用。也就是说：该示例当前可正常加载运行，但顺序编排的长期演进方向是 Workflow 模块（见 docs/guides/workflow），在新项目选型时应留意这一前提。
6. 如何加载与运行这个示例
用 adk CLI 运行。该示例目录位于 samples 下，adk run以示例的父目录作为 Agent 根目录加载：在 contributing/samples/multi_agent 下执行
adk run multi_agent_seq_config随后在交互提示中输入Write a quicksort method in python即可看到三步流水线依次执行：writer 输出初稿 → reviewer 输出意见列表 → refactorer 输出最终代码块。运行时需具备 Gemini 模型访问凭证（模型名gemini-2.5-flash/gemini-2.5-pro需在你的凭据下可用）。
加载链路。从测试代码看，示例的加载方式与 CLI 一致：test_samples.py 中的_load_root_agent使用AgentLoader的loader.load_agent(sample_dir.name)完成"目录名 → Agent 实例"的解析，且测试会对 samples 下的所有示例目录做参数化加载校验（test_sample_loads），保证本示例的 YAML 始终能被当前版本正确加载——如果你改动配置后想快速验证，可以参照这一测试路径。
7. 设计要点总结
回到这个示例本身，可以提炼出配置型顺序流水线的四个可复用经验：
- 引用式子 Agent 声明：
root_agent.yaml只维护config_path列表，子 Agent 配置独立成文件，结构清晰、便于增删节点； output_key+ 指令占位符的零代码数据流：上游产物自动进入会话状态，下游在instruction中用{key}取用，无需编写任何传递逻辑；- 按价值分层选模型：flash 档做初稿与评审、pro 档做最终修订，在不牺牲最终质量的前提下压低整体成本；
- 收敛性兜底：末步指令显式处理"No major issues found"分支，使流水线在无需修改时稳定收敛。
局限与适用前提同样要记牢：依赖SequentialAgent（已进入弃用流程，未来将移除）；指令模板中的花括号占位符依赖会话状态注入，键名拼错时占位符不会报错而可能导致提示词失真；示例模型固定为 Gemini 系列，换用其他模型需同步调整model字段与相关能力假设。
【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
