跳到內容
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",
});