adk-python 实践指南：用 YAML 配置搭建“编写-评审-重构“顺序执行的多 Agent 流水线

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 # 根 AgentSequentialAgent声明三个子 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: $schemahttps://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_classSequentialAgent声明 Agent 类型配置加载器据此实例化顺序执行的 shell AgentnameCodePipelineAgent流水线名称也用作 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.yamlagent_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 users 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.yamlagent_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 如何变成下游的输入示例的配置魔法背后是两条清晰的源码链路1output_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_implL110-L147按sub_agents列表顺序逐个run_async执行透传每个子 Agent 产生的所有Event若某子 Agent 触发了暂停如人工确认/请求输入则跳过后续子 Agent 直接返回等待恢复。可恢复执行resume。通过实验性的SequentialAgentStateL81-L86把当前执行到哪个子 Agent持久化在 agent state 中配合_get_start_indexL149-L172在恢复时从断点继续而不是从头重跑整条流水线。若发现状态中记录的子 Agent 已被从配置中删除会记 warning 并从头开始。Live 模式的完成信号。在音视频流式live场景下框架无法从流本身判断子 Agent 何时完成因此_run_live_implL174 起会给每个LlmAgent子 Agent 动态注入一个task_completed工具并追加指令由模型调用该工具来声明任务结束流水线随即移交下一个 Agent。弃用提示重要。从源码结构看SequentialAgent类本身带有deprecated标记L89-L100SequentialAgent 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），仅供参考