@vegintech/langchain-react-agent

一个用于 React 的 LangChain Agent UI 组件库，基于 Ant Design X 构建，提供开箱即用的智能对话界面。

特性

• 🚀 基于 LangChain - 与 LangChain 生态无缝集成，支持 LangGraph 后端
• 💬 流式消息 - 内置流式响应支持，实时显示 AI 回复
• 🛠️ 工具调用 - 支持前端工具和后端工具的定义与执行
• 🎨 Ant Design X - 基于 Ant Design X 组件，提供优秀的视觉体验
• 🔧 高度可定制 - 灵活的配置选项，支持自定义消息渲染和输入框行为
• 📱 响应式设计 - 适配各种屏幕尺寸

安装

npm install @vegintech/langchain-react-agent
# 或
yarn add @vegintech/langchain-react-agent
# 或
pnpm add @vegintech/langchain-react-agent

对等依赖

确保你的项目已安装以下依赖：

npm install react react-dom @langchain/react

快速开始

import { AgentChat } from "@vegintech/langchain-react-agent";

function App() {
  return (
    <AgentChat
      apiUrl="http://localhost:2024"
      assistantId="my-assistant"
      onThreadIdChange={(threadId) => {
        console.log("New thread:", threadId);
      }}
    />
  );
}

组件

AgentChat

核心聊天组件，封装了消息列表、输入框和工具管理功能。

import { AgentChat } from "@vegintech/langchain-react-agent";

<AgentChat
  // 连接配置
  apiUrl="https://api.example.com"
  assistantId="your-assistant-id"
  threadId={threadId} // 可选：会话 ID
  headers={{ Authorization: "Bearer token" }} // 可选：自定义请求头
  onThreadIdChange={(id) => setThreadId(id)} // 可选：会话 ID 变化回调
  // 工具配置
  tools={[frontendTool, backendTool]} // 可选：工具定义数组
  // 上下文
  contexts={[{ description: "用户信息", value: "用户ID: 123" }]} // 可选
  // 消息渲染配置
  messageConfig={{
    components: {
      /* 自定义 Markdown 组件 */
    },
    allowedTags: { div: ["class"] },
  }}
  // 输入框配置
  inputConfig={{
    placeholder: "请输入消息...",
    onPreSend: (params) => ({
      messages: [{ type: "human", content: params.message }],
    }),
  }}
  // 错误处理
  onError={(error) => console.error(error)}
/>;

工具定义

前端工具

前端工具在浏览器端执行，适用于需要访问浏览器 API 或不需要后端处理的场景。

import type { FrontendTool } from "@vegintech/langchain-react-agent";

const alertTool: FrontendTool = {
  type: "frontend",
  name: "alert",
  description: "显示一个警告弹窗",
  parameters: {
    type: "object",
    properties: {
      message: { type: "string", description: "警告消息内容" },
    },
    required: ["message"],
  },
  execute: async (args) => {
    alert(args.message);
    return { success: true };
  },
  render: (props) => (
    <div className="tool-alert">{props.status === "running" ? "显示弹窗中..." : "弹窗已显示"}</div>
  ),
};

后端工具

后端工具由 LangChain Agent 在后端执行，适用于需要访问数据库、API 等后端资源的场景。

import type { BackendTool } from "@vegintech/langchain-react-agent";

const searchTool: BackendTool = {
  type: "backend",
  name: "search",
  description: "搜索知识库",
  parameters: {
    type: "object",
    properties: {
      query: { type: "string", description: "搜索关键词" },
    },
    required: ["query"],
  },
  render: (props) => (
    <div className="tool-search">
      {props.status === "pending" && "等待执行..."}
      {props.status === "running" && `搜索: ${props.args.query}`}
      {props.status === "success" && `找到 ${props.result?.count || 0} 条结果`}
    </div>
  ),
};

API 参考

AgentChat Props

| 属性 | 类型 | 必填 | 说明 | | ---------------- | ------------------------------------------- | ---- | ------------------------- | | apiUrl | string | 是 | LangGraph API 地址 | | assistantId | string | 是 | 助手 ID | | threadId | string | 否 | 会话 ID，不传则创建新会话 | | headers | Record<string, string | undefined | null> | 否 | 自定义请求头 | | onThreadIdChange | (threadId: string) => void | 否 | 会话 ID 变化回调 | | className | string | 否 | 自定义 CSS 类名 | | tools | ToolDefinition[] | 否 | 工具定义数组 | | contexts | ContextItem[] | 否 | 上下文信息数组 | | messageConfig | MessageConfig | 否 | 消息渲染配置 | | inputConfig | InputConfig | 否 | 输入框配置 | | onError | (error: Error) => void | 否 | 错误处理回调 |

类型定义

import type {
  AgentChatProps,
  AgentChatRef,
  FrontendTool,
  BackendTool,
  ToolDefinition,
  ChatMessage,
  ContextItem,
  MessageConfig,
  InputConfig,
} from "@vegintech/langchain-react-agent";