1. 技术栈

前端框架: Next.js + React + Antd + @ant-design/x（AI 对话）

Agent 框架: LangChain.js + LangGraph + @langchain/mcp-adapters（MCP 工具集成）

数据存储: MongoDB

Markdown 渲染: @ant-design/x-markdown

可观测性: Langfuse

核心模块：

• • src/agents/ - Agent 定义文件目录

• • src/lib/agents/ - Agent 核心库

• • src/app/api/agents/ - RESTful API 路由

---

2. 最简 Agent Demo（结合 MCP）

// src/agents/demo-agent.js
import { defineAgent } from '@/lib/agents/define';
import { createAgent } from 'langchain';
import { ChatOpenAI } from '@langchain/openai';
import { MultiServerMCPClient } from '@langchain/mcp-adapters';

// MCP 服务配置
const MCP_SERVERS = {
  my_tools: {
    transport: 'http',
    url: 'https://your-mcp-server.com/mcp',
  },
};

// 缓存 MCP 工具
let cachedTools = null;

async function getMCPTools() {
  if (cachedTools) return cachedTools;
  const client = new MultiServerMCPClient({ mcpServers: MCP_SERVERS });
  cachedTools = await client.getTools();
  return cachedTools;
}

export default defineAgent({
  id: 'demo-agent',
  name: 'Demo 助手',
  description: '最简 MCP Agent 示例',

  createAgent: async () => {
    const model = new ChatOpenAI({
      model: 'gpt-4.1',
      temperature: 0.3,
      apiKey: process.env.OPENAI_API_KEY,
      configuration: { baseURL: process.env.OPENAI_BASE_URL },
    });

    const tools = await getMCPTools();

    return createAgent({
      model,
      tools,
      systemPrompt: '你是一个智能助手，可以使用工具完成任务。',
    });
  },
});

注册 Agent（在 src/lib/agents/scanner.js）：

import demoAgent from '@/agents/demo-agent';

const AGENT_MODULES = [
  { filename: 'demo-agent.js', module: demoAgent },
];

---

4. Agent 定义

使用 defineAgent() 辅助函数定义 Agent：

defineAgent({
  id: 'agent-id',           // 唯一标识（可选，默认从文件名推断）
  name: '显示名称',
  description: '描述',
  isPublic: true,           // 是否公开
  examples: [],             // 快捷提问示例
  createAgent: async () => { /* 返回 LangGraph Agent */ }
})

---

5. Agent 注册机制

采用静态导入方式注册 Agent（Next.js 打包限制，无法动态扫描文件）：

// src/lib/agents/scanner.js
import businessAgent from '@/agents/business-agent';
import chartAgent from '@/agents/chart-agent';

const AGENT_MODULES = [
  { filename: 'business-agent.js', module: businessAgent },
  { filename: 'chart-agent.js', module: chartAgent },
];

添加新 Agent 步骤：

1. 1. 在 src/agents/ 创建 Agent 文件

2. 2. 在 scanner.js 中 import 并添加到 AGENT_MODULES 数组

AgentRegistry 功能：

• • 懒加载初始化

• • Agent 实例缓存

• • 元数据查询（支持 isPublic 过滤）

---

6. 任务执行

核心特性：

• • 后台任务执行，客户端断开连接后仍能完整执行

• • 使用 agent.streamEvents() 处理流式事件

• • 支持事件类型：on_chat_model_stream、on_tool_start、on_tool_end、on_chain_start/end

• • 定时批量更新数据库（300ms 间隔）

• • 通过 onProgress 回调实时推送进度

---

7. 数据持久化

5.1 MongoDB 连接管理

src/lib/db/mongodb.js 实现了 MongoDB 连接的单例模式和连接池管理：

import { mongoDBManager } from '@/lib/db/mongodb';

// 获取集合
const collection = await mongoDBManager.getCollection('my_collection');

// 获取数据库实例
const db = await mongoDBManager.getDb();

连接池配置：

• • maxPoolSize: 10 - 最大连接数

• • minPoolSize: 1 - 最小连接数

• • maxIdleTimeMS: 30000 - 空闲超时

• • connectTimeoutMS: 10000 - 连接超时

5.2 聊天记录服务

src/lib/db/chatHistory.js 采用会话-消息分离的数据结构设计：

数据集合：

集合名	用途
chat_sessions	存储会话元数据（不含消息）
chat_messages	存储消息内容（按 sessionId 关联）

会话结构 (chat_sessions)：

{
  _id: ObjectId,
  agentId: string,      // 关联的 Agent ID
  userId: string,       // 用户 ID
  title: string,        // 会话标题
  messageCount: number, // 消息计数
  deleted: boolean,     // 逻辑删除标记
  createdAt: Date,
  updatedAt: Date
}

消息结构 (chat_messages)：

{
  _id: ObjectId,
  sessionId: string,    // 关联的会话 ID
  key: string,          // 消息唯一标识
  role: 'user' | 'assistant',
  content: string | Array,  // 支持多模态
  toolCalls: Array,     // 工具调用记录
  streaming: boolean,   // 是否流式中
  timestamp: Date
}

5.3 对话存储

src/lib/agents/conversationStore.js 提供 Agent 对话的持久化：

• • 支持创建/查询/删除对话

• • 按 agentId、userId 查询

• • 消息追加与批量追加

• • 自动创建索引优化查询

---

8. API 接口

接口	方法	功能
/api/agents	GET	获取 Agent 列表（支持 public 过滤）
/api/agents?id=xxx	GET	获取单个 Agent 元数据
/api/agents/[id]/chat	POST	与 Agent 对话（支持流式/非流式）

Chat API 特性：

• • 支持流式响应

• • 支持多模态消息（文本/数组）

• • 支持对话历史传入

• • 集成 Langfuse 追踪

---

9. MCP 工具集成

通过 @langchain/mcp-adapters 集成 MCP 服务：

import { MultiServerMCPClient } from "@langchain/mcp-adapters";

const mcpClient = new MultiServerMCPClient({ mcpServers: MCP_SERVERS });
const tools = await mcpClient.getTools();

支持工具缓存避免重复加载。

---

10. 提示词管理（两种方式）

方式一：接口动态获取

通过 getPrompt() 从提示词管理系统动态获取，支持版本管理和缓存：

import { getPrompt } from '@/lib/agents/prompt';

const systemPrompt = await getPrompt({ id: 27 });  // 获取最新版本
const systemPrompt = await getPrompt({ id: 27, version: '1.0.0' });  // 指定版本

接口地址: GET http://kuai.kujiale.com/api/prompts/{id}/versions

方式二：硬编码

直接在代码中定义：

const SYSTEM_PROMPT = `你是一个智能助手。`;

选择建议: 需要频繁调整 → 接口获取；稳定场景 → 硬编码

---

11. Agent 分享功能

支持四种分享方式，将 Agent 能力对外输出：

11.1 Web 独立页面

直接访问分享链接，提供完整的聊天界面：

https://your-domain.com/share/{shareId}

适用场景: 分享给用户直接访问，无需任何集成工作

11.2 iframe 嵌入

将聊天界面嵌入到第三方网站：

<iframe 
  src="https://your-domain.com/share/iframe/{shareId}" 
  width="100%" 
  height="600" 
  frameborder="0">
</iframe>

适用场景: 嵌入到已有网站、后台系统、帮助中心等

11.3 Bubble 气泡组件

悬浮聊天气泡，用户点击展开对话面板：

<script 
  id="chatbot-bubble"
  src="https://your-domain.com/share/bubble.js"
  data-bot-src="https://your-domain.com/share/{shareId}"
  data-default-open="false"
  data-drag="true">
</script>

配置参数:

• • data-bot-src: 分享链接地址（必填）

• • data-default-open: 是否默认展开（默认 false）

• • data-drag: 是否可拖拽（默认 false）

• • data-open-icon: 自定义打开图标 URL

• • data-close-icon: 自定义关闭图标 URL

功能特性:

• • 悬浮气泡图标，点击展开聊天面板

• • 支持拖拽定位

• • 支持面板拉伸调整大小

• • 响应式适配移动端

• • ESC 键关闭

适用场景: 官网、产品页面、客服入口等需要悬浮助手的场景

11.4 API 调用

通过 API 直接调用 Agent 能力：

// 发送消息
POST /api/agents/{agentId}/chat
{
  "message": "你好",
  "stream": true,
  "history": []
}

适用场景: 程序化集成、自定义 UI、后端服务调用

---

12. 架构图

Agent 核心
HTTP/SSE
外部服务
LLMGPT/Qwen/DeepSeek
MCP Servers工具服务
Prompt System提示词管理
MongoDB 持久化
chat_sessions
chat_messages
share_configs
Agent 定义 (src/agents/)
chart-agent
business-agent
...
Next.js API Routes
/api/agents
/api/agents/[id]/chat
/api/share
客户端
Web 直接访问
iframe 嵌入
Bubble 气泡组件
AgentRegistryAgent 注册表
AgentScanner静态导入
TaskRunner后台任务执行

---

13. 目录结构

src/
├── agents/                      # Agent 定义文件
│   ├── chart-agent.js           # 图表生成助手
│   ├── business-agent.js        # 业务助手
│   ├── smart-search-agent.js    # 智能搜索助手
│   ├── apollo-agent.js          # Apollo 助手
│   └── README.md                # Agent 开发指南
├── lib/
│   ├── agents/                  # Agent 核心库
│   │   ├── index.js             # 统一导出
│   │   ├── define.js            # defineAgent 辅助函数
│   │   ├── scanner.js           # Agent 扫描注册
│   │   ├── registry.js          # Agent 注册表
│   │   ├── taskRunner.js        # 后台任务执行器
│   │   ├── conversationStore.js # 对话存储
│   │   └── prompt.js            # 提示词获取
│   ├── db/                      # 数据库层
│   │   ├── mongodb.js           # MongoDB 连接管理
│   │   └── chatHistory.js       # 聊天记录服务
│   ├── share/                   # 分享功能
│   │   ├── index.js             # 统一导出
│   │   ├── shareConfig.js       # 分享配置服务
│   │   ├── shareChat.js         # 分享聊天服务
│   │   ├── shareAnalytics.js    # 分享统计服务
│   │   └── accessControl.js     # 访问控制
│   └── langfuse.js              # Langfuse 追踪集成
├── app/
│   ├── api/
│   │   ├── agents/              # Agent API
│   │   │   ├── route.js         # GET /api/agents
│   │   │   └── [id]/chat/route.js
│   │   └── share/               # 分享 API
│   │       ├── route.js         # POST/GET /api/share
│   │       └── [shareId]/route.js
│   └── share/                   # 分享页面
│       ├── layout.js
│       ├── [shareId]/           # 独立分享页
│       └── iframe/[shareId]/    # iframe 嵌入页
├── public/share/
│   └── bubble.js                # 气泡组件脚本
└── config/
    ├── modelConfig.js           # 模型配置
    └── dbConfig.js              # 数据库配置

---

总结

本项目基于 LangChain.js + LangGraph 构建了一套完整的企业级 Agent 框架，具备以下核心能力：

Agent 开发

• • 声明式 Agent 定义（defineAgent），开发者只需关注业务逻辑

• • 通过 MCP 协议无缝集成外部工具服务

• • 支持动态提示词管理，便于运营迭代

执行引擎

• • 后台任务执行器（TaskRunner），客户端断开后仍能完整执行

• • 流式响应（SSE），实时推送 AI 回复和工具调用状态

• • 工具调用全流程追踪（start → running → done）

数据持久化

• • 会话-消息分离设计，支持高效查询

• • 完整的聊天历史记录和会话管理

• • 分享配置和统计数据存储

多端分享

• • 四种分享方式：Web 页面、iframe 嵌入、Bubble 气泡、API 调用

• • 开箱即用的气泡组件，支持拖拽、自定义图标、响应式适配

可观测性

• • 集成 Langfuse 实现 Agent 执行追踪

• • 完整的日志记录和错误处理