AIOS API SDK

@kmlckj/licos-api-sdk 是 AIOS 已发布能力的纯 API 客户端。它只负责鉴权、HTTP 请求、SSE 事件流、类型和错误处理，不会渲染聊天窗口或创建页面元素。

适合服务端、Node.js 应用及现代浏览器调用。若需要悬浮聊天或嵌入式聊天界面，请使用 @kmlckj/licos-chat-sdk。

安装

npm install @kmlckj/licos-api-sdk

pnpm add @kmlckj/licos-api-sdk

初始化

baseURL 必须是 AIOS 低代码服务的绝对地址，例如 https://aios.example.com/low-code。SDK 会在该地址后拼接已发布 API 的路径。

import { LicosAPI } from "@kmlckj/licos-api-sdk";

const client = new LicosAPI({
  baseURL: "https://aios.example.com/low-code",
  token: "<ACCESS_TOKEN>",
  // workspaceId: "<WORKSPACE_ID>", // 可选，作为 X-Workspace-Id 请求头发送
});

token 也可以是刷新令牌的异步函数：

const client = new LicosAPI({
  baseURL: "https://aios.example.com/low-code",
  token: async () => getFreshAccessToken(),
});

生产环境请由接入方服务端安全地签发和刷新令牌；不要将长期管理员令牌写入浏览器代码。

智能体对话

创建非流式对话

client.chat.create() 返回本次 Chat 的元数据。智能体调用必须提供 bot_id 和接入方定义的稳定 user_id。

const chat = await client.chat.create({
  bot_id: "<BOT_ID>",
  user_id: "visitor_001",
  additional_messages: [{
    role: "user",
    type: "question",
    content_type: "text",
    content: "你好",
  }],
});

console.log(chat.id, chat.conversation_id, chat.status);

消费流式回复

client.chat.stream() 返回 SSE 事件流。调用方可根据 conversation.message.delta 逐步渲染文本，并在 done 事件结束后收尾。

const stream = await client.chat.stream({
  bot_id: "<BOT_ID>",
  user_id: "visitor_001",
  query: "请总结这份报告",
  auto_save_history: true,
});

for await (const event of stream) {
  if (event.event === "conversation.message.delta") {
    process.stdout.write(event.data.content);
  }
}

查询、取消和端侧工具恢复

| 方法 | 作用 | | --- | --- | | client.chat.retrieve({ conversation_id, chat_id }) | 查询一次 Chat 的状态与中断信息。 | | client.chat.messages.list({ conversation_id, chat_id }) | 查询本次 Chat 产生的回答、工具调用等消息。 | | client.chat.cancel({ conversation_id, chat_id }) | 取消进行中的 Chat。 | | client.chat.submitToolOutputs({ conversation_id, chat_id, tool_outputs }) | 非流式提交端侧工具执行结果。 | | client.chat.submitToolOutputsStream(...) | 流式提交端侧工具执行结果，返回 SSE 事件流。 |

const detail = await client.chat.retrieve({
  conversation_id: chat.conversation_id,
  chat_id: chat.id,
});

if (detail.status === "requires_action") {
  await client.chat.submitToolOutputs({
    conversation_id: chat.conversation_id,
    chat_id: chat.id,
    tool_outputs: [{
      tool_call_id: "call_001",
      output: JSON.stringify({ result: "ok" }),
    }],
  });
}

低代码应用会话流

client.workflows.chat() 流式执行已发布会话流。必须提供 workflow_id、非空的 additional_messages、parameters，并且在 app_id 或 bot_id 中二选一。

const stream = await client.workflows.chat({
  workflow_id: "<CHATFLOW_ID>",
  app_id: "<APP_ID>",
  additional_messages: [{
    role: "user",
    type: "question",
    content_type: "text",
    content: "帮我审查这份合同",
  }],
  parameters: {
    locale: "zh-CN",
  },
});

for await (const event of stream) {
  if (event.event === "conversation.message.delta") {
    console.log(event.data.content);
  }
}

文件上传与附件消息

client.files.upload() 调用 AIOS 资产上传接口，将浏览器 File/Blob、ArrayBuffer 或 Uint8Array 上传为可供智能体和会话流读取的资产。单个文件最大 20 MiB。

上传时请传入目标资源，避免资产归属不明确：智能体使用 resource_type: "agent" 与智能体 ID；应用会话流使用 resource_type: "app" 与应用 ID。

const asset = await client.files.upload({
  file: selectedFile,
  asset_type: selectedFile.type.startsWith("image/") ? "image" : "file",
  resource_type: "agent",
  resource_id: "<BOT_ID>",
});

const attachmentUrl = asset.preview_url || asset.url || asset.download_url;

上传结果的 url、preview_url 或 download_url 可直接作为下一个消息附件的 URL。

SDK 提供 createUserMessage() 用于构造文档约定的 additional_messages。附件 URL 必须是 AIOS 运行时可访问的公开地址；可由 client.files.upload() 获取，也可使用接入方既有存储服务的 URL。

import { createUserMessage } from "@kmlckj/licos-api-sdk";

const message = createUserMessage({
  content: "请分析附件",
  attachments: [
    { type: "file", url: "https://files.example.com/contract.pdf", name: "合同.pdf" },
    { type: "image", url: "https://files.example.com/photo.png", name: "图片.png" },
  ],
});

错误处理

HTTP、网络和 AIOS 业务错误会抛出 LicosApiError。错误中保留 HTTP 状态、平台业务码、原始响应和请求地址。

import { LicosApiError } from "@kmlckj/licos-api-sdk";

try {
  await client.chat.create({ bot_id: "<BOT_ID>", user_id: "visitor_001", query: "你好" });
} catch (error) {
  if (error instanceof LicosApiError) {
    console.error(error.status, error.code, error.message);
    console.debug(error.details);
  }
}

API 一览

| 模块 | 方法 | 返回 | | --- | --- | --- | | chat | create | Promise<ChatInfo> | | chat | stream | Promise<AsyncIterable<SseEvent>> | | chat | retrieve | Promise<ChatInfo> | | chat.messages | list | Promise<ChatMessage[]> | | chat | submitToolOutputs | Promise<ChatInfo> | | chat | submitToolOutputsStream | Promise<AsyncIterable<SseEvent>> | | chat | cancel | Promise<ChatInfo> | | workflows | chat | Promise<AsyncIterable<SseEvent>> | | files | upload | Promise<UploadedAsset> | | 工具函数 | createUserMessage | AdditionalMessage |