Axiom Lattice 客户端 SDK
Axiom Lattice代理服务API的TypeScript客户端.
概览
客户端SDK为与Axiom Lattice Agent Service API的交互提供了简单的接口. 它处理认证、请求/答复格式化和错误处理.
运行时间和范围
此软件包是运行时中立的: 它针对浏览器, 节点 18+, Deno, Bun 和类似 现代JS运行时间. 它只包含HTTP/SSE客户端和协议类型; 反应钩, UI组件和服务器侧业务逻辑存在于其他软件包中.
公共API使用跨运行时间Web标准类型. 文件/存档输入使用 Blob
(浏览器) File 是一个 Blob 子类); SDK 不要求只使用 DOM File 或者说
只节点 node:* 类型。 建构中的节点类型用于测试/工具,而不是
公共合同。 见 docs/architecture/decisions/ADR-260-client-sdk-runtime-neutral.md。 。 。 .
特征
- 创建和管理线索
- 发送信息和接收回复
- 以事件为基础的回调流响应
- 注册客户端工具
- 处理工具呼叫和回复
- 用 ChunkMessageMerger 处理流媒体消息块
- HTTP 客户端标准化, 对所有 API 调用使用 axios
- 通过认证代理 Web App 发布管理
client.webApps
代理网络应用管理
client.webApps 是认证的控制台管理 API,而不是匿名的外部运行时间客户端 。 它规定 list, (中文(简体) ), get, (中文(简体) ), create, (中文(简体) ), update, (中文(简体) ), enable, (中文(简体) ), disable,以及 delete。 。 。 .
import { Client, type CreateAgentWebAppInput } from "@axiom-lattice/client-sdk";
const client = new Client({
baseURL: "http://localhost:4001",
apiKey: "console-session-token",
assistantId: "support-agent",
transport: "sse",
});
const input: CreateAgentWebAppInput = {
assistantId: "support-agent",
name: "Support",
integration: { type: "react_sdk" },
scope: { defaultProjectId: "support", allowedProjectIds: ["support"] },
features: {
projectSelector: false,
modelSelector: false,
threadManagement: true,
attachments: false,
hitl: false,
genUI: false,
},
appearance: { title: "Support assistant" },
};
const publication = await client.webApps.create(input);
await client.webApps.enable(publication.id);
使用 @axiom-lattice/react-sdk/web-app 在外部反应应用程序中。 默认/本地的 SQLite 设置目前使用一个内存的Web App商店,因此发布定义无法从网关重启中幸存; 为持续性配置 PostgreSQL 商店. 见 管理指南。 。 。 .
安装
npm install @axiom-lattice/client-sdk
使用量
import { Client, createSimpleMessageMerger } from "@axiom-lattice/client-sdk";
// Create a client
const client = new Client({
baseURL: "https://api.example.com",
apiKey: "your-api-key",
assistantId: "your-assistant-id",
transport: "sse",
environment: "web", // Optional: "web" (default) or "wechat-miniprogram"
});
// Create a thread
const threadId = await client.createThread({
metadata: { user: "user123" },
});
// Send a message
const response = await client.chat.send({
threadId,
messages: [
{
role: "user",
content: "Hello, how can you help me?",
id: "msg-1",
},
],
});
// Stream a message
const stopStreaming = client.chat.stream(
{
threadId,
messages: [
{
role: "user",
content: "Tell me a story",
id: "msg-2",
},
],
},
(event) => {
console.log("Event:", event);
},
() => {
console.log("Stream completed");
},
(error) => {
console.error("Stream error:", error);
}
);
// Stop streaming if needed
// stopStreaming();
// Use ChunkMessageMerger to process streaming chunks
const merger = createSimpleMessageMerger();
// Process user message
merger.push({
type: "human",
data: {
id: "user-1",
content: "Hello",
},
});
// Process AI message with tool calls
merger.push({
type: "ai",
data: {
id: "ai-1",
content: "I need to search for that.",
tool_calls: [
{
name: "search",
args: { query: "typescript" },
id: "search-1",
},
],
},
});
// Process tool response
merger.push({
type: "tool",
data: {
id: "tool-1",
content: "Search results: ...",
tool_call_id: "search-1",
},
});
// Get merged messages
const messages = merger.getMessages();
移徙说明
运行时环境支持
截至1.0.13版本,客户端SDK现在通过该版本支持不同的运行时环境 environment 配置选项。 目前得到支持的环境有:
"web"(默认):所有HTTP请求都使用axios,包括流式响应"wechat-miniprogram": 使用自定义 WeChat Mini 程序 HTTP 客户端执行来兼容 WeChat Mini 程序
具体说明环境:
const client = new Client({
// ... other options
environment: "wechat-miniprogram", // For WeChat Mini Program environments
});
WeChat Mini 程序环境对流化响应使用不同的方法,因为真正的流化在此环境中得不到支持. 它使用投票机制.
HTTP 客户端标准化
截至1.0.12版本,客户端SDK现在只对所有HTTP请求使用axios,包括流回. 此前,SDK使用Axios组合来进行常规请求,而原生取API来进行流取. 这一变化使整个SDK的HTTP客户端实施标准化.
福利:
- 一致的错误处理
- 统一请求/答复拦截器
- 简化维护和调试
- 更好地兼容不同的 JavaScript 环境
春克麦斯墨尔格Name
这个 ChunkMessageMerger 模块已从网络项目移至客户端-sdk软件包。 它提供了处理流媒体消息块并将其合并为完整消息的功能.
用来:
import { createSimpleMessageMerger } from "@axiom-lattice/client-sdk";
const merger = createSimpleMessageMerger();
// Use merger methods: push, getMessages, reset, etc.
未来的移徙计划
目前的网络项目使用自身的执行 useChat 与网络应用程序的 API 和信件格式紧密结合。 未来,我们计划迁移网络项目 使用反应-sdk's useChat hook,为聊天互动提供了更标准化的界面.
今后移徙的步骤:
- 更新网络项目的信息类型, 以与响应- sdk 的信息格式保持一致
- 用客户端- sdk 方法取代直接 API 调用
- 整合反应- sdk 使用 Chat 钩
- 更新用户界面组件以使用新信件格式
API 参考
客户端
与Axiom Lattice代理服务API互动的主要客户类.
WeChat 客户端
使用本地软件的 WeChat Mini 程序的专门客户端 wx 网络请求的API.
import { WeChatClient } from "@axiom-lattice/client-sdk";
// Create a WeChat client
const client = new WeChatClient({
baseURL: "https://api.example.com",
apiKey: "your-api-key",
assistantId: "your-assistant-id",
transport: "sse",
});
// Use the same API methods as the standard Client
const threadId = await client.createThread({
metadata: { user: "user123" },
});
// Send a message
const response = await client.chat.send({
threadId,
messages: [
{
role: "user",
content: "Hello, how can you help me?",
id: "msg-1",
},
],
});
春克麦斯墨尔格Name
用于处理流媒体消息块并将其合并为完整消息的功能 .
createSimpleMessageMerger(): 创建新消息合并实例push(chunk): 处理信件块getMessages(): 合并所有使用工具调用的信息getMessagesWithoutToolCalls(): 获取没有工具调用的信息initialMessages(msgs): 以现有信件初始化reset(): 重置合并状态