开发接口

数字专家提供了一组 API 及 SDK 用于开发者与专家智智能体进行交互。这些 API 使您可以创建自定义应用程序，以便与数字专家的智能体进行通信。 Xpert 智能体接口遵循 Agent Protocol 标准，这是一种用于智能体之间通信的协议。Agent Protocol 为智能体提供了一种通用的方式来交换消息，以便于智能体之间的互操作性。

首选为访问专家智能体的程序创建一个 Key，用于身份验证。

使用 Key 访问专家智能体的 Rest APIs，或者使用 LangGraph SDK 访问 XpertAI 平台。

使用 LangGraph SDK 调用 XpertAI 平台

XpertAI 智能体平台，可通过 LangGraph SDK （@langchain/langgraph-sdk（JS/TS SDK） / langgraph-sdk Python SDK）与其交互。该 SDK 封装了与 LangGraph REST API 通信的核心能力，可以方便地管理助手 (assistants)、线程 (threads)、运行 (runs)、持久存储 (store) 等核心组件。

参考代码 XpertAI SDK 示例

1. 安装

确保已经安装 Node.js 环境，然后在项目中安装 SDK：

# 使用 yarn 安装
yarn add @langchain/langgraph-sdk
# 或使用 npm
npm install @langchain/langgraph-sdk

SDK 默认会连接到 http://localhost:8123（如使用 langgraph-cli 本地启动）；否则需在配置时指定 API URL 或 apiKey (npm)。

2. 初始化客户端

在 JavaScript/TypeScript 中，可以这样创建一个 Client 实例：

import { Client } from "@langchain/langgraph-sdk";

const client = new Client({
  apiUrl: "https://api.xpertai.cn/api/ai/", // Your baseUrl of XpertAI server.
  apiKey: "your-api-key", // API Key of xpert
})

如未显式配置，SDK 会默认连接到本地 http://localhost:8123 (npm)。

3. 管理数字专家（智能体）

列出已有数字专家

import { Client, Assistant } from "@langchain/langgraph-sdk";

// List all xperts
const xperts: Assistant[] = await client.assistants.search({
  metadata: null,
  offset: 0,
  limit: 10,
})
console.log("Experts:", xperts);

每个数字专家就是一个 assistant (npm, LangGraph)。

获取单个数字专家

const xpert = await client.assistants.get(xpertId);

4. 创建与管理 Threads（线程）

创建新线程（空状态）

const thread = await client.threads.create(); // 或传入 threadId、metadata 等初始化参数
console.log("New Thread:", thread);

示例中，返回包含 thread_id、status 等属性 (LangGraph)。

预填充状态

const threadWithState = await client.threads.create({
  threadId: "xxxxxxx",
  ifExists: 'raise'
});

这样可在创建时直接注入线程ID (LangGraph)。

查询线程列表 & 获取状态

const list = await client.threads.search({ limit: 10, offset: 0 });
const singleThread = await client.threads.get(thread.thread_id);
const history = await client.threads.getHistory(thread.thread_id, { limit: 50 });

5. 启动运行（Runs）

可以发起对某个数字专家在线程中的运行，包括支持流式返回。

启动流式返回的运行

const stream = client.runs.stream(thread.thread_id, assistant.assistant_id, {
  input: { 
    input: "Tell me a joke.", // more parameters 
  },
});
for await (const chunk of streamResponse) {
  const data = (<{ type: 'message', data: string | {type: 'text' | string; text?: string; data?: any} }>chunk.data)
  // Output text messages only
  if (data.type === 'message') {
    if (typeof data.data === 'string') {
      process.stdout.write(data.data)
    } else if (data.data.type === 'text') {
      process.stdout.write(data.data.text ?? '')
    } else {
      // console.log(`Component:`, data.data);
    }
  }
}

这样可边生成边处理响应，适合交互式场景 (npm)。

其他运行操作示例

const run = await client.runs.create(thread.thread_id, assistant.assistant_id, { input: { ... } });
const result = await client.runs.join(thread.thread_id, run.run_id);
await client.runs.cancel(thread.thread_id, run.run_id);
const runsList = await client.runs.list(thread.thread_id, { limit: 10 });

6. 使用 Store（持久存储）

存储会话中或任务中需要跨请求保存的数据。

// 写入
await client.store.putItem([xpert_id], "key1", { value: 42 });

// 读取
const item = await client.store.getItem([xpert_id], "key1");

// 列出命名空间
const namespaces = await client.store.listNamespaces({
  prefix: [xpert_id],
  maxDepth: 2,
  limit: 10
});

// 搜索
const found = await client.store.searchItems({ namespacePrefix: "my", query: "42" });

详细接口如 StoreClient 所定义 (LangGraph)。

7. XpertAI 平台集成 Tips

配置默认 API 地址与密钥：API 地址需要显式指定，密钥可使用环境变量 LANGGRAPH_API_KEY 统一配置。
Stream 输出到前端：适用 React 等前端，可以通过 SDK 的流式能力构建实时对话界面。
持久记忆：通过 Store 功能保存会话关键数据，增强智能体的记忆能力。

默认

沙箱

使用 LangGraph SDK 调用 XpertAI 平台

1. 安装

2. 初始化客户端

3. 管理数字专家（智能体）

列出已有数字专家

获取单个数字专家

4. 创建与管理 Threads（线程）

创建新线程（空状态）

预填充状态

查询线程列表 & 获取状态

5. 启动运行（Runs）

启动流式返回的运行

其他运行操作示例

6. 使用 Store（持久存储）

7. XpertAI 平台集成 Tips

参考

更多信息

默认

沙箱

​使用 LangGraph SDK 调用 XpertAI 平台

​1. 安装

​2. 初始化客户端

​3. 管理数字专家（智能体）

​列出已有数字专家

​获取单个数字专家

​4. 创建与管理 Threads（线程）

​创建新线程（空状态）

​预填充状态

​查询线程列表 & 获取状态

​5. 启动运行（Runs）

​启动流式返回的运行

​其他运行操作示例

​6. 使用 Store（持久存储）

​7. XpertAI 平台集成 Tips

​参考

​更多信息

使用 LangGraph SDK 调用 XpertAI 平台

1. 安装

2. 初始化客户端

3. 管理数字专家（智能体）

列出已有数字专家

获取单个数字专家

4. 创建与管理 Threads（线程）

创建新线程（空状态）

预填充状态

查询线程列表 & 获取状态

5. 启动运行（Runs）

启动流式返回的运行

其他运行操作示例

6. 使用 Store（持久存储）

7. XpertAI 平台集成 Tips

参考

更多信息