AgentLoom：基于OpenCode的确定性多智能体工作流编排引擎

AgentLoom是一个自托管的多智能体工作流运行器，与Claude Code动态工作流API兼容。它基于OpenCode构建，支持确定性AI工作流执行、子智能体扇出、自定义工具注册、提示词缓存优化等功能，并配有实时Web UI展示每个运行智能体的token和工具调用。

• 原作者/维护者：vblanco20-1
• 来源平台：github
• 原始标题：AgentLoom
• 原始链接：https://github.com/vblanco20-1/AgentLoom
• 来源发布时间/更新时间：2026-05-28T18:45:11Z

|------|----------------------|-----------| | 托管方式 | 云端托管，集成在客户端 | 完全自托管 | | 后端模型 | 内置Anthropic Claude | 基于OpenCode，支持多提供商 | | 工作流创作 | 支持AI辅助生成(workflow关键词) | CLI驱动，需手动编写 | | 权限管理 | 内置审批UX和组织治理 | 开发者自行管理 | | 计费模式 | 统一计费 | 直接使用各提供商API | | 额外功能 | 深度研究、ultracode模式 | defineTool、memory、replay | \n这种设计使得熟悉Claude Code工作流的开发者可以几乎零成本迁移到AgentLoom。\n\n---\n\n## 核心功能特性\n\n### 基于OpenCode的多提供商支持\n\nAgentLoom选择OpenCode作为每个智能体的后端执行引擎，这带来了关键优势：\n\n- 提供商无关性：不锁定特定AI模型，支持OpenAI、Anthropic、Google等多个提供商\n- 自托管能力：可以在私有基础设施上部署，满足数据隐私和合规要求\n- 成本透明：直接使用各提供商的API，没有中间商加价\n\n### 会话级提示词缓存优化\n\n对于大规模扇出(fan-out)工作流（如同时启动数十个子智能体），提示词缓存是控制成本的关键。AgentLoom实现了两项优化技术：\n\n#### 固定智能体配置文件\n\n在首次调用agent()之前，将智能体定义写入固定的.opencode/agent/.md文件，设置mode: subagent。这样：\n\n- 大型稳定的上下文（角色定义、规则、参考文档如CLAUDE.md）存储在配置文件中\n- OpenCode在服务器启动时一次性读取该配置\n- 所有智能体共享相同的系统提示，首次后的调用都能命中缓存\n- 每个智能体的变化部分（文件列表、任务ID）放在用户提示末尾\n\n#### 会话内重试\n\n当模式验证失败时，AgentLoom在同一OpenCode会话内重新提示(buildRetryPrompt)，而非创建全新上下文。这使得缓存的前缀在重试间得以保留。\n\n### 自定义工具注册(defineTool)\n\nAgentLoom允许工作流注册JavaScript回调函数作为MCP(Model Context Protocol)工具：\n\njavascript\ndefineTool('calculate', {\n description: 'Perform mathematical calculations',\n parameters: {\n type: 'object',\n properties: {\n expression: { type: 'string', description: 'Math expression to evaluate' }\n },\n required: ['expression']\n }\n}, async ({ expression }) => {\n return { result: eval(expression) };\n});\n\n\n这些工具被路由回同一个Bun进程执行，子智能体可以像调用原生工具一样调用它们。\n\n### 共享内存(memory)\n\nmemory()函数提供了一个跨智能体调用的共享内存文件：\n\njavascript\n// Agent A writes\nmemory().set('intermediate_result', someData);\n\n// Agent B reads\nconst data = memory().get('intermediate_result');\n\n\n这在需要智能体间传递中间结果时特别有用，避免了通过返回值和参数的繁琐传递。\n\n### 确定性回放(replay)\n\nAgentLoom支持录制和回放工作流执行：\n\nbash\n# 录制执行\nagent-runner run workflow.js --record\n\n# 确定性回放\nagent-runner replay <runId> --speed 2x\n\n\n这对于调试、测试和审计非常重要——可以精确重现某次执行，观察每个步骤的状态。\n\n### 实时Web UI\n\nAgentLoom内置了一个实时Web界面，在http://localhost:7777/run/<runId>展示：\n\n- 每个运行智能体的实时token流\n- 工具调用和返回结果\n- 执行阶段和进度\n- 错误和警告信息\n\n这让开发者能够直观地观察工作流执行过程，快速定位问题。\n\n---\n\n## 工作流脚本API详解\n\nAgentLoom向每个工作流脚本注入六个全局变量：\n\n### agent(prompt, opts)\n\n生成一个子智能体，返回经过模式验证的JSON或null，从不会抛出异常。\n\njavascript\nconst result = await agent(\n 'Review this code for security issues',\n {\n agent: 'security-reviewer', // 使用预定义的智能体配置\n schema: { // JSON模式验证\n type: 'object',\n properties: {\n issues: { type: 'array', items: { type: 'string' } },\n severity: { type: 'string', enum: ['low', 'medium', 'high'] }\n }\n },\n retries: 3 // 验证失败时的重试次数\n }\n);\n\n\n### pipeline(items, ...stages)\n\n为每个项目创建流式处理管道。第n个阶段接收(prev, originalItem, idx)，其中prev是上一阶段的输出。\n\njavascript\nconst results = await pipeline(\n files,\n async (file) => ({ content: await readFile(file) }), // Stage 1: 读取\n async ({ content }) => analyze(content), // Stage 2: 分析\n async (analysis) => generateReport(analysis) // Stage 3: 生成报告\n);\n\n\n### parallel(thunks)\n\nPromise.all的变体，接收thunk函数而非promise：\n\njavascript\nconst results = await parallel([\n () => agent('Task 1'),\n () => agent('Task 2'),\n () => agent('Task 3')\n]);\n\n\n### phase(title) / log(msg, meta?)\n\n用于遥测的阶段标记和日志记录：\n\njavascript\nphase('Data Processing');\nlog('Processing item', { itemId: 123 });\n\n\n### args\n\n从--args-file、--args-json或stdin传入的冻结输入对象：\n\njavascript\nconst { inputFile, outputDir } = args;\n\n\n---\n\n## 快速开始\n\n### 安装与构建\n\nbash\n# 克隆仓库\ngit clone https://github.com/vblanco20-1/AgentLoom.git\ncd AgentLoom\n\n# 安装依赖（使用Bun）\nbun install\n\n# 构建\nbun run build:all\n\n\n### 运行示例工作流\n\nbash\n# 运行最小示例\nbun bin/agent-runner run examples/minimal.workflow.js\n\n# 带参数运行\nbun bin/agent-runner run examples/codebase-review.workflow.js \\\n --args-json '{\"repo\": \"./my-project\", \"focus\": \"security\"}'\n\n\n### 配置\n\n在工作流旁放置runner.config.ts（或.js/.json）进行配置：\n\ntypescript\nexport default {\n opencode: {\n provider: 'anthropic',\n model: 'claude-3-5-sonnet-20241022',\n apiKey: process.env.ANTHROPIC_API_KEY\n },\n web: {\n port: 7777,\n autoOpen: true\n },\n persistence: {\n runsDir: './.runner/runs'\n }\n};\n\n\n---\n\n## 安全注意事项\n\nAgentLoom的工作流VM使用new AsyncFunction(...)执行脚本，这意味着：\n\n> ⚠️ 仅运行可信来源的工作流脚本！\n\n不要执行从互联网下载的、未经审查的.workflow.js文件，因为它们具有完整的JavaScript执行能力。\n\n---\n\n## 应用场景与价值\n\nAgentLoom适用于以下场景：\n\n### 代码库分析\n\n同时启动多个子智能体分析代码库的不同方面（安全性、性能、可维护性），然后汇总结果生成综合报告。\n\n### 数据处理管道\n\n构建复杂的数据ETL流程，每个阶段由AI智能体处理，利用pipeline的流式特性高效处理大规模数据。\n\n### 自动化测试生成\n\n为代码库自动生成单元测试、集成测试，并行执行并收集覆盖率报告。\n\n### 文档生成\n\n从代码注释、类型定义、使用示例中自动生成API文档、用户指南。\n\n### 研究与实验\n\n需要可复现的AI实验环境，记录每次执行的完整状态，支持事后分析和对比。\n\n---\n\n## 项目状态与展望\n\n根据IMPLEMENTATION_STATUS.md，AgentLoom目前处于预发布阶段(v0.1)。虽然核心功能已经实现，但作者明确表示这是"完全vibe-coded"的项目，不建议用于生产环境。\n\n尽管如此，项目展示了构建自托管AI工作流引擎的完整架构和技术选型，对于想要深入理解多智能体系统或构建类似工具的开发者具有重要参考价值。\n\n未来可能的发展方向包括：\n\n- 更完善的错误处理和恢复机制\n- 支持更多类型的工具集成（不仅是MCP）\n- 工作流可视化编辑器\n- 分布式执行支持（跨多台机器扇出智能体）\n- 与现有CI/CD系统的深度集成\n\n---\n\n## 总结\n\nAgentLoom是一个雄心勃勃的开源项目，它填补了当前AI工具链中的一个重要空白：自托管、多提供商、可观察的多智能体工作流引擎。通过与Claude Code工作流API的兼容，它降低了开发者的学习成本；通过OpenCode后端，它提供了模型选择的灵活性；通过提示词缓存优化，它控制了大规模执行的成本。\n\n对于正在探索AI工作流编排的开发者，AgentLoom提供了一个值得研究的参考实现，其架构设计和技术选择都体现了对实际工程问题的深入思考。\n

原作者与来源

• 原作者/维护者：vblanco20-1
• 来源平台：github
• 原始标题：AgentLoom
• 原始链接：https://github.com/vblanco20-1/AgentLoom
• 来源发布时间/更新时间：2026-05-28T18:45:11Z 原作者与来源\n\n- 原作者/维护者: vblanco20-1\n- 来源平台: GitHub\n- 原始标题: AgentLoom: Prototype agentic orchestrator for deterministic AI workflows\n- 原始链接: https://github.com/vblanco20-1/AgentLoom\n- 发布时间: 2026年5月28日\n\n---\n\n项目背景与定位\n\n随着大型语言模型(LLM)能力的飞速提升，基于智能体(Agent)的AI系统架构正在兴起。从单智能体对话到多智能体协作，从简单任务执行到复杂工作流编排，开发者需要更强大的工具来管理和协调这些AI工作流。\n\nAgentLoom应运而生，它是一个自托管的多智能体工作流运行器，其API设计与Claude Code的动态工作流功能完全兼容。这意味着开发者可以在本地环境中运行原本需要依赖Claude Code客户端的工作流脚本，获得更大的灵活性和控制权。\n\n项目的核心定位是：提供一个确定性、可复现、可观察的AI工作流执行引擎，让开发者能够构建复杂的智能体协作系统，同时保持对执行过程的完全掌控。\n\n---\n\n与Claude Code动态工作流的关系\n\nAgentLoom与Claude Code的动态工作流功能有着直接的渊源关系。Claude Code作为Anthropic推出的AI编程助手，内置了强大的工作流系统，支持通过自然语言描述让AI自动生成和执行多步骤任务。\n\nAgentLoom实现了相同的API表面，包括：\n\n- 相同的全局注入变量：agent()、pipeline()、parallel()、phase()、log()、args\n- 相同的元数据导出格式：meta = { name, description, phases }\n- 相同的模式验证机制：智能体返回结果经过JSON模式验证\n- 相同的非屏障管道语义：pipeline()阶段采用流式处理而非等待全部完成\n- 相同的后台执行模型：工作流在后台运行，支持暂停和恢复\n\n两者的主要区别在于：\n\n| 特性 | Claude Code动态工作流 | AgentLoom |