企业官网建设流程全解析

基于 LangGraph、Convex 与 MCP 的可视化 AI Agent 工作流构建器：Open Agent Builder 架构解析与部署实战

【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub

Open Agent Builder 是一个基于拖拽画布的可视化 AI Agent 工作流构建器：用户通过连接不同类型的节点即可编排复杂的多 Agent 流水线，再借助 LangGraph 完成状态管理、条件路由与人工审批，并通过 Composio 生态接入上万种工具、以 MCP 协议扩展能力。本文以本仓库open-agent-builder目录下的 README 为主体，结合其源码逐层讲解从环境部署、核心节点到执行引擎的原理，读完你既能独立跑通整个应用，也能理解"画布节点是如何变成可执行图"的底层机制。

一、项目定位：把 Agent 流水线变成一张可视化画布

Open Agent Builder 是 Firecrawl 团队发布的同名项目的分支版本，其核心目标非常明确：让你不需要手写大量编排代码，而是通过拖拽节点、连线的方式构建 AI Agent 复杂工作流，然后在真实环境中执行，并实时观察每一步的流式输出。

根据 README 的描述，它的工作方式可以概括为四点：

1. 拖拽式界面：在画布上搭建 Agent 工作流；
2. 实时执行：执行过程带流式（streaming）状态更新；
3. 8 种核心节点：Start、Agent、Tools、Transform、If/Else、While Loop、User Approval、End；
4. MCP 协议支持：借助 Composio 的 10,000+ 工具集成，为 Agent 提供可扩展的"技能层"。

也就是说，这个项目把"工具调用"这件事抽象成了 Agent 的外挂技能层：Composio 负责工具市场的供给（网页、数据、办公、AI 等领域），MCP（Model Context Protocol）负责工具与 Agent 之间标准化的连接协议，而画布负责把"谁先执行、什么条件下执行、循环几次、是否需要人审批"这些编排逻辑可视化。

二、技术栈全景：每一层都有明确分工

README 中用一张表格给出了完整的技术选型，每一层解决一个特定问题：

从 package.json 的依赖声明可以进一步印证这套架构：@langchain/langgraph（0.4.x）、convex（1.28.x）、@clerk/nextjs（6.33.x）、@xyflow/react（12.8.x，即 React Flow）、@composio/core、@modelcontextprotocol/sdk、@e2b/code-interpreter等一应俱全。

在众多 Provider 中，README 特别强调：当工作流使用 MCP 工具时，Anthropic Claude 是当前推荐的首选 Provider，因为它对 MCP 有原生支持（Claude Haiku 4.5 / Sonnet 4.5）。

三、核心节点类型与工作流数据结构

README 列出的 8 种核心节点是 UI 层面最常用的抽象。而翻开 类型定义文件 可以看到，底层类型系统其实定义得更细，WorkflowNode的type联合类型包含：agent、mcp、if-else、while、user-approval、transform、set-state、end、start、guardrails、arcade、note。

一个节点的数据结构如下（摘自 types.ts）：

export interface WorkflowNode { id: string; type: 'agent' | 'mcp' | 'if-else' | 'while' | 'user-approval' | 'transform' | 'set-state' | 'end' | 'start' | 'guardrails' | 'arcade' | 'note'; position: { x: number; y: number }; data: NodeData; }

data字段（NodeData）按节点类型承载不同配置，例如：

• Agent 节点：instructions（指令）、model（模型标识）、tools（MCP server ID 列表）、outputFormat（输出格式，支持 JSON）、includeChatHistory（是否携带对话历史）、reasoningEffort等；
• Start 节点：inputVariables数组，每个输入变量包含name、type、required、description、defaultValue；
• If/Else 节点：condition（条件表达式）、trueLabel/falseLabel（分支标签）；
• While 节点：whileCondition、maxIterations、timeoutMinutes；
• Transform 节点：transformScript（可执行的转换脚本）；
• User Approval 节点：approvalMessage（审批提示文案）；
• MCP 节点：mcpServers（MCPServer 配置列表）、mcpAction、outputField；
• Arcade 节点：arcadeTool（如GoogleDocs.CreateDocumentFromText@4.3.1）、arcadeInput、arcadeUserId。

MCPServer结构同样清晰（types.ts）：id、name、label、url、authType、accessToken、tools。这意味着每个 MCP 服务器都可以携带独立的认证信息与可用工具列表。

边（WorkflowEdge）则额外支持label与sourceHandle两个字段——这正是条件分支（if/else）与循环分支（continue/break）在数据结构上的落点。

四、环境准备与完整部署步骤

4.1 克隆仓库与安装依赖

git clone https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub.git cd ai-engineering-hub/open-agent-builder npm install

4.2 初始化 Convex（实时数据库）

Convex 负责所有工作流与执行数据的持久化。README 给出的步骤是：

# 全局安装 Convex CLI npm install -g convex # 初始化 Convex 项目 npx convex dev

执行npx convex dev后会发生三件事：

• 打开浏览器引导你创建/关联一个 Convex 项目；
• 在.env.local中自动生成NEXT_PUBLIC_CONVEX_URL；
• 启动 Convex 开发服务器。

注意：Convex dev server 需要保持运行，建议放在独立的终端窗口中。

4.3 配置 Clerk（用户认证）

Clerk 提供安全的用户认证与管理能力，配置流程为：

1. 前往 clerk.com 创建新应用；
2. 在 Clerk 控制台API Keys页面复制密钥；
3. 进入JWT Templates → Convex，点击 "Apply" 并复制 issuer URL。

随后写入.env.local：

# Clerk Authentication NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_... CLERK_SECRET_KEY=sk_test_... # Clerk + Convex Integration CLERK_JWT_ISSUER_DOMAIN=https://your-clerk-domain.clerk.accounts.dev

4.4 配置 Convex 认证（关键一步）

编辑 convex/auth.config.ts，把domain替换成你自己的 Clerk issuer URL：

export default { providers: [ { domain: "https://your-clerk-domain.clerk.accounts.dev", // 你的 Clerk issuer URL applicationID: "convex", }, ], };

然后重新推送认证配置到 Convex：

npx convex dev

从源码注释可以看到，该文件的domain实际读取的是 Convex 环境变量（通过npx convex env set CLERK_JWT_ISSUER_DOMAIN "https://..."设置），而非process.env，这一步如果遗漏会导致登录后无法正确关联用户身份。

4.5 可选：配置默认 LLM Provider

用户也可以通过界面（Settings → API Keys）自行添加 LLM API Key。若想配置默认 Provider，在.env.local中加入：

# Anthropic Claude（推荐 - 原生 MCP 支持，Haiku 4.5 & Sonnet 4.5） ANTHROPIC_API_KEY=sk-ant-... # OpenAI GPT-5 OPENAI_API_KEY=sk-... # Groq GROQ_API_KEY=gsk_...

重要提示：对于使用 MCP 工具的工作流，Anthropic Claude 目前是推荐 Provider，因为它对 MCP 有原生支持。这一点在 Agent 执行器源码 中也有印证：Claude 路径使用client.beta.messages.create并直接传入mcp_servers配置与mcp-client-2025-04-04beta 标志。

4.6 可选：E2B 沙箱代码解释器

Transform 节点如果要做"沙箱化代码执行"（例如让 Agent 动态生成并运行 Python 代码），需要配置 E2B：

# E2B Code Interpreter（可选） E2B_API_KEY=e2b_...

密钥可在 e2b.dev 获取，对应依赖为 package.json 中的@e2b/code-interpreter。

五、启动应用

README 提供了两种启动方式。标准方式是开两个终端：

# 终端 1：Convex dev server npx convex dev # 终端 2：Next.js dev server npm run dev

也可以一条命令同时启动两者（依赖concurrently）：

npm run dev:all

启动后访问 http://localhost:3000 即可进入可视化画布界面。

六、源码级深度解析：画布节点如何变成可执行图

部署只是第一步，理解这套系统最有趣的部分，是"画布上的节点 + 连线"如何被转换成真正可运行的编排逻辑。核心答案集中在 LangGraph 执行器。

6.1 从 Workflow 到 StateGraph 的编译过程

LangGraphExecutor类的构造函数会调用buildGraph()，把Workflow（节点数组 + 边数组）编译成 LangGraph 的StateGraph。编译时做了几件关键的事（langgraph.ts）：

1. 边校验：跳过 source/target 不存在的非法边，避免运行时崩溃；
2. Note 节点跳过：note类型的节点是纯视觉便利贴，不参与图执行；
3. Start / End 节点处理：Start 节点接入 LangGraph 的START，所有 End 节点统一连到内置END；
4. 条件路由：if-else节点通过addConditionalEdges注册条件路由器，按边的sourceHandle（if/else）决定走向；
5. 循环路由：while节点注册循环路由器，按continue/break两个分支返回目标；
6. 并行路由：如果一个普通节点的出边超过 1 条且目标不唯一，会自动启用并行执行（shouldUseParallelRouting）；
7. 编译前诊断：如果某个节点从 Start 不可达，会抛出包含"不可达节点清单"和修复建议的详细错误，方便用户在画布上排查断连问题。

6.2 状态管理：Annotation 定义工作流上下文

工作流的运行时状态通过WorkflowStateAnnotation定义（langgraph.ts），共 6 个字段：

每个节点执行器返回的都是不可变的 state 更新（通过 reducer 友好格式合并），而不是直接修改状态，这保证了 LangGraph 检查点（checkpoint）机制的可靠性。

6.3 检查点、中断与恢复：human-in-the-loop 的基石

LangGraphExecutor显式启用了MemorySaver检查点器（langgraph.ts），并在注释中列出了四大用途：

• human-in-the-loop 审批（interrupt/resume）；
• Arcade 授权暂停；
• 服务器重启后恢复工作流；
• 时间旅行调试（time-travel debugging）。

执行层面，executeStream使用streamMode: "values"并设置recursionLimit: 100（默认 25），以支持最多 100 步的图执行。当某个节点触发interrupt()（如 User Approval 节点、Arcade 授权）时，流会产出携带pendingAuth的暂停状态；恢复时通过resumeFromAuth传入Command({ resume: resumeValue })继续执行（langgraph.ts）。

6.4 Agent 节点执行器：多 Provider 调度与 MCP 工具桥接

Agent 执行器 是整个系统最核心的执行单元，其工作流程为：

1. 变量替换：先用substituteVariables把指令中的{{...}}占位符替换为真实状态值；
2. MCP 解析：通过resolveMCPServers/migrateMCPData把 MCP server ID 解析为完整配置（兼容新旧两种数据格式）；
3. Provider 解析：模型字符串如anthropic/claude-sonnet-4-5-20250929会被按第一个/拆分为 provider 与 modelName；
4. 按 Provider 分流：
   • Anthropic：使用原生@anthropic-ai/sdk，有 MCP 工具时通过messages.create+mcp_servers参数调用，并解析tool_use/mcp_tool_use两种内容块；
   • OpenAI：有 MCP 工具时把 MCP 工具转换为 OpenAI function calling 格式，采用"先调工具、再把工具结果回填做第二次补全"的两段式调用；
   • Groq：使用 Responses API 并把 MCP 工具映射为type: "mcp"的server_label/server_url；
5. 输出归一化：返回__agentValue（最终文本或解析后的 JSON）、__agentToolCalls（工具调用记录）、__chatHistoryUpdates（对话历史增量）、__variableUpdates（变量增量），供上层 reducer 合并。

此外，源码还内置了MOCK_AGENT_RESPONSE环境变量：设置后可以按节点 ID 或节点名返回 mock 输出，方便在不消耗真实 LLM 调用的情况下测试工作流逻辑——这是做 CI 集成测试时的利器。

6.5 变量替换机制：{{...}}模板语法

变量贯穿整个工作流：Start 节点接收输入 → Agent 节点产出结果 → Transform 节点加工 → 条件节点判断。这一切的粘合剂是 variable-substitution.ts 中的substituteVariables：

• 支持两种写法：完整式{{state.variables.node_1.price}}与简写式{{node_1.price}}（自动补全state.variables.前缀）；
• 支持input.xxx、lastOutput.xxx快捷引用；
• 支持数组下标，如{{items[0]}}；
• 求值失败时保留原占位符而不是抛错，避免单个变量错误导致整个节点失败；
• 配套提供extractVariableReferences（提取全部引用）与validateVariableReferences（校验缺失引用），以及getAvailableVariables（为 UI 提供变量自动补全列表）。

同一套机制也被 If/Else 条件、While 循环条件与审批消息复用，是整个画布"数据流"一致性的基础。

6.6 循环控制：最大迭代上限与安全护栏

While 循环节点由 langgraph.ts 中的createWhileLoopRouter与executeWhileNode实现，核心参数是maxIterations：

• 默认值为10次；
• 硬性上限100次（ABSOLUTE_MAX），超出会被强制截断并给出警告，防止死循环拖垮执行；
• 循环路由器根据上次迭代输出的condition、stoppedReason（condition_false/max_iterations）以及当前迭代计数决定continue还是break；
• 迭代计数以${nodeId}__iterationCount为 key 保存在variables中，累计结果以${nodeId}__loopResults累积，循环退出后这些结果会透传给下游节点。

6.7 Convex 数据模型：七张表支撑全链路

convex/schema.ts 定义了完整的存储模型，共 8 张表：

其中mcpServers表反映了 MCP 的集中化管理思路：每个服务器都记录authType（none/api-key/bearer/oauth-coming-soon）、connectionStatus（connected/error/untested）、enabled与isOfficial（是否为内置官方 MCP）等字段，UI 侧可以直接展示连接状态与最近测试时间。

七、开箱即用的模板示例：Simple Agent

仓库在 lib/workflow/templates/examples/01-simple-agent.ts 中提供了一个最基础的工作流模板，用来展示数据结构的实际写法：

• 流程为Start → Agent → End，适合"单轮问答、简单文本生成"场景；
• Start 节点定义了一个必填输入变量question；
• Agent 节点使用anthropic/claude-sonnet-4-20250514模型，指令中通过{{input.question}}引用用户输入；
• 输出格式为Text。

这个模板同时是理解"一个最小可用工作流 JSON 长什么样"的最佳起点，也常被用于端到端测试（对应 package.json 中的npm run test:workflow与npm run test:simple）。

八、测试与验证体系

从 package.json 的 scripts 可以看出，项目内置了相当完整的测试入口：

• npm run test：Playwright 端到端测试；
• npm run test:mcp：远程 MCP 连接测试（add-remote-mcp.spec.ts）；
• npm run test:workflow/test:simple等：基于脚本对单个模板工作流做执行验证；
• npm run test:approval：审批工作流测试；
• npm run test:streaming：流式输出测试；
• npm run test:comprehensive/test:templates：综合工作流与模板校验。

结合前面提到的MOCK_AGENT_RESPONSE机制，开发者可以在完全不消耗真实 LLM 额度的情况下跑通以上绝大部分测试，这对工作流编排类应用的质量保障至关重要。

九、总结：从画布到生产可用的编排引擎

Open Agent Builder 的价值在于把"AI Agent 工作流编排"拆成了清晰的分层：React Flow 负责可视化编辑，LangGraph 负责图执行与状态管理，Convex 负责持久化与实时同步，Clerk 负责身份认证，MCP + Composio 负责工具能力供给。README 提供的 8 种核心节点覆盖了顺序执行、分支判断、循环迭代、人工审批与数据处理这几类最常见的编排原语，而源码层面的LangGraphExecutor、多 Provider Agent 执行器、{{...}}变量替换与检查点恢复机制，则为这些原语提供了可生产运行的实现支撑。

如果你希望在此基础上做二次开发，最值得深入阅读的三个文件是：类型定义（了解节点与数据模型）、LangGraph 执行器（了解图编译、条件路由、循环与中断恢复）、以及 Convex Schema（了解存储与索引设计）。按照本文第四、五节的步骤完成部署后，你就可以在 localhost:3000 的画布上拖出第一个属于自己的多 Agent 工作流了。

【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub