ADK Python 实战用 YAML 配置构建带反馈回路的 Workflowloop_config 样本详解【免费下载链接】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本文围绕 ADKAgent Development KitPython 版中的loop_config官方样本完整讲解如何用 YAML 配置文件定义一个“生成—评估—反馈—重试”的反馈回路工作流包括root_agent.yaml中 edges 的完整写法、代码引用Code References、边内函数引用Function References in Edges与外部 Agent 文件External Agent Files三处特殊语法的语义和解析原理以及通过黄金测试事件序列验证回路实际运行的方法。读完后你将能够直接用配置代替 Python 代码来搭建带循环路由的 ADK Workflow。一、样本解决什么问题loop_config是 contributing/samples/workflows/loop_config/README.md 所描述的官方样本它演示如何用 YAML 定义一个带反馈回路feedback loop的 Workflowprocess_input把用户输入主题写入会话状态generate_headlineLLM Agent 根据主题生成标题并参考上一轮反馈evaluate_headlineLLM Agent 对标题打分tech-related或unrelated并给出改进建议route_headline按打分结果路由——若为unrelated携带反馈回到generate_headline重新生成形成回路若为tech-related流程结束。该样本与 Python 版本的 contributing/samples/workflows/loop/agent.py 行为完全对应README 称其 mirrors 该样本区别仅在于图结构用 YAML 而非 Python 字面量表达。README 明确指出加载root_agent.yaml后agent_class: Workflow会被解析为Workflow类edges会映射到Workflow同名字段最终得到五条边、最后一条为unrelated回到generate_headline的Workflow实例。二、样本文件结构与职责contributing/samples/workflows/loop_config/ ├── README.md # 样本说明本文主体来源 ├── root_agent.yaml # 工作流图定义agent_class edges ├── agent.py # Feedback 模型 process_input / route_headline 函数 ├── generate_headline.yaml # 生成标题的 LlmAgent 定义 ├── evaluate_headline.yaml # 评估标题的 LlmAgent 定义含 output_schema └── tests/ ├── flower.json # 黄金事件序列非科技主题触发回路 └── computer.json # 黄金事件序列各文件职责文件作用root_agent.yaml根工作流声明agent_class: Workflow用edges描述整张执行图含回路边agent.py存放 Pydantic 结构化输出模型Feedback以及两个普通 Python 函数process_input、route_headlinegenerate_headline.yaml/evaluate_headline.yaml独立 YAML 定义的LlmAgent被 root 边引用tests/*.json从目录结构看是录制的完整会话事件流事件列表 最终 state可用来逐步核对每个节点的输入输出三、完整配置文件逐文件解读3.1 根工作流root_agent.yamlcontributing/samples/workflows/loop_config/root_agent.yaml 全文去掉许可证头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两个要点第一条边是一个线性序列START → process_input → generate_headline → evaluate_headline → route_headline。列表中混用了三种节点表示法函数引用.agent.process_input、外部 Agent 文件generate_headline.yaml这正是下面第四节三种特殊语法的综合演示。第二条边是回路边.agent.route_headline之后的unrelated: generate_headline.yaml是一个路由字典——当route_headline产出的route值等于unrelated时流转到generate_headline.yaml节点其他路由值tech-related没有出边流程自然终止。3.2 生成节点generate_headline.yamlcontributing/samples/workflows/loop_config/generate_headline.yamlagent_class: LlmAgent name: generate_headline instruction: | Write a headline about the topic {topic}. If feedback is provided, take it into account. The feedback: {feedback?}agent_class: LlmAgent告诉 loader 该文件描述的是一个LlmAgent实例指令中的{topic}来自process_input写入状态的键{feedback?}中的?是可选插值语法首轮执行时 state 中还没有feedback键使用可选占位符可避免缺失报错第二轮起则自动带入evaluate_headline写入的反馈内容。3.3 评估节点evaluate_headline.yamlcontributing/samples/workflows/loop_config/evaluate_headline.yamlagent_class: LlmAgent name: evaluate_headline instruction: | Grade whether the headline is related to technology or software engineering. output_schema: name: loop_config.agent.Feedback output_key: feedbackoutput_schema采用name条目携带全限定类名loop_config.agent.Feedbackloader 会动态导入该对象——这是 README 所述 “Code References” 语法的实际用例output_key: feedback指定评估结果写入会话状态中的键名正是回路下一轮generate_headline指令里{feedback?}读取的键。3.4 Python 侧agent.pycontributing/samples/workflows/loop_config/agent.py 定义了图节点之外的全部 Python 代码class Feedback(BaseModel): grade: Literal[tech-related, unrelated] Field( description( Decide if the headline is related to technology or software engineering. ) ) feedback: str Field( description( If the headline is unrelated to technology, provide feedback on how to make it more tech-focused. ) ) def process_input(node_input: str): Puts user input in the state. return Event(state{topic: node_input}) def route_headline(node_input: Feedback): return Event(routenode_input.grade)Feedback结构化输出模型grade限定为两个取值正好对应路由字典的两个键之一process_input接收节点输入用户消息文本通过Event(state{...})把主题写入状态route_headline读取上一节点写入的feedback反序列化为Feedback通过Event(route...)声明路由值驱动Workflow按出边字典分发。与 Python 版样本对照contributing/samples/workflows/loop/agent.py 中同样的图是用Workflow(nameroot_agent, edges[(...), (route_headline, {unrelated: generate_headline})])字面量写出的两者的edges结构一一对应可交叉验证 YAML 语义。四、README 定义的三处特殊语法READMEcontributing/samples/workflows/loop_config/README.md明确归纳了本样本用到的三种动态解析语法4.1 代码引用Code References持有 Python 对象的字段如evaluate_headline.yaml中的output_schema可以写成带name条目的结构name是该对象的全限定名loader 负责导入解析基于sys.path其中包含 agent 目录所在目录示例name: loop_config.agent.Feedback解析为本目录下agent.py中的FeedbackPydantic 模型。4.2 边内函数引用Function References in Edges边列表中的字符串如果不以.yaml结尾、也不是START就会被当作函数引用处理以.开头时相对当前 agent 目录的 Python 包路径解析。示例.agent.process_input解析为agent.py中的process_input函数即先展开为loop_config.agent.process_input再导入loader 会自动用函数名作为节点名创建FunctionNode本例中节点名即process_input不带前导点的引用如.agent.route_headline展开后的包路径形式走同样的sys.path导入逻辑。4.3 外部 Agent 文件External Agent FilesAgent 可以定义在独立 YAML 文件中边列表中直接用文件名引用示例generate_headline.yaml即引用该文件定义的LlmAgent实例复用mapper 按字符串值缓存已解析节点因此在多条边中重复使用同一文件名回路场景必然如此generate_headline.yaml同时出现在首条边和unrelated出边中会命中同一个节点实例从而正确保持图结构——这是回路能够成立的关键机制。五、源码级原理loader 如何把字符串解析成节点上述三种语法的实现集中在 src/google/adk/agents/config_agent_utils.py 的_resolve_node_like方法约 L334–L394可以直接印证 README 的描述START哨兵字符串START直接映射为Workflow的START常量L340–L341缓存优先任何字符串/内联节点在解析前都会先查_resolved_nodes_cacheL349–L350命中即返回同一对象——这正是“同一文件名在多边中复用同一实例”的源码依据L355、L391–L393 写入缓存且同时以原始字符串和节点name两个键登记.yaml/.yml后缀构造AgentRefConfig(config_path...)并调用resolve_agent_reference加载外部 Agent 文件L352–L358裸单词的限制不含.的字符串被视为已存在的节点名若缓存里没有会抛出ValueError提示“节点必须由更早的边先定义”即不支持前向引用L360–L368。这意味着写 edges 时节点必须先定义后引用前导点相对路径以.开头的引用会取当前 agent 目录名拼成包路径L371–L374再经resolve_fully_qualified_name导入若结果是可调用对象非类则用最后一段作为节点名创建FunctionNodeL376–L379与 README “自动创建 FunctionNode” 的描述一致非法引用快速失败解析结果既非可调用也非节点时立即抛出带引用名的ValueErrorL386–L389避免问题延迟到图校验阶段才暴露。由此也能解释 README 的运行前提因为代码引用是对sys.path解析的必须从 agent 文件夹所在目录即contributing/samples/workflows/作为工作目录运行与 ADK CLI 加载 agent 的约定一致。对应的图运行时实现位于 src/google/adk/workflow/_workflow.pyWorkflow类与edges字段及 src/google/adk/workflow/_function_node.pyFunctionNodeedges 列表中的元组/字典形式与 YAML 中- - START / .agent.process_input / ...的结构完全同构。六、用黄金事件序列验证回路真的发生了tests/目录下的 contributing/samples/workflows/loop_config/tests/flower.json 录入了主题flower非科技主题注定触发回路的完整事件流可逐步对照验证e-2process_input1stateDelta.topic flower——主题写入状态e-3generate_headline1首轮产出Petal Power: The Timeless Allure of Flowerse-4evaluate_headline1模型输出 JSON{grade: unrelated, feedback: ...}并写入stateDelta.feedback——注意state中的feedback值正是下一轮生成的输入e-5route_headline1actions.route unrelated——命中unrelated: generate_headline.yaml出边回到生成节点e-6generate_headline2节点名后缀2表明同一节点第二次执行新标题AI-Powered Petals: ...明显吸收了反馈e-7evaluate_headline2grade tech-relatede-8route_headline2route tech-related无对应出边调用结束。最终state同时包含topic: flower与feedback.grade: tech-related完整还原了“生成 → 评估 → 反馈 → 再生成 → 通过”的回路闭环。tests/computer.json提供了另一组主题的事件记录可作对照。七、执行方式与运行前提运行目录从contributing/samples/workflows/目录执行 ADK 命令README 原话代码引用相对sys.path解析须“从持有 agent 文件夹的目录运行与 CLI 的约定一致”。由于root_agent.yaml声明name: root_agent且文件位于loop_config/目录按 ADK CLI 的 agent 目录约定该目录即一个可加载的 agent 项目输入示例README 给出的两个测试输入为Python programming科技主题预期一轮通过与Baking cookies非科技主题预期触发unrelated回路前提与限制模型访问由LlmAgent默认配置决定本样本自身未固定模型与 API 配置回路边只声明了unrelated路由tech-related无出边即终止因此不会出现死循环若自行扩展路由字典需自行保证终止性节点必须先定义后引用前向引用会直接报错新增节点时应保持“定义在前的边”出现在引用它的边之前。八、小结配置式 Workflow 回路的三个可复用模式对照 contributing/samples/workflows/loop_config/ 全套文件可以把该样本抽象为三个可直接复用的模式图结构完全 YAML 化agent_class: Workflowedges即可表达含循环的执行图LLM 节点拆成独立.yaml文件按文件名引用Python 侧只保留路由函数与结构化模型动态解析三语法name全限定名任意 Python 对象如output_schema、前导点函数引用自动转FunctionNode、外部 Agent 文件名带实例级缓存保证图结构正确用状态键串联回路数据output_keyfeedback写入状态下一轮指令中的{feedback?}可选插值读出配合路由函数读取output_key的值决定走向——“状态即回路记忆”无需任何额外会话管理代码。这一套语法与 Python 字面量写法contributing/samples/workflows/loop/agent.py行为等价适合在需要把 Agent 拓扑交给非 Python 流程管理配置即代码、易于审查与批量生成的场景中直接套用。【免费下载链接】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），仅供参考 ADK Python 实战：用 YAML 配置构建带反馈回路的 Workflow（loop_config 样本详解）
ADK Python 实战用 YAML 配置构建带反馈回路的 Workflowloop_config 样本详解【免费下载链接】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本文围绕 ADKAgent Development KitPython 版中的loop_config官方样本完整讲解如何用 YAML 配置文件定义一个“生成—评估—反馈—重试”的反馈回路工作流包括root_agent.yaml中 edges 的完整写法、代码引用Code References、边内函数引用Function References in Edges与外部 Agent 文件External Agent Files三处特殊语法的语义和解析原理以及通过黄金测试事件序列验证回路实际运行的方法。读完后你将能够直接用配置代替 Python 代码来搭建带循环路由的 ADK Workflow。一、样本解决什么问题loop_config是 contributing/samples/workflows/loop_config/README.md 所描述的官方样本它演示如何用 YAML 定义一个带反馈回路feedback loop的 Workflowprocess_input把用户输入主题写入会话状态generate_headlineLLM Agent 根据主题生成标题并参考上一轮反馈evaluate_headlineLLM Agent 对标题打分tech-related或unrelated并给出改进建议route_headline按打分结果路由——若为unrelated携带反馈回到generate_headline重新生成形成回路若为tech-related流程结束。该样本与 Python 版本的 contributing/samples/workflows/loop/agent.py 行为完全对应README 称其 mirrors 该样本区别仅在于图结构用 YAML 而非 Python 字面量表达。README 明确指出加载root_agent.yaml后agent_class: Workflow会被解析为Workflow类edges会映射到Workflow同名字段最终得到五条边、最后一条为unrelated回到generate_headline的Workflow实例。二、样本文件结构与职责contributing/samples/workflows/loop_config/ ├── README.md # 样本说明本文主体来源 ├── root_agent.yaml # 工作流图定义agent_class edges ├── agent.py # Feedback 模型 process_input / route_headline 函数 ├── generate_headline.yaml # 生成标题的 LlmAgent 定义 ├── evaluate_headline.yaml # 评估标题的 LlmAgent 定义含 output_schema └── tests/ ├── flower.json # 黄金事件序列非科技主题触发回路 └── computer.json # 黄金事件序列各文件职责文件作用root_agent.yaml根工作流声明agent_class: Workflow用edges描述整张执行图含回路边agent.py存放 Pydantic 结构化输出模型Feedback以及两个普通 Python 函数process_input、route_headlinegenerate_headline.yaml/evaluate_headline.yaml独立 YAML 定义的LlmAgent被 root 边引用tests/*.json从目录结构看是录制的完整会话事件流事件列表 最终 state可用来逐步核对每个节点的输入输出三、完整配置文件逐文件解读3.1 根工作流root_agent.yamlcontributing/samples/workflows/loop_config/root_agent.yaml 全文去掉许可证头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两个要点第一条边是一个线性序列START → process_input → generate_headline → evaluate_headline → route_headline。列表中混用了三种节点表示法函数引用.agent.process_input、外部 Agent 文件generate_headline.yaml这正是下面第四节三种特殊语法的综合演示。第二条边是回路边.agent.route_headline之后的unrelated: generate_headline.yaml是一个路由字典——当route_headline产出的route值等于unrelated时流转到generate_headline.yaml节点其他路由值tech-related没有出边流程自然终止。3.2 生成节点generate_headline.yamlcontributing/samples/workflows/loop_config/generate_headline.yamlagent_class: LlmAgent name: generate_headline instruction: | Write a headline about the topic {topic}. If feedback is provided, take it into account. The feedback: {feedback?}agent_class: LlmAgent告诉 loader 该文件描述的是一个LlmAgent实例指令中的{topic}来自process_input写入状态的键{feedback?}中的?是可选插值语法首轮执行时 state 中还没有feedback键使用可选占位符可避免缺失报错第二轮起则自动带入evaluate_headline写入的反馈内容。3.3 评估节点evaluate_headline.yamlcontributing/samples/workflows/loop_config/evaluate_headline.yamlagent_class: LlmAgent name: evaluate_headline instruction: | Grade whether the headline is related to technology or software engineering. output_schema: name: loop_config.agent.Feedback output_key: feedbackoutput_schema采用name条目携带全限定类名loop_config.agent.Feedbackloader 会动态导入该对象——这是 README 所述 “Code References” 语法的实际用例output_key: feedback指定评估结果写入会话状态中的键名正是回路下一轮generate_headline指令里{feedback?}读取的键。3.4 Python 侧agent.pycontributing/samples/workflows/loop_config/agent.py 定义了图节点之外的全部 Python 代码class Feedback(BaseModel): grade: Literal[tech-related, unrelated] Field( description( Decide if the headline is related to technology or software engineering. ) ) feedback: str Field( description( If the headline is unrelated to technology, provide feedback on how to make it more tech-focused. ) ) def process_input(node_input: str): Puts user input in the state. return Event(state{topic: node_input}) def route_headline(node_input: Feedback): return Event(routenode_input.grade)Feedback结构化输出模型grade限定为两个取值正好对应路由字典的两个键之一process_input接收节点输入用户消息文本通过Event(state{...})把主题写入状态route_headline读取上一节点写入的feedback反序列化为Feedback通过Event(route...)声明路由值驱动Workflow按出边字典分发。与 Python 版样本对照contributing/samples/workflows/loop/agent.py 中同样的图是用Workflow(nameroot_agent, edges[(...), (route_headline, {unrelated: generate_headline})])字面量写出的两者的edges结构一一对应可交叉验证 YAML 语义。四、README 定义的三处特殊语法READMEcontributing/samples/workflows/loop_config/README.md明确归纳了本样本用到的三种动态解析语法4.1 代码引用Code References持有 Python 对象的字段如evaluate_headline.yaml中的output_schema可以写成带name条目的结构name是该对象的全限定名loader 负责导入解析基于sys.path其中包含 agent 目录所在目录示例name: loop_config.agent.Feedback解析为本目录下agent.py中的FeedbackPydantic 模型。4.2 边内函数引用Function References in Edges边列表中的字符串如果不以.yaml结尾、也不是START就会被当作函数引用处理以.开头时相对当前 agent 目录的 Python 包路径解析。示例.agent.process_input解析为agent.py中的process_input函数即先展开为loop_config.agent.process_input再导入loader 会自动用函数名作为节点名创建FunctionNode本例中节点名即process_input不带前导点的引用如.agent.route_headline展开后的包路径形式走同样的sys.path导入逻辑。4.3 外部 Agent 文件External Agent FilesAgent 可以定义在独立 YAML 文件中边列表中直接用文件名引用示例generate_headline.yaml即引用该文件定义的LlmAgent实例复用mapper 按字符串值缓存已解析节点因此在多条边中重复使用同一文件名回路场景必然如此generate_headline.yaml同时出现在首条边和unrelated出边中会命中同一个节点实例从而正确保持图结构——这是回路能够成立的关键机制。五、源码级原理loader 如何把字符串解析成节点上述三种语法的实现集中在 src/google/adk/agents/config_agent_utils.py 的_resolve_node_like方法约 L334–L394可以直接印证 README 的描述START哨兵字符串START直接映射为Workflow的START常量L340–L341缓存优先任何字符串/内联节点在解析前都会先查_resolved_nodes_cacheL349–L350命中即返回同一对象——这正是“同一文件名在多边中复用同一实例”的源码依据L355、L391–L393 写入缓存且同时以原始字符串和节点name两个键登记.yaml/.yml后缀构造AgentRefConfig(config_path...)并调用resolve_agent_reference加载外部 Agent 文件L352–L358裸单词的限制不含.的字符串被视为已存在的节点名若缓存里没有会抛出ValueError提示“节点必须由更早的边先定义”即不支持前向引用L360–L368。这意味着写 edges 时节点必须先定义后引用前导点相对路径以.开头的引用会取当前 agent 目录名拼成包路径L371–L374再经resolve_fully_qualified_name导入若结果是可调用对象非类则用最后一段作为节点名创建FunctionNodeL376–L379与 README “自动创建 FunctionNode” 的描述一致非法引用快速失败解析结果既非可调用也非节点时立即抛出带引用名的ValueErrorL386–L389避免问题延迟到图校验阶段才暴露。由此也能解释 README 的运行前提因为代码引用是对sys.path解析的必须从 agent 文件夹所在目录即contributing/samples/workflows/作为工作目录运行与 ADK CLI 加载 agent 的约定一致。对应的图运行时实现位于 src/google/adk/workflow/_workflow.pyWorkflow类与edges字段及 src/google/adk/workflow/_function_node.pyFunctionNodeedges 列表中的元组/字典形式与 YAML 中- - START / .agent.process_input / ...的结构完全同构。六、用黄金事件序列验证回路真的发生了tests/目录下的 contributing/samples/workflows/loop_config/tests/flower.json 录入了主题flower非科技主题注定触发回路的完整事件流可逐步对照验证e-2process_input1stateDelta.topic flower——主题写入状态e-3generate_headline1首轮产出Petal Power: The Timeless Allure of Flowerse-4evaluate_headline1模型输出 JSON{grade: unrelated, feedback: ...}并写入stateDelta.feedback——注意state中的feedback值正是下一轮生成的输入e-5route_headline1actions.route unrelated——命中unrelated: generate_headline.yaml出边回到生成节点e-6generate_headline2节点名后缀2表明同一节点第二次执行新标题AI-Powered Petals: ...明显吸收了反馈e-7evaluate_headline2grade tech-relatede-8route_headline2route tech-related无对应出边调用结束。最终state同时包含topic: flower与feedback.grade: tech-related完整还原了“生成 → 评估 → 反馈 → 再生成 → 通过”的回路闭环。tests/computer.json提供了另一组主题的事件记录可作对照。七、执行方式与运行前提运行目录从contributing/samples/workflows/目录执行 ADK 命令README 原话代码引用相对sys.path解析须“从持有 agent 文件夹的目录运行与 CLI 的约定一致”。由于root_agent.yaml声明name: root_agent且文件位于loop_config/目录按 ADK CLI 的 agent 目录约定该目录即一个可加载的 agent 项目输入示例README 给出的两个测试输入为Python programming科技主题预期一轮通过与Baking cookies非科技主题预期触发unrelated回路前提与限制模型访问由LlmAgent默认配置决定本样本自身未固定模型与 API 配置回路边只声明了unrelated路由tech-related无出边即终止因此不会出现死循环若自行扩展路由字典需自行保证终止性节点必须先定义后引用前向引用会直接报错新增节点时应保持“定义在前的边”出现在引用它的边之前。八、小结配置式 Workflow 回路的三个可复用模式对照 contributing/samples/workflows/loop_config/ 全套文件可以把该样本抽象为三个可直接复用的模式图结构完全 YAML 化agent_class: Workflowedges即可表达含循环的执行图LLM 节点拆成独立.yaml文件按文件名引用Python 侧只保留路由函数与结构化模型动态解析三语法name全限定名任意 Python 对象如output_schema、前导点函数引用自动转FunctionNode、外部 Agent 文件名带实例级缓存保证图结构正确用状态键串联回路数据output_keyfeedback写入状态下一轮指令中的{feedback?}可选插值读出配合路由函数读取output_key的值决定走向——“状态即回路记忆”无需任何额外会话管理代码。这一套语法与 Python 字面量写法contributing/samples/workflows/loop/agent.py行为等价适合在需要把 Agent 拓扑交给非 Python 流程管理配置即代码、易于审查与批量生成的场景中直接套用。【免费下载链接】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），仅供参考