open-agent-platform源码解读

langchain-ai/open-agent-platform (OAP) 是 LangChain 官方为了展示 LangGraph 的强大能力而推出的参考实现 (Reference Implementation)。它不仅仅是一个 Demo，更是一个接近生产级的、支持 No-Code/Low-Code 配置的 Agent 平台。

核心定位：它的前身可以看作是 OpenGPTs 的升级版，但架构上更现代化，引入了 MCP (Model Context Protocol)、Supervisor (多智能体协作) 和 RAG (LangConnect) 等最新概念。

1. 整体架构概览 (Architecture)

OAP 采用了典型的 前后端分离 架构，核心逻辑完全依赖于 LangGraph 的图编排能力。

`

graph TD

subgraph Frontend_Nextjs

UI[Web UI - React/Tailwind]

Config[Agent Configuration UI]

Chat[Chat Interface]

end

subgraph Backend_FastAPI_LangGraph
    API[FastAPI Router]
    Runtime[LangGraph Runtime]
    Dispatcher[Agent Dispatcher]
    
    subgraph Graph_Logic
        Supervisor[Supervisor Node]
        Worker[Worker Agent]
        Tools[ToolNode - MCP Client]
    end
end

subgraph Infrastructure
    DB[(Postgres / Supabase)]
    MCP[External MCP Servers]
end

UI -->|REST/SSE| API
API -->|Invoke/Stream| Runtime
Runtime -->|Load/Save State| DB
Tools -->|Connect| MCP

`

2. 核心源码模块分析[1]

通常 OAP 的代码库结构如下（基于 LangChain 官方的最佳实践推断）：

2.1 后端 (Backend) - backend/

这是二次开发的核心战场。

• app/server.py (入口):

  • 通常使用 FastAPI 或 LangServe 启动服务。
  • 负责挂载 API 路由，处理 CORS，以及初始化数据库连接池。

• app/agent.py 或 app/graphs/ (核心大脑):关键点:

  • 这里定义了 StateGraph。[2]

  • Supervisor 模式: OAP 默认支持多智能体。你会看到一个 supervisor 节点，它使用 LLM 来决定下一个由哪个 worker 节点（如 ResearchAgent, CoderAgent）执行。

  • 代码特征:

    1 2 3 4 5 6

    # 典型的 Supervisor 路由逻辑 workflow.add_conditional_edges( "supervisor", lambda x: x["next"], {"Researcher": "research_node", "Coder": "coder_node", "FINISH": END} )

• app/tools/ (工具层 - 重点关注 MCP):

  • OAP 的一大亮点是支持 MCP。它不再只是简单的 Python 函数工具，而是作为一个 MCP Client 去连接外部的 MCP Server。
  • 二次开发点: 如果你想接入公司内部的 API，标准做法是写一个简单的 MCP Server，然后在 OAP 的配置界面填入该 Server 的 URL，而不是去改后端的 Python 代码。

• app/storage.py (持久化):

  • 使用 AsyncPostgresSaver。
  • Checkpointer: 负责保存每一步的 state。如果你要换 MySQL，就是改这里（参考之前的设计文档）。

2.2 前端 (Frontend) - frontend/

基于 Next.js 构建。

• components/AgentConfig.tsx (动态表单):
  • 亮点: OAP 的 UI 是配置驱动的。后端通过 Pydantic 模型定义了 Agent 的配置项（例如 system_prompt, model_name），前端会根据 Schema 自动生成表单。
  • x_oap_ui_config: 在后端的 Schema 中，你会发现字段上有这个 metadata，它告诉前端如何渲染该字段（例如是下拉框还是文本域）。
• hooks/useChatStream.ts:
  • 处理 SSE (Server-Sent Events)。它负责解析 LangGraph 传回来的 on_tool_start, on_chat_model_stream 等事件，并渲染成打字机效果。

---

3. 关键机制解析 (Deep Dive)

3.1 动态配置 (Configuration Schema)

OAP 不只是运行写死的 Agent，它允许用户在 UI 上创建 Agent。

• 原理: 后端定义了一个 “Configurable Runnable”。

• 代码逻辑: 在 graph.compile() 时，并没有把 prompt 写死，而是通过 configurable 参数传入。

  1 2 3

  def agent_node(state, config): system_msg = config["configurable"].get("system_prompt") # ... 使用 system_msg 调用 LLM

• 二次开发: 如果你想给 Agent 增加一个 “风格(Style)” 选项（如：幽默/严谨），你需要在后端的 Config Schema 中添加字段，前端 UI 会自动渲染出这个输入框。

3.2 工具集成 (The MCP Layer)

这是 OAP 最先进的地方。它解耦了 “Agent 平台” 和 “工具集”。

• 传统方式: 在 backend 代码里写 def search_tool(): …。
• OAP 方式:
  • Agent 启动时，读取配置中的 MCP Server 地址列表。
  • 通过 mcp-python-sdk 动态获取工具列表。
  • 将这些工具 bind_tools 到 LLM 上。
• 优势: 你可以在不重启 OAP 服务的情况下，通过部署新的 MCP Server 来扩展能力。

3.3 持久化与记忆 (Persistence)

OAP 使用 thread_id 来隔离会话。

• Checkpointing: 每次 LLM 输出或工具调用后，状态都会写入 Postgres。
• Time Travel: 虽然 UI 上可能简化了，但底层支持 get_state(thread_id)。如果你想做“撤回消息”或“修改分支”，后端能力是现成的。

---

4. 二次开发指南 (How to Customize)

如果你想基于 OAP 打造自己的企业级 Agent 平台，建议按以下步骤进行：

第一阶段：数据与鉴权改造

1. 替换鉴权: OAP 默认可能集成了 Supabase Auth 或简单的 Mock Auth。你需要修改 backend/app/auth.py (或类似文件) 接入你们公司的 OAuth / LDAP。
2. 替换数据库: 默认是 Postgres。如果你必须用 MySQL，请按照我之前提供的 AsyncMySQLSaver 代码替换掉 AsyncPostgresSaver。

第二阶段：自定义 Agent 模板

OAP 允许你定义不同的 “Agent Type”（模板）。

1. 在 backend/app/graphs/ 下新建一个 code_review_graph.py。
2. 定义专门用于代码审计的 StateGraph（包含 Git Loader 节点、SonarQube 分析节点等）。
3. 在入口文件注册这个新的 Graph ID。
4. 效果: 用户点击 “New Agent” 时，可以选择 “Code Reviewer” 模板。

第三阶段：接入业务工具 (MCP)

不要直接在 OAP 后端写业务逻辑代码。

1. 开发 MCP Server: 使用 mcp-python-sdk 创建一个独立的小服务，暴露你们公司的内部 API（如：查询订单、重启服务器）。
2. 配置连接: 在 OAP 界面上，添加这个 MCP Server 的 URL。
3. 效果: 你的 Agent 瞬间拥有了操作公司内部系统的能力，且做到了安全隔离。

第四阶段：UI 品牌化

1. 修改 frontend/tailwind.config.js 换成你们公司的品牌色。
2. 修改 frontend/app/layout.tsx 替换 Logo 和标题。

总结

open-agent-platform 是一个极佳的起点。它最大的价值在于：

1. Schema-Driven UI: 解决了“后端改配置，前端跑断腿”的问题。
2. MCP Native: 顺应了未来 AI 工具调用的标准协议。
3. LangGraph Core: 保证了底层编排能力的上限极高。

---

• ← Previous Post
• Next Post →

---

---