Chuyển đến nội dung
Imbrace SDK

AI Agent

Trang này bao gồm hai không gian tên AI liên quan:

  • chatAi / chat_ai — tạo và quản lý AI agents, xử lý tài liệu/tệp, và document AI.
  • aiAgent / ai_agent — streaming chat (SSE), quản lý embedding, dữ liệu Parquet, distributed tracing, và Chat Client sub-API.

Tài nguyên AI Agent kết nối đến một dịch vụ chuyên biệt chạy trên một base URL riêng biệt với cổng API chính.

Để biết ví dụ từ đầu đến cuối kết nối các tính năng này, xem Hướng dẫn toàn diện §1.

import { ImbraceClient } from "@imbrace/sdk"


const client = new ImbraceClient({
  accessToken: process.env.IMBRACE_ACCESS_TOKEN,
  env: "stable",
})
 
import { ImbraceClient } from "@imbrace/sdk"


const client = new ImbraceClient({
  apiKey: process.env.IMBRACE_API_KEY,
  organizationId: process.env.IMBRACE_ORGANIZATION_ID,
  env: "stable",
})

Cả client đồng bộ (ImbraceClient) và bất đồng bộ (AsyncImbraceClient) đều hiển thị cùng bề mặt — các phương thức bất đồng bộ được await và client sử dụng AsyncAiAgentResource bên dưới.

AI Agents — chatAi / chat_ai

Quản lý AI agents (CRUD), chạy completions tương thích OpenAI, và xử lý tài liệu/tệp. Cùng không gian tên này cũng bao gồm Knowledge Hub folders và knowledge bases.

CRUD AI Agent

// Liệt kê tất cả AI agents trong tài khoản của bạn
const agents = await client.chatAi.listAiAgents();
// Mỗi AI agent có một `id` (UUID).
// Sử dụng trường `id` cho tất cả các lời gọi tiếp theo.


// Liệt kê sub-agents (các agent có thể được ủy quyền bởi orchestrator)
const subAgents = await client.chatAi.listAiAgentSubAgents();


// Lấy một AI agent
const agent = await client.chatAi.getAiAgent("9f77692f-33d0-436a-8138-2efb268838e6");


// Tạo — provider_id và model_id là bắt buộc
const created = await client.chatAi.createAiAgent({
  name: "Support Bot",
  workflow_name: "support_bot_v1",
  provider_id: "system",
  model_id: "Default",   // tên model cụ thể như "gpt-4o" chỉ hoạt động nếu nhà cung cấp system của tổ chức có model đó
  streaming: true,       // phải bật để chat UI nhận text-delta SSE events
  description: "Handles tier-1 support queries",
});


// Cập nhật — tất cả các trường đều tùy chọn (Partial)
const updated = await client.chatAi.updateAiAgent(created.id, {
  name: "Support Bot v2",
  workflow_name: "support_bot_v1",
});


// Chỉ cập nhật system instructions
await client.chatAi.updateAiAgentInstructions(
  created.id,
  "You are a helpful support agent.",
);


await client.chatAi.deleteAiAgent(created.id);

Completions (qua client.ai)

Chat completions tương thích OpenAI có sẵn trên namespace client.ai cho cả TypeScript và Python. Xem phần Dịch vụ AI tương thích OpenAI bên dưới để biết chi tiết.

const response = await client.ai.complete({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are a helpful CRM assistant." },
    { role: "user", content: "Summarize this customer note: ..." },
  ],
});
console.log(response.choices[0].message.content);

Document AI models

const models = await client.chatAi.listDocumentModels();

Document AI

Trích xuất dữ liệu có cấu trúc từ PDF và hình ảnh bằng vision model. Xem tài liệu tham khảo Document AI để biết tham số đầy đủ, điền form PDF và cách sử dụng bất đồng bộ.

Trích xuất tệp (tải tệp lên agent)

Tải tệp lên và trích xuất nội dung thô.

// Tải tệp lên agent cụ thể
const formData = new FormData();
formData.append("file", fileBuffer, "report.pdf");
const uploaded = await client.chatAi.uploadAgentFile(formData);


// Trích xuất nội dung từ tệp đã tải lên
const extracted = await client.chatAi.extractFile(formData);

Phiên Chat v1

Các endpoint REST chat cũ để duy trì lịch sử hội thoại. Có sẵn trên client.ai_agent cho cả TypeScript và Python. Xem Legacy v1 chat bên dưới.

Knowledge Hub — thư mục & knowledge bases

Thư mục và knowledge bases được quản lý qua client.boards (TypeScript) / client.folders và client.boards (Python). Thư mục tổ chức knowledge bases — một knowledge base là tập hợp các tệp mà AI agent có thể truy xuất. Truyền ID thư mục dưới dạng folder_ids khi tạo AI agent — xem Hướng dẫn toàn diện §3.

import { type CreateFolderInput } from "@imbrace/sdk";


// Thư mục
const folders = await client.boards.searchFolders({ organizationId: "org_xxx" });
const folder  = await client.boards.createFolder({ name: "Q1 Reports" });
await client.boards.updateFolder(folder._id, { name: "Q1 2025 Reports" });
await client.boards.deleteFolders({ ids: [folder._id] });


// Tệp (mục knowledge base)
const uploaded = await client.boards.uploadFile(formData);
const files    = await client.boards.searchFiles({ folderId: folder._id });
const file     = await client.boards.getFile("file_id");
await client.boards.createFile({ name: "doc.txt", folder_id: folder._id });
await client.boards.deleteFiles({ ids: ["file_id"] });

Dịch vụ AI tương thích OpenAI — client.ai

Completions, streaming và embeddings theo phong cách OpenAI. Cũng hiển thị API quản lý cho LLM models, providers, guardrails, RAG files, và AI agents. Có sẵn cho cả TypeScript và Python.

// Completion đơn lẻ
const response = await client.ai.complete({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are a helpful CRM assistant." },
    { role: "user",   content: "Summarize this customer note: ..." },
  ],
  temperature: 0.7,
});
console.log(response.choices[0].message.content);


// Streaming
const stream = client.ai.stream({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Draft a follow-up email for this lead." }],
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0].delta.content ?? "");
}


// Embeddings
const result = await client.ai.embed({
  model: "text-embedding-ada-002",
  input: ["customer complained about billing", "billing issue escalated"],
});

LLM Models

Liệt kê các model có sẵn cho AI agents và workflow agents.

const result = await client.ai.getLlmModels();
// result.data → [{name, is_toolCall_available, is_vision_available, is_support_thinking}]
for (const model of result.data) {
  console.log(model.name, model.is_toolCall_available);
}

Providers

Quản lý các nhà cung cấp LLM tùy chỉnh. listProviders bao gồm một mục "system" tổng hợp (provider_id: "system") đại diện cho các model tích hợp sẵn từ getLlmModels.

// Liệt kê tất cả providers (bao gồm mặc định hệ thống là mục đầu tiên)
const providers = await client.ai.listProviders();
// Chỉ providers tùy chỉnh
const custom = await client.ai.listProviders({ includeSystem: false });


// Thêm provider tùy chỉnh
const provider = await client.ai.createProvider({
  name: "My Azure OpenAI",
  type: "azure",
  api_key: "sk-...",
  base_url: "https://my-instance.openai.azure.com/",
});


// Cập nhật, làm mới model, xóa
await client.ai.updateProvider(provider._id, { name: "Azure OpenAI (prod)" });
await client.ai.refreshProviderModels(provider._id);
await client.ai.deleteProvider(provider._id);

Guardrails

Lọc đầu ra AI agent vì lý do an toàn, tuân thủ chính sách, hoặc hướng dẫn thương hiệu.

// Liệt kê và lấy
const guardrails = await client.ai.listGuardrails();
const guardrail  = await client.ai.getGuardrail("guardrail_id");


// Tạo
const created = await client.ai.createGuardrail({
  name: "Brand Safety",
  model: "gpt-4o",
  instructions: "Block responses that mention competitor names.",
  unsafe_categories: ["violence", "hate_speech"],
  competitor_keywords: ["CompetitorA", "CompetitorB"],
});


// Cập nhật và xóa
await client.ai.updateGuardrail(created._id, {
  name: "Brand Safety v2",
  model: "gpt-4o",
  instructions: "Updated instructions.",
});
await client.ai.deleteGuardrail(created._id);

Guardrail Providers

Quản lý các nhà cung cấp LLM hỗ trợ đánh giá guardrail.

// Liệt kê và lấy
const providers = await client.ai.listGuardrailProviders();
const provider  = await client.ai.getGuardrailProvider("provider_id");


// Tạo
const gp = await client.ai.createGuardrailProvider({
  name: "OpenAI Moderation",
  type: "openai",
  config: { api_key: "sk-..." },
});


// Kiểm tra kết nối và liệt kê model có sẵn
const testResult = await client.ai.testGuardrailProvider(gp._id, { prompt: "test prompt" });
const models     = await client.ai.getGuardrailProviderModels(gp._id);


// Cập nhật và xóa
await client.ai.updateGuardrailProvider(gp._id, { name: "OpenAI Moderation v2" });
await client.ai.deleteGuardrailProvider(gp._id);

RAG Files

Tải lên và quản lý tệp cho Retrieval-Augmented Generation qua dịch vụ AI.

const files = await client.ai.listRagFiles();
const file  = await client.ai.getRagFile("file_id");


// Tải lên
const formData = new FormData();
formData.append("file", fileBuffer, "knowledge.pdf");
const uploaded = await client.ai.uploadRagFile(formData);


await client.ai.deleteRagFile(uploaded._id);

AI Agents (qua client.ai)

Các endpoint đọc/cập nhật AI agent bổ sung trên namespace client.ai. Để CRUD tạo/xóa đầy đủ, sử dụng client.chatAi ở trên.

// Liệt kê agent từ endpoint accounts
const accountAgents = await client.ai.listAiAgents();
// Liệt kê agent (endpoint agents)
const agents = await client.ai.listAgents();


// Lấy một agent
const agent = await client.ai.getAiAgent("asst_abc");


// Kiểm tra tên có sẵn trước khi tạo
const check = await client.ai.checkAiAgentName("Support Bot");
// check.available → true / false


// Patch chỉ trường instructions
await client.ai.patchInstructions("asst_abc", {
  instructions: "You are a concise, helpful assistant.",
});

AI Agent Apps (qua client.ai)

AI Agent Apps liên kết AI agent với cấu hình workflow hoặc ứng dụng.

// Tạo
const app = await client.ai.createAiAgentApp({
  name: "Support App",
  workflow_name: "support_workflow_v1",
  assistant_id: "asst_abc",
  model_id: "Default",   // an toàn cho mọi tổ chức; "gpt-4o" chỉ hoạt động nếu nhà cung cấp system của tổ chức có model đó
  provider_id: "system",
});


// Cập nhật và xóa
await client.ai.updateAiAgentApp(app._id, { name: "Support App v2" });
await client.ai.deleteAiAgentApp(app._id);


// Chỉ cập nhật định nghĩa workflow
await client.ai.updateAiAgentWorkflow(app._id, {
  workflow: { steps: [{ id: "step1", type: "llm" }] },
});

Tool Server

Xác minh rằng URL máy chủ công cụ tùy chỉnh có thể truy cập được và trả về schema công cụ hợp lệ.

const result = await client.ai.verifyToolServer({ url: "https://my-tools.example.com/mcp" });
if (result.success) {
  console.log("Available tools:", result.tools);
}

Chat v2 — Streaming (SSE)

Trả về phản hồi thô. Tiêu thụ body dưới dạng luồng Server-Sent Events.

const response = await client.aiAgent.streamChat({
  id: "chat_id",
  assistant_id: "asst_abc",
  messages: [{ role: "user", content: "What can you do?" }],
});


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));
}

Sub-agent Chat v2

Stream phản hồi từ sub-agent và truy xuất lịch sử hội thoại của nó.

const res = await client.aiAgent.streamSubAgentChat({
  assistant_id: "asst_sub",
  session_id: "sess_xyz",
  chat_id: "chat_id",
  messages: [{ role: "user", content: "Explain the data." }],
});


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

Đề xuất Prompt

Lấy các đề xuất prompt được xây dựng sẵn cho một AI agent cụ thể.

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

Embeddings & Knowledge Base

Quản lý tệp được sử dụng cho Retrieval-Augmented Generation (RAG). Tải tệp lên trước qua client.boards.uploadFile (TypeScript) / client.boards.upload_file (Python), sau đó kích hoạt xử lý embedding.

// Kích hoạt xử lý embedding cho tệp đã tải lên
await client.aiAgent.processEmbedding({ fileId: "file_abc" });


// Liệt kê và kiểm tra tệp 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" });


// Cập nhật trạng thái và xóa
await client.aiAgent.updateEmbeddingFileStatus("file_abc", "active");
await client.aiAgent.deleteEmbeddingFile("file_abc");


// Phân loại tệp cho RAG
const classification = await client.aiAgent.classifyFile({ file_id: "file_abc" });

Data Board

Đề xuất loại trường có hỗ trợ AI cho các tập dữ liệu có cấu trúc.

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

Tạo và quản lý tệp dữ liệu cột Parquet cho các pipeline phân tích.

// Tạo tệp Parquet từ dữ liệu JSON
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");

Distributed Tracing (Tempo)

Truy vấn các trace Grafana Tempo do dịch vụ AI Agent phát ra để quan sát và gỡ lỗi.

// Liệt kê trace gần đây
const traces = await client.aiAgent.getTraces({
  service:   "ai-agent",
  limit:     50,
  timeRange: 3600,     // giây
  orgId:     "org_abc",
  details:   true,
});


// Kiểm tra một trace
const trace = await client.aiAgent.getTrace("trace_id_hex");


// Liệt kê services, tags, và tag values
const services = await client.aiAgent.getTraceServices();
const tags     = await client.aiAgent.getTraceTags();
const values   = await client.aiAgent.getTraceTagValues("http.status_code");


// Tìm kiếm TraceQL
const results = await client.aiAgent.searchTraceQL(
  `{ .service.name = "ai-agent" && .http.status = 500 }`
);

Chat Client

Chat Client sub-API hỗ trợ các ứng dụng frontend (ví dụ: widget chat nhúng). Để biết cách kết nối ở cấp framework (React singleton, Express auth proxy, v.v.), xem Tích hợp.

Xác thực

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" });

Chats

// Tạo phiên chat mới
await client.aiAgent.createClientChat({
  id:                     "chat_uuid",
  assistantId:            "asst_abc",
  organizationId:         "org_abc",
  userId:                 "user_xxx",
  selectedVisibilityType: "private",
  message: {
    id:        "msg_uuid",
    role:      "user",
    content:   "Hello!",
    createdAt: new Date().toISOString(),
    parts:     [{ type: "text", text: "Hello!" }],
  },
});


// Liệt kê, đọc, cập nhật, xóa chats
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" });


// Tự động tạo tiêu đề cho chat
await client.aiAgent.generateClientChatTitle("chat_id");


// Stream trạng thái chat thời gian thực dưới dạng SSE — trả về Response thô
const statusStream = await client.aiAgent.streamClientChatStatus("chat_id");

Tin nhắn

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

Bình chọn

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

Documents (các tạo phẩm do AI tạo ra)

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


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");

Thông tin dịch vụ

Các endpoint tiện ích để kiểm tra trạng thái và phiên bản của dịch vụ AI Agent.

const config  = await client.aiAgent.getConfig();
const health  = await client.aiAgent.getHealth();          // tóm tắt
const details = await client.aiAgent.getHealth(true);      // chi tiết
const version = await client.aiAgent.getVersion();

Hướng dẫn Quản trị

Truy cập tài liệu quản trị được lưu trữ bởi dịch vụ AI Agent. Các tệp hướng dẫn được trả về dưới dạng luồng nhị phân thô (thường là PDF).

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


// Tải xuống một hướng dẫn cụ thể — trả về Response thô (luồng PDF)
const response = await client.aiAgent.getAdminGuide("onboarding.pdf");
const blob = await response.blob();

Chat v1 cũ

Các endpoint REST chat gốc duy trì lịch sử hội thoại mà không có streaming. Mã mới nên sử dụng Chat v2 streaming ở trên; v1 tồn tại để tương thích ngược với các chat hiện có.

// Liệt kê chats cho một tổ chức
const chats = await client.aiAgent.listChats({
  organization_id: "org_abc",
  user_id: "user_123",
  limit: 20,
});


// Lấy một chat (truyền true để bao gồm tin nhắn)
const chat = await client.aiAgent.getChat("chat_id", true);


// Xóa một chat
await client.aiAgent.deleteChat("chat_id", {
  organization_id: "org_abc",
  user_id: "user_123",
});