《实用笔记》：循环工程与图工程：架构转变
《实用笔记》操作指南：循环工程与图工程：架构转变——适用于采用该模式的团队的契约、检查机制及可直接插入的代码模块。
本指南将逐步构建从原始材料到可运行系统的完整流程，主题为“循环工程与图引擎：正在悄然重塑AI智能体的架构变革”。重点在于可操作的步骤、明确的检查点，以及可直接放入代码库的代码，无需猜测其用途。 在概览阶段，应在修改代码之前明确输入参数、各步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行相应步骤，而无需推测隐藏状态。 配置信息应与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中管理，以便操作人员无需查看整个架构即可进行审计。
目录
在处理目录设计阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的组成部分，而非后续需要补充的功能。 在成本较高的步骤之后设置检查点。当操作员重新尝试某个节点时，恢复流程不应再次调用相同的大型语言模型。
1. 我们构建人工智能智能体的方式存在的问题
在处理“1. 问题所在”这一阶段时，首先需列出相关约定：所需的输入参数、成功标志，以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 建议采用小型、可测试的单元，而非冗长的脚本。当某个步骤失败时，故障应指向单一责任模块，而非复杂的流程链。 在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。
2. 首先，一个简单的类比
在处理“2 First a simple”这一简单阶段时，首先需明确合同条款：所需的输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持透明。 将这一阶段视为输入与验证后输出之间的契约。为相关成果命名，定义成功判定标准，并杜绝无声的半完成状态。 在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的LLM接口。 在处理“2 First a simple”这一简单阶段时，首先需明确合同条款：所需的输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持透明。 将配置信息置于应用程序代码之外。环境文件、密钥存储和功能标志应集中存放于一个位置，以便操作员无需查看整个流程即可进行审计。
3. 什么是循环工程？
“3个What循环阶段”若被视为可度量的结构，则效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。同时将正常流程与恢复流程都记录下来。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的内容。要保持图表状态简洁且具有类型定义，嵌套的数据块会掩盖哪个节点编写了哪个字段的信息，还会在中断后导致无法继续处理。
4. 循环工程架构
将4循环工程架构视为可度量的对象来处理时效果最佳。在扩大范围之前，先记录一份优秀的测试用例、一个故障案例以及回滚说明。 优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤出现故障时，故障应指向单一责任模块，而非复杂的流程链。 保持图结构的状态简洁且具有类型定义。嵌套的数据块会掩盖哪个节点修改了哪个字段的信息，还会在中断后导致无法继续执行。
def run_agent(task: str, tools: list, max_iterations: int = 10) -> str:
context = [{"role": "user", "content": task}]
for step in range(max_iterations):
response = llm.generate(context, tools=tools)
if response.is_final_answer:
return response.content
tool_result = execute_tool(response.tool_call)
context.append({"role": "assistant", "content": response.content})
context.append({"role": "tool", "content": tool_result})
return "Stopped: max iterations reached"
5. 什么是图工程？
将“5个什么是图”阶段视为可度量的结构来处理效果最佳。在扩大范围之前，先记录一份完美的操作日志、一个故障案例以及回滚说明。 把这个阶段视为输入与已验证输出之间的契约。为相关工件命名，明确成功标准，绝不允许出现无声的半完成状态。 保持图的状态简洁且具有类型约束。嵌套的数据块会掩盖哪个节点修改了哪个字段的信息，还会在中断后导致无法继续处理。 将“5个什么是图”阶段视为可度量的结构来处理效果最佳。在扩大范围之前，先记录一份完美的操作日志、一个故障案例以及回滚说明。 将配置信息置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放于一个位置，这样操作人员无需查看整个图结构即可进行审计。
为何这种方法如此有效
在“为何此方法高效”这一阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误处理都是产品不可或缺的部分，而非后续需要补充的功能。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。仅靠编译时的配置并不能保证业务的完整性。
6. 图结构工程架构
在6个图形工程架构阶段中，应在修改代码之前明确输入内容、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比庞大的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能指向单一责任主体，而非复杂的流程链。对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不等同于业务功能的完整性。
from graph_engine import StateGraph, START, END
def router(state: dict) -> str:
return state["task_type"] # "research" | "code" | "review"
def research_agent(state: dict) -> dict:
state["results"]["research"] = do_research(state["query"])
return state
def code_agent(state: dict) -> dict:
state["results"]["code"] = write_code(state["query"])
return state
def review_agent(state: dict) -> dict:
state["valid"] = validate(state["results"])
return state
def aggregator(state: dict) -> dict:
state["final_output"] = merge(state["results"])
return state
graph = StateGraph(schema=AgentState)
graph.add_node("router", router)
graph.add_node("research_agent", research_agent)
graph.add_node("code_agent", code_agent)
graph.add_node("review_agent", review_agent)
graph.add_node("aggregator", aggregator)
graph.add_conditional_edges("router", {
"research": "research_agent",
"code": "code_agent",
"review": "review_agent",
})
graph.add_edge(["research_agent", "code_agent", "review_agent"], "aggregator")
graph.add_conditional_edges("aggregator", {
"valid": END,
"invalid": "router", # explicit retry edge
})
app = graph.compile()
app.invoke({"query": "...", "results": {}, "task_type": "code"})
循环与图形：对比分析
在“循环结构与图结构并行处理”阶段，应在修改代码之前明确输入参数、各步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 应将此阶段视为输入与验证后输出之间的契约。为相关成果命名，定义成功标准，杜绝默许的半完成状态。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不等同于业务上的完整性。
7. 视角转变：为何行业正从循环结构转向图结构
在“视角转换”阶段的第7步中，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。对于会耗费资金或修改生产数据的操作，必须经过人工审批。编译时的配置并不等同于业务功能的完整性。
1. 现实世界中的任务并非直线推进
对于现实世界任务阶段，应在修改代码之前明确输入内容、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不等同于业务功能的完整性。
2. 多智能体系统需要更完善的架构
对于需要两个多智能体系统的阶段，在修改代码之前应明确输入参数、该步骤的负责人以及终止条件。操作人员应当能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的内容。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不能等同于业务功能的完整性。
3. 随着人工智能作用的增强，透明度与信任度愈发重要
在“可见性与信任”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比冗长的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能指向单一责任主体，而非复杂的流程链。对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的逻辑连接并不等同于业务功能的完整性。
4. 成本与速度
在成本与速度优化阶段，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将此阶段视为输入与验证后输出之间的契约。为相关成果命名，定义成功判定标准，杜绝默许的半完成状态。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的逻辑连接并不等同于业务上的完整性。 在成本与速度优化阶段，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。
5. 更易于测试和维护
在进入“更易于测试”的五个阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改不会出错。 同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误消息处理都是产品本身的组成部分，而非后续需要补充的功能。 在成本较高的步骤之后设置检查点。当操作员重新尝试某个节点时，恢复流程不应再次调用相同的大型语言模型。
8. 何时使用循环结构与图结构
在处理“8个使用场景”阶段时，首先写下相关契约：所需的输入参数、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 优先选择小型、可测试的单元，而非冗长的脚本。当某个步骤失败时，故障应指向单一责任模块，而非复杂的流程链。 在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的LLM接口。
何时使用循环：
在处理“寻找循环”阶段时，首先需写下契约：所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持透明。 将此阶段视为输入与验证后输出之间的契约。为相关成果命名，定义成功检查标准，并杜绝无声的半完成状态。 在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。 在处理“寻找循环”阶段时，首先需写下契约：所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持透明。 将配置信息置于应用程序代码之外。环境文件、密钥存储和功能标志应集中存放于一个位置，以便操作员无需查看整个流程即可进行审计。
何时需要构建图结构：
将“图阶段实现”视为可度量的结构来处理时，其效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。 同时记录正常流程和恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的内容。 保持图的状态简洁且具有明确类型。嵌套的数据块会掩盖哪个节点修改了哪个字段的信息，还会在中断后导致流程无法继续。
那么，应该选择哪种方式呢？
“So Which One Should”这一方法在被视为可度量的界面时效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。 优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应能指向单一的责任主体，而非复杂的流程链。 保持图表状态简洁且具有类型定义。嵌套的数据块会掩盖哪个节点修改了哪个字段的信息，还会在中断后导致无法继续处理。
9. 生产环境检查清单
将“9项生产环境检查清单”阶段视为可度量的工作面最为有效。在扩大范围之前，需记录一份标准范本、一个故障案例以及回滚说明。 应将此阶段视为输入与已验证输出之间的契约。为相关成果命名，明确成功标准，杜绝默许的半完成状态。 保持图结构扁平且类型化。嵌套的数据块会掩盖哪个节点修改了哪个字段，还会在中断后导致无法继续处理。 将“9项生产环境检查清单”阶段视为可度量的工作面最为有效。在扩大范围之前，需记录一份标准范本、一个故障案例以及回滚说明。 将配置信息置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放于一处，以便操作人员无需查看整个图结构即可进行审计。
10. 核心要点
在“10个关键要点”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的内容。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不等同于业务功能的完整性。
11. 参考资料
在“11个参考阶段”中，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比冗长的脚本，更应采用小型、可测试的单元。当某个步骤失败时，故障原因应能指向单一责任点，而非复杂的流程链。对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不等同于业务功能的完整性。
点击获取更多内容
在“进一步跟进”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将此阶段视为输入与已验证输出之间的契约。为相关成果命名，定义成功检测标准，并拒绝默许的半完成状态。 对于涉及资金支出或更改生产数据的操作，必须经过人工审批。编译时的连接关系并不等同于业务上的完整性。 在“进一步跟进”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个操作人员可以审核的位置，无需阅读整个系统结构。
操作检查清单
将操作检查清单视为可度量的基准，效果最佳。在扩大范围之前，先记录一份最优示例、一个故障案例以及回滚说明。
在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外账单。
保持图表状态简洁且类型明确。嵌套的数据结构会掩盖哪个节点修改了哪个字段，还会在中断后导致无法继续处理。
只要预算允许，就在持续集成过程中使用测试用例而非真实的付费 API 来执行关键路径的烟雾测试。
将配置信息与应用程序代码分开。环境文件、密钥存储和功能开关应集中存放，以便操作人员无需查看整个图表即可进行审计。
保持图结构的状态简洁且类型明确。嵌套的数据块会掩盖是哪个节点修改了哪个字段，还会在中断后导致流程无法继续。
在提升栈结构之前，先冻结各版本，为关键路径记录完整的操作日志，并确认回滚步骤。共享环境需要设置速率限制、进行租户验证，同时明确密钥轮换的负责人。与其追求花哨的一次性演示，不如注重扎实的可靠性。
c83488435d23的批注：将提供者密钥移出代码仓库，为每个会话设置令牌使用上限，并将操作日志存储在评估用示例文件旁边，以便后续模型更换时仍能保持数据可比性。