基于 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-hubOpen Agent Builder 是一个基于拖拽画布的可视化 AI Agent 工作流构建器用户通过连接不同类型的节点即可编排复杂的多 Agent 流水线再借助 LangGraph 完成状态管理、条件路由与人工审批并通过 Composio 生态接入上万种工具、以 MCP 协议扩展能力。本文以本仓库open-agent-builder目录下的 README 为主体结合其源码逐层讲解从环境部署、核心节点到执行引擎的原理读完你既能独立跑通整个应用也能理解画布节点是如何变成可执行图的底层机制。一、项目定位把 Agent 流水线变成一张可视化画布Open Agent Builder 是 Firecrawl 团队发布的同名项目的分支版本其核心目标非常明确让你不需要手写大量编排代码而是通过拖拽节点、连线的方式构建 AI Agent 复杂工作流然后在真实环境中执行并实时观察每一步的流式输出。根据 README 的描述它的工作方式可以概括为四点拖拽式界面在画布上搭建 Agent 工作流实时执行执行过程带流式streaming状态更新8 种核心节点Start、Agent、Tools、Transform、If/Else、While Loop、User Approval、EndMCP 协议支持借助 Composio 的 10,000 工具集成为 Agent 提供可扩展的技能层。也就是说这个项目把工具调用这件事抽象成了 Agent 的外挂技能层Composio 负责工具市场的供给网页、数据、办公、AI 等领域MCPModel Context Protocol负责工具与 Agent 之间标准化的连接协议而画布负责把谁先执行、什么条件下执行、循环几次、是否需要人审批这些编排逻辑可视化。二、技术栈全景每一层都有明确分工README 中用一张表格给出了完整的技术选型每一层解决一个特定问题技术职责Composio10,000 工具集成作为 AI Agent 的技能层Next.js 16canaryReact 框架App Router 承载前端页面与 API 路由TypeScript全栈类型安全LangGraph工作流编排引擎提供状态管理、条件路由与 human-in-the-loop 支持Convex实时数据库负责工作流、执行记录与用户数据的自动响应式同步Clerk认证与用户管理支持 JWT 集成Tailwind CSS原子化 CSS构建响应式 UIReact Flow可视化画布提供可拖拽的节点AnthropicClaude AI 集成Claude Haiku 4.5 与 Sonnet 4.5原生支持 MCPOpenAIgpt-5 集成Groq针对开源模型的高效推理E2B沙箱化代码执行为 Transform 节点提供安全运行环境从 package.json 的依赖声明可以进一步印证这套架构langchain/langgraph0.4.x、convex1.28.x、clerk/nextjs6.33.x、xyflow/react12.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.tsexport 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模型标识、toolsMCP server ID 列表、outputFormat输出格式支持 JSON、includeChatHistory是否携带对话历史、reasoningEffort等Start 节点inputVariables数组每个输入变量包含name、type、required、description、defaultValueIf/Else 节点condition条件表达式、trueLabel/falseLabel分支标签While 节点whileCondition、maxIterations、timeoutMinutesTransform 节点transformScript可执行的转换脚本User Approval 节点approvalMessage审批提示文案MCP 节点mcpServersMCPServer 配置列表、mcpAction、outputFieldArcade 节点arcadeTool如GoogleDocs.CreateDocumentFromText4.3.1、arcadeInput、arcadeUserId。MCPServer结构同样清晰types.tsid、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 install4.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 提供安全的用户认证与管理能力配置流程为前往 clerk.com 创建新应用在 Clerk 控制台API Keys页面复制密钥进入JWT Templates → Convex点击 Apply 并复制 issuer URL。随后写入.env.local# Clerk Authentication NEXT_PUBLIC_CLERK_PUBLISHABLE_KEYpk_test_... CLERK_SECRET_KEYsk_test_... # Clerk Convex Integration CLERK_JWT_ISSUER_DOMAINhttps://your-clerk-domain.clerk.accounts.dev4.4 配置 Convex 认证关键一步编辑 convex/auth.config.ts把domain替换成你自己的 Clerk issuer URLexport default { providers: [ { domain: https://your-clerk-domain.clerk.accounts.dev, // 你的 Clerk issuer URL applicationID: convex, }, ], };然后重新推送认证配置到 Convexnpx 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_KEYsk-ant-... # OpenAI GPT-5 OPENAI_API_KEYsk-... # Groq GROQ_API_KEYgsk_...重要提示对于使用 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_KEYe2b_...密钥可在 e2b.dev 获取对应依赖为 package.json 中的e2b/code-interpreter。五、启动应用README 提供了两种启动方式。标准方式是开两个终端# 终端 1Convex dev server npx convex dev # 终端 2Next.js dev server npm run dev也可以一条命令同时启动两者依赖concurrentlynpm run dev:all启动后访问 http://localhost:3000 即可进入可视化画布界面。六、源码级深度解析画布节点如何变成可执行图部署只是第一步理解这套系统最有趣的部分是画布上的节点 连线如何被转换成真正可运行的编排逻辑。核心答案集中在 LangGraph 执行器。6.1 从 Workflow 到 StateGraph 的编译过程LangGraphExecutor类的构造函数会调用buildGraph()把Workflow节点数组 边数组编译成 LangGraph 的StateGraph。编译时做了几件关键的事langgraph.ts边校验跳过 source/target 不存在的非法边避免运行时崩溃Note 节点跳过note类型的节点是纯视觉便利贴不参与图执行Start / End 节点处理Start 节点接入 LangGraph 的START所有 End 节点统一连到内置END条件路由if-else节点通过addConditionalEdges注册条件路由器按边的sourceHandleif/else决定走向循环路由while节点注册循环路由器按continue/break两个分支返回目标并行路由如果一个普通节点的出边超过 1 条且目标不唯一会自动启用并行执行shouldUseParallelRouting编译前诊断如果某个节点从 Start 不可达会抛出包含不可达节点清单和修复建议的详细错误方便用户在画布上排查断连问题。6.2 状态管理Annotation 定义工作流上下文工作流的运行时状态通过WorkflowStateAnnotation定义langgraph.ts共 6 个字段字段类型reducer 行为用途variablesRecordstring, any合并merge核心变量含input、lastOutput及各节点输出chatHistory消息数组追加多轮对话上下文currentNodeIdstring覆盖记录当前执行节点nodeResults节点结果表合并每个节点的执行状态、输出、错误、工具调用记录pendingAuthany覆盖等待中的授权/审批状态loopResults数组追加循环迭代结果的累积器每个节点执行器返回的都是不可变的 state 更新通过 reducer 友好格式合并而不是直接修改状态这保证了 LangGraph 检查点checkpoint机制的可靠性。6.3 检查点、中断与恢复human-in-the-loop 的基石LangGraphExecutor显式启用了MemorySaver检查点器langgraph.ts并在注释中列出了四大用途human-in-the-loop 审批interrupt/resumeArcade 授权暂停服务器重启后恢复工作流时间旅行调试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 执行器 是整个系统最核心的执行单元其工作流程为变量替换先用substituteVariables把指令中的{{...}}占位符替换为真实状态值MCP 解析通过resolveMCPServers/migrateMCPData把 MCP server ID 解析为完整配置兼容新旧两种数据格式Provider 解析模型字符串如anthropic/claude-sonnet-4-5-20250929会被按第一个/拆分为 provider 与 modelName按 Provider 分流Anthropic使用原生anthropic-ai/sdk有 MCP 工具时通过messages.createmcp_servers参数调用并解析tool_use/mcp_tool_use两种内容块OpenAI有 MCP 工具时把 MCP 工具转换为 OpenAI function calling 格式采用先调工具、再把工具结果回填做第二次补全的两段式调用Groq使用 Responses API 并把 MCP 工具映射为type: mcp的server_label/server_url输出归一化返回__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、stoppedReasoncondition_false/max_iterations以及当前迭代计数决定continue还是break迭代计数以${nodeId}__iterationCount为 key 保存在variables中累计结果以${nodeId}__loopResults累积循环退出后这些结果会透传给下游节点。6.7 Convex 数据模型七张表支撑全链路convex/schema.ts 定义了完整的存储模型共 8 张表表用途关键索引users从 Clerk 同步的用户by_clerkId、by_emailworkflows工作流定义节点、边、元数据by_userId、by_customId、by_category、by_templateexecutions执行记录与状态by_workflow、by_status、by_startedmcpServersMCP 服务器注册中心含 authType、工具列表、连接状态by_userId、by_category、by_officialarcadeAuthArcade 工具授权记录by_authId、by_statususerMCPs用户自定义 MCPCursor 风格配置by_userId、by_nameapiKeys用户 API Key哈希存储 前缀展示by_userId、by_keyuserLLMKeys用户自带的 LLM Provider Key加密存储、多 Providerby_userProvider、by_activeapprovals人工审批记录pending/approved/rejectedby_status、by_userId、by_workflow、by_execution其中mcpServers表反映了 MCP 的集中化管理思路每个服务器都记录authTypenone/api-key/bearer/oauth-coming-soon、connectionStatusconnected/error/untested、enabled与isOfficial是否为内置官方 MCP等字段UI 侧可以直接展示连接状态与最近测试时间。七、开箱即用的模板示例Simple Agent仓库在 lib/workflow/templates/examples/01-simple-agent.ts 中提供了一个最基础的工作流模板用来展示数据结构的实际写法流程为Start → Agent → End适合单轮问答、简单文本生成场景Start 节点定义了一个必填输入变量questionAgent 节点使用anthropic/claude-sonnet-4-20250514模型指令中通过{{input.question}}引用用户输入输出格式为Text。这个模板同时是理解一个最小可用工作流 JSON 长什么样的最佳起点也常被用于端到端测试对应 package.json 中的npm run test:workflow与npm run test:simple。八、测试与验证体系从 package.json 的 scripts 可以看出项目内置了相当完整的测试入口npm run testPlaywright 端到端测试npm run test:mcp远程 MCP 连接测试add-remote-mcp.spec.tsnpm 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考