跳转到内容
Imbrace SDK

AI Agent

client.aiAgent / client.ai_agent 连接到独立的 AI Agent 服务，运行在与主 API gateway 不同的 base URL 上。该资源提供流式聊天、embedding knowledge base 管理、列式数据（Parquet）、分布式追踪（Tempo），以及前端应用使用的完整 Chat Client 子 API。

端到端 streamChat 示例，参阅完整流程指南 §1。

import { ImbraceClient } from "@imbrace/sdk";
const client = new ImbraceClient();

Chat v2 — 流式传输（SSE）

返回原始 response。将 body 作为 Server-Sent Events 流消费。

const response = await client.aiAgent.streamChat({
  id: "chat_id",
  assistant_id: "asst_abc",
  organization_id: "org_abc",
  messages: [{ role: "user", content: "您能做什么？" }],
});


const reader = response.body!.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

子 Agent 聊天 v2

从子 agent 流式获取响应并获取其对话历史。

const res = await client.aiAgent.streamSubAgentChat({
  assistant_id: "asst_sub",
  organization_id: "org_abc",
  session_id: "sess_xyz",
  chat_id: "chat_id",
  messages: [{ role: "user", content: "解释这些数据。" }],
});


const history = await client.aiAgent.getSubAgentHistory({
  session_id: "sess_xyz",
  chat_id: "chat_id",
});

提示建议

获取助手的建议提示列表。

const suggestions = await client.aiAgent.getAgentPromptSuggestion("asst_abc");

Embeddings & Knowledge Base

管理用于检索增强生成（RAG）的文件。先通过 client.boards.uploadFile 上传文件，再触发 embedding 处理。

// 触发已上传文件的 embedding 处理
await client.aiAgent.processEmbedding({ fileId: "file_abc" });


// 列出和检查 embedding 文件
const files   = await client.aiAgent.listEmbeddingFiles({ page: 1, limit: 20 });
const file    = await client.aiAgent.getEmbeddingFile("file_abc");
const preview = await client.aiAgent.previewEmbeddingFile({ file_id: "file_abc" });


// 更新状态和删除
await client.aiAgent.updateEmbeddingFileStatus("file_abc", "active");
await client.aiAgent.deleteEmbeddingFile("file_abc");


// 为 RAG 分类文件
const classification = await client.aiAgent.classifyFile({ file_id: "file_abc" });

数据看板

为结构化数据集使用 AI 建议字段类型。

const result = await client.aiAgent.suggestFieldTypes({
  fields: [
    { name: "created_at", samples: ["2024-01-01", "2024-02-15"] },
    { name: "amount",     samples: [100, 200.5, 999] },
    { name: "is_active",  samples: [true, false, true] },
  ],
});
// result.fields[i].suggestedType → "datetime" | "number" | "boolean" | ...

Parquet

为分析管道创建和管理列式 Parquet 数据文件。

// 从 JSON 数据创建 Parquet 文件
const result = await client.aiAgent.generateParquet({
  data: [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }],
  fileName: "users",
  folderName: "exports",
});


const files = await client.aiAgent.listParquetFiles();
await client.aiAgent.deleteParquetFile("exports/users.parquet");

分布式追踪（Tempo）

从 AI Agent 服务查询 Grafana Tempo traces 以进行观测和调试。

// 列出最近的 traces
const traces = await client.aiAgent.getTraces({
  service:   "ai-agent",
  limit:     50,
  timeRange: 3600,     // 秒
  orgId:     "org_abc",
  details:   true,
});


// 查看单个 trace 详情
const trace = await client.aiAgent.getTrace("trace_id_hex");


// 列出 services、tags 和 tag 值
const services = await client.aiAgent.getTraceServices();
const tags     = await client.aiAgent.getTraceTags();
const values   = await client.aiAgent.getTraceTagValues("http.status_code");


// 使用 TraceQL 搜索
const results = await client.aiAgent.searchTraceQL(
  `{ .service.name = "ai-agent" && .http.status = 500 }`
);

Chat Client

Chat Client 子 API 为前端应用（如嵌入式聊天 widget）提供服务。框架级接线参阅集成。

认证

await client.aiAgent.verifyChatClientCredentials({ token: "tok_xxx" });
await client.aiAgent.registerChatClient({ name: "web-app", secret: "s3cr3t" });
const user = await client.aiAgent.getChatClientUser({ token: "tok_xxx" });

聊天

// 创建新聊天会话
await client.aiAgent.createClientChat({
  id: "chat_uuid",
  message: {
    id: "msg_uuid",
    role: "user",
    parts: [{ type: "text", text: "您好！" }],
  },
  assistantId:    "asst_abc",
  organizationId: "org_abc",
});


// 列出、读取、更新、删除
const chats = await client.aiAgent.listClientChats({
  organization_id: "org_abc",
  limit: 20,
});
const chat = await client.aiAgent.getClientChat("chat_id");
await client.aiAgent.updateClientChat("chat_id", { visibility: "private" });
await client.aiAgent.deleteClientChat("chat_id");
await client.aiAgent.deleteAllClientChats({ organization_id: "org_abc" });


// 自动生成聊天标题
await client.aiAgent.generateClientChatTitle("chat_id");


// 以 SSE 方式流式传输实时聊天状态 — 返回原始 Response
const statusStream = await client.aiAgent.streamClientChatStatus("chat_id");

消息

await client.aiAgent.persistClientMessage({ chatId: "chat_id", content: "您好" });
const messages = await client.aiAgent.listClientMessages("chat_id");
await client.aiAgent.deleteTrailingMessages("message_id");

投票

const votes = await client.aiAgent.getVotes("chat_id");
await client.aiAgent.updateVote({ messageId: "msg_id", vote: "up" });

文档（AI 生成的制品）

await client.aiAgent.createDocument({ kind: "text", content: "草稿..." });


const doc        = await client.aiAgent.getDocument("doc_id");
const latest     = await client.aiAgent.getDocumentLatest("doc_id");
const pub        = await client.aiAgent.getDocumentPublic("doc_id");
const byKind     = await client.aiAgent.getDocumentLatestByKind({ kind: "text" });
const suggestion = await client.aiAgent.getDocumentSuggestions("doc_id");


await client.aiAgent.deleteDocument("doc_id");

管理员指南

访问由 AI Agent 服务存储的管理员文档。指南文件以原始二进制流形式返回（通常是 PDF）。

const guides = await client.aiAgent.listAdminGuides();


// 下载特定指南 — 返回原始 Response（PDF 流）
const response = await client.aiAgent.getAdminGuide("onboarding.pdf");
const blob = await response.blob();

旧版 v1 聊天

原始 REST 聊天接口，无需流式传输即可保留对话历史。新代码应使用上方的 Chat v2 流式传输；v1 保留用于向后兼容。

// 列出某组织的聊天记录
const chats = await client.aiAgent.listChats({
  organization_id: "org_abc",
  user_id: "user_123",
  limit: 20,
});


// 获取单个聊天（传 true 以包含消息）
const chat = await client.aiAgent.getChat("chat_id", true);


// 删除聊天
await client.aiAgent.deleteChat("chat_id", {
  organization_id: "org_abc",
  user_id: "user_123",
});