开发接口
数字专家提供了一组 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.mtda.cloud/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 功能保存会话关键数据,增强智能体的记忆能力。
参考
更多信息
SDK 还在不断完善中,如有遇到问题或有建议,请加微信:xpertai 联系我们进行技术交流。