# AgentFlow Runtime：结构化多智能体工作流运行时，让编码智能体协作可预测、可追踪 > 基于TypeScript/Node.js的多智能体工作流运行时，通过JSON模板配置结构化角色（Researcher、Planner、Executor等），实现确定性执行、输出验证和完整追踪，默认支持Mock模式无需API密钥。 - 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm) - 发布时间: 2026-05-24T07:15:23.000Z - 最近活动: 2026-05-24T07:24:37.228Z - 热度: 148.8 - 关键词: AgentFlow, 多智能体, 工作流运行时, TypeScript, 结构化角色, 确定性执行, 编码智能体 - 页面链接: https://www.zingnex.cn/forum/thread/agentflow-runtime - Canonical: https://www.zingnex.cn/forum/thread/agentflow-runtime - Markdown 来源: ingested_event --- ## 原作者与来源 - **原作者/维护者**: senlinal - **来源平台**: GitHub - **原项目名**: agentflow-runtime - **原始链接**: https://github.com/senlinal/agentflow-runtime - **发布时间**: 2026年5月24日 --- ## 项目概述：多智能体协作的工程化框架 在LLM智能体应用开发中，一个核心挑战是：**如何让多个智能体协同工作，同时保持行为的可预测性和可追溯性？** AgentFlow Runtime提供了一个基于TypeScript/Node.js的解决方案。它不是又一个聊天式的智能体框架，而是一个**确定性工作流运行时**——通过JSON模板配置结构化角色，实现精确控制的执行流程。 ### 核心设计理念 - **确定性执行**：运行时只负责加载配置、调用执行器、验证输出，不决定角色行为 - **结构化上下文**：角色间交换结构化数据而非自由文本聊天 - **完整追踪**：每个工作流执行都被持久化到`.workflow-runs/` - **默认Mock**：开箱即用，无需API密钥即可演示和测试 --- ## 核心概念与架构 ### 系统架构 ``` TaskBrief输入 → WorkflowRunner/WorkflowRuntime → 工作流模板JSON ↓ AgentNode角色节点 → 结构化WorkflowContext ↓ TraceStore（摘要/追踪/上下文） ``` ### 运行时职责边界 `WorkflowRuntime`是确定性的，它**不**决定角色行为，也**不**硬编码工作流顺序。它只负责： 1. 加载配置的节点和边 2. 调用每个节点的注册执行器 3. 验证输出模式 4. 将结构化输出写入上下文 5. 解析下一条边的条件 6. 在`end`或`maxIterations`时停止 7. 记录追踪条目 这种设计确保了运行时的**纯粹性**——它是执行引擎，不是决策引擎。 --- ## 预置角色与工作流模板 ### 结构化角色预设 项目提供可复用的角色预设，位于`roles/*.json`： | 角色 | 职责 | |------|------| | **Researcher** | 研究分析，生成研究报告 | | **FeasibilityEvaluator** | 可行性评估，输出可行性报告 | | **Planner** | 制定执行计划 | | **Debater** | 审查和质疑计划 | | **PlannerRevision** | 根据反馈修订计划 | | **Executor** | 执行计划 | | **Verifier** | 验证执行结果 | | **GoalKeeper** | 最终目标检查 | | **TaskNegotiator** | 任务协商，澄清目标 | ### 工作流模板示例 | 模板 | 流程 | 用途 | |------|------|------| | **research-feasibility-execute-verify** | Researcher → FeasibilityEvaluator → 条件执行 | 可行性门控执行 | | **task-negotiation** | TaskNegotiator → end | 任务澄清和确认 | | **abcde-basic** | Planner → Debater → PlannerRevision → Executor → Verifier → GoalKeeper | 完整ABCDE循环 | | **code-test-verify** | CodeExecutor → TestRunner → Verifier | 受控代码执行验证 | --- ## 工作流配置文件系统 ### 配置文件分层 项目采用分层配置策略，支持多种工作模式： ``` profiles/ ├── current.json # 当前激活的配置 ├── rag-optimization.json # RAG优化模式 ├── coding-safe-fix.json # 安全代码修复模式 ├── external-project-fix.json # 外部项目修复模式 ├── frontend-site-build.json # 前端站点构建模式 └── agent-workforce-basic.json # 基础多智能体工作力模式 ``` ### 内置配置详解 **rag-optimization配置** - 从`task-negotiation`开始 - 使用`confirmed-scope-gate` - 阻止生产索引变更、部署、删除和未确认的指标变更 **coding-safe-fix配置** - 默认使用受控的code/test/verify链 - 包含审批流程 - 适用于小规模范围修复 **frontend-site-build配置** - 处理单页网站、落地页、个人站点 - 支持HTML/CSS/JS和轻量级React/Next.js - 默认不部署、不删除文件、不调用真实LLM、不执行代码变更 **agent-workforce-basic配置** - 运行`abcde-basic`模板 - 演示Planner、Debater、PlannerRevision、Executor、Verifier、GoalKeeper协作 - 运行时追踪验证 --- ## 使用方式 ### 快速开始 ```bash git clone cd agentflow-runtime # 运行演示（Mock模式） npm run demo # 列出可用模板 npm run workflow:list # 运行特定模板 npm run workflow -- --template research-feasibility-execute-verify --input inputs/feasible-task.json # 运行代码测试验证链 npm run workflow -- --template code-test-verify --input inputs/feasible-task.json # 运行测试 npm run test npm run typecheck ``` ### 配置管理 ```bash # 列出配置 npm run workflow:profiles # 查看当前配置 npm run workflow:profile # 切换配置 npm run workflow:profile:use -- --profile rag-optimization # 检查配置详情 npm run workflow:profile:inspect -- --profile rag-optimization ``` ### 智能路由执行 ```bash # 自动路由到合适配置 npm run workflow:route-profile -- --task "做一个仿 Claude.ai 风格的个人网站" # 使用特定配置运行任务 npm run workflow:run-profile -- --profile rag-optimization --task "继续 RAG 召回优化" # 演示完整多智能体协作 npm run workflow:run-profile -- --profile agent-workforce-basic --task "演示多角色协作" ``` ### 可恢复会话 当需要范围确认时，配置运行会创建可恢复会话： ```bash # 列出会话 npm run workflow:profile:sessions # 查看特定会话 npm run workflow:profile:session -- --id # 恢复会话 npm run workflow:run-profile -- --sessionId --answer "确认继续" ``` --- ## 关键特性详解 ### 验证与门控 **code-test-verify模板**使用`type: "verify"`节点，其确定性验证器检查： - 代码执行状态 - 配置的测试结果 - 被阻止的操作 - 变更/删除的文件 - 差异限制 - 不安全路径 - 检查点证据 验证失败时，模板路由到`repairPlanBuilder → humanApprovalGate → end`，创建范围修复计划和待人工审批请求，**不自动重新运行CodeExecutor**。 ### 运行时验证的代理 角色时间线是运行时验证的：**无追踪，无代理**。角色仅在`trace.json`中存在`source=runtime_trace`记录时才会显示。 这种设计确保了代理存在的**可验证性**——每个声称参与工作的代理都必须有运行时追踪证据。 ### LLM集成 默认使用Mock执行，无需API密钥。支持可选的OpenAI兼容和DeepSeek提供商用于`type: "llm"`节点： - 默认：Mock行为 - 可选：真实LLM调用（需显式配置） --- ## 技术实现细节 ### 运行时要求 - Node.js（支持`--experimental-strip-types`） - npm - 无需安装步骤（仅使用Node内置模块） ### 项目结构 ``` ├── workflows/ # 工作流模板JSON ├── roles/ # 角色预设JSON ├── profiles/ # 配置文件 ├── inputs/ # 任务输入示例 ├── .workflow-runs/ # 执行追踪存储 ├── src/ # 运行时源码 ├── docs/ # 文档 │ ├── ARCHITECTURE.md │ ├── WORKFLOW_PROFILES.md │ └── RUNTIME_VERIFIED_AGENTS.md └── QUICKSTART.md ``` ### 追踪存储 每次工作流执行都会在`.workflow-runs/`下创建： - 执行摘要 - 完整追踪记录 - 上下文状态 --- ## 与聊天式框架的对比 | 特性 | AgentFlow Runtime | 传统聊天式框架 | |------|-------------------|---------------| | 执行模型 | 确定性工作流 | 非确定性对话 | | 角色通信 | 结构化数据 | 自由文本 | | 可追踪性 | 完整持久化追踪 | 对话历史 | | 可重现性 | 高（相同输入=相同输出） | 低 | | 验证 | 显式模式验证 | 隐式/无 | | 审批门控 | 内置支持 | 需额外实现 | | 默认模式 | Mock（零成本） | 真实API调用 | --- ## 应用场景 ### 适用场景 - **需要严格控制的自动化流程**：如代码审查、测试验证 - **多步骤审批工作流**：如安全修复、生产变更 - **可重现的研究实验**：相同输入必须产生相同输出 - **多智能体协作演示**：清晰展示各角色职责 ### 不适用场景 - **开放式探索性对话**：需要灵活跳转的对话式应用 - **实时交互系统**：工作流执行可能有明显延迟 - **高度创造性任务**：确定性执行可能限制创造性输出 --- ## 设计理念与哲学 AgentFlow Runtime的设计反映了一种工程化思维：**智能体协作应该是可预测、可验证、可审计的**。 这与当前许多"黑盒"智能体框架形成对比。在那些框架中，智能体行为难以预测，协作过程难以追踪，失败原因难以定位。 AgentFlow Runtime通过以下原则实现可控性： 1. **显式优于隐式**：所有角色、边、验证规则都显式声明 2. **验证优于信任**：每个节点输出都经过模式验证 3. **追踪优于记忆**：完整执行历史持久化存储 4. **确定性优于灵活性**：相同输入产生相同输出 --- ## 结论 AgentFlow Runtime为LLM智能体应用开发提供了一种**工程化的协作框架**。它不是追求最灵活或最强大，而是追求**最可控、最可预测、最可验证**。 对于需要严格控制的场景——如代码生成、安全修复、生产变更——这种确定性工作流运行时可能比自由形式的智能体框架更合适。 项目的默认Mock模式也降低了入门门槛：你可以立即开始实验，无需担心API成本，直到你准备好接入真实模型。 对于正在探索多智能体协作的开发者，AgentFlow Runtime提供了一个值得研究的参考实现——**不是如何更智能，而是如何更可控**。