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

Hướng dẫn toàn diện

Hướng dẫn này đi qua bốn quy trình làm việc chính trong Imbrace SDK từ đầu đến cuối. Mỗi phần là độc lập — hãy theo thứ tự hoặc nhảy đến phần bạn cần.

1. Tạo AI Agent và Bắt đầu Chat

  1. Khởi tạo client

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

  2. Tạo AI agent

    workflow_name phải là duy nhất trong tổ chức của bạn.

    const agent = await client.chatAi.createAiAgent({
      name: "Support Bot",
      workflow_name: "support_bot_v1",
      description: "Handles tier-1 customer support queries",
      instructions: "You are a helpful support agent. Be concise and friendly.",
      provider_id: "default",   // sử dụng nhà cung cấp LLM mặc định của tổ chức
      model_id: "Default",     // định tuyến tới model mặc định đã cấu hình của tổ chức
      streaming: true,         // phát các sự kiện SSE text-delta (xem Aside bên dưới)
    })
    

    const aiAgentId = agent.id  // UUID — sử dụng cho tất cả các lời gọi tiếp theo
    console.log("AI agent created:", aiAgentId)

    provider_id và model_id là tùy chọn — SDK tự điền { provider_id: "default", model_id: "Default" } khi bỏ trống. "Default" gắn với bất kỳ model nào mà tổ chức cấu hình làm mặc định và là lựa chọn an toàn cho mọi tổ chức. Truyền tường minh để ghi đè: provider_id: "<uuid>" để gắn nhà cung cấp LLM tùy chỉnh, hoặc model_id: "gpt-4o" v.v. — nhưng tên model cụ thể chỉ hoạt động nếu nhà cung cấp default của tổ chức thực sự có model đó. Liệt kê các model của tổ chức bằng client.ai.listModels() (TypeScript) / client.ai.list_models() (Python) trước khi hardcode.

  3. Stream phản hồi chat bằng AI agent

    Dùng streamChatText / stream_chat_text — helper này bao bọc streamChat, phân tích luồng sự kiện SSE và trả về từng đoạn văn bản thuần. Giả định agent đã được tạo với streaming: true (xem Aside ở bước 2).

    for await (const chunk of client.aiAgent.streamChatText({
      assistant_id: aiAgentId,
      messages: [{ role: "user", content: "How do I reset my password?" }],
      // id là UUID phiên — tái sử dụng để duy trì lịch sử hội thoại.
      // Nếu bỏ qua, UUID mới sẽ được tự động tạo mỗi lần gọi.
    })) {
      process.stdout.write(chunk)
    }

  4. Duy trì lịch sử hội thoại (session ID)

    Truyền cùng id (phải là UUID) qua các lời gọi để giữ ngữ cảnh:

    import { randomUUID } from "crypto"
    

    const sessionId = randomUUID()
    

    // Tin nhắn đầu tiên
    await client.aiAgent.streamChat({
      assistant_id: aiAgentId,
      id: sessionId,
      messages: [{ role: "user", content: "What's your refund policy?" }],
    })
    

    // Tin nhắn tiếp theo — cùng phiên, AI agent nhớ ngữ cảnh
    await client.aiAgent.streamChat({
      assistant_id: aiAgentId,
      id: sessionId,
      messages: [{ role: "user", content: "How long does it take?" }],
    })

2. Tạo Workflow và Gắn nó vào AI Agent

  1. Lấy project ID của bạn

    Sao chép Project ID từ Imbrace Dashboard → Workflows, hoặc lấy bằng code nếu tổ chức của bạn đã có flow:

    // Cách A — hardcode từ Dashboard (khuyến nghị cho tổ chức mới)
    const projectId = "your_project_id"
    

    // Cách B — lấy từ một flow có sẵn (báo lỗi nếu tổ chức chưa có flow nào)
    const projectId = await client.workflows.resolveProjectId()

  2. Tạo một flow mới

    const flow = await client.workflows.createFlow({
      displayName: "CRM Update on New Lead",
      projectId,
    })
    console.log("Flow created:", flow.id)

  3. Thêm trigger Webhook và xuất bản flow

    Một flow mới tạo ở trạng thái DRAFT không có trigger — URL webhook chưa tồn tại, vì vậy triggerFlow sẽ trả về 404. Thêm piece Webhook làm trigger, sau đó xuất bản:

    // Đặt piece Webhook làm trigger của flow
    await client.workflows.applyFlowOperation(flow.id, {
      type: "UPDATE_TRIGGER",
      request: {
        name: "trigger",
        type: "PIECE_TRIGGER",
        valid: true,
        displayName: "Webhook",
        settings: {
          pieceName: "@activepieces/piece-webhook",
          pieceVersion: "0.1.24",
          triggerName: "catch_webhook",
          input: { authType: "none" },
          propertySettings: {},
        },
      },
    })
    

    // Xuất bản — trạng thái flow chuyển từ DISABLED → ENABLED và URL webhook hoạt động
    await client.workflows.applyFlowOperation(flow.id, {
      type: "LOCK_AND_PUBLISH",
      request: {},
    })

  4. Kích hoạt flow thủ công với payload

    // Fire and forget (bất đồng bộ)
    await client.workflows.triggerFlow(flow.id, {
      contact_name: "Jane Smith",
      email: "jane@example.com",
    })
    

    // Trigger đồng bộ — để lời gọi này thực sự trả về dữ liệu thay vì hết thời gian,
    // flow cần có hành động "Return Response" được thêm qua applyFlowOperation
    // ADD_ACTION (nếu không gateway đợi 30s cho phản hồi và từ bỏ).
    const result = await client.workflows.triggerFlowSync(flow.id, {
      contact_name: "Jane Smith",
      email: "jane@example.com",
    })
    console.log("Flow result:", result)

  5. Gắn flow vào AI agent của bạn

    Mở AI agent của bạn trong bảng điều khiển Imbrace, đi đến Tools → Workflows, và đính kèm flow. AI agent sẽ có thể kích hoạt nó trong cuộc hội thoại khi thích hợp.

    Ngoài ra, cập nhật AI agent để tham chiếu workflow theo tên:

    await client.chatAi.updateAiAgent(aiAgentId, {
      name: "Support Bot",
      workflow_name: "support_bot_v1",
      workflow_function_call: [{ flow_id: flow.id, description: "Update CRM on new lead" }],
    })

  6. Kiểm tra lịch sử chạy

    const { data: runs } = await client.workflows.listRuns({
      flowId: flow.id,
      limit: 10,
    })
    for (const run of runs) {
      console.log(run.id, run.status, run.startTime)
    }

3. Quản lý Knowledge Hubs và Gắn vào AI Agent

Các tệp và thư mục Knowledge Hub nằm trong dịch vụ data-board (client.boards). _id của thư mục là giá trị bạn truyền cho AI agent làm nguồn kiến thức.

  1. Tạo một thư mục

    const folder = await client.boards.createFolder({
      name: "Product Documentation",
      organization_id: process.env.IMBRACE_ORGANIZATION_ID,
      parent_id: "root",
    })
    console.log("Folder ID:", folder._id)

  2. Tải tệp lên thư mục

    import { readFileSync } from "fs"
    

    const fileBuffer = readFileSync("./docs/faq.pdf")
    const formData = new FormData()
    formData.append("file", new Blob([fileBuffer], { type: "application/pdf" }), "faq.pdf")
    formData.append("folder_id", folder._id)
    formData.append("organization_id", process.env.IMBRACE_ORGANIZATION_ID ?? "")
    

    const uploaded = await client.boards.uploadFile(formData)
    console.log("File uploaded:", uploaded.file_id)

  3. Gắn thư mục vào AI agent

    Truyền _id của thư mục trong folder_ids — AI agent truy xuất từ mọi tệp trong thư mục đó. Sử dụng board_ids để gắn một data-board CRM (các mục của nó trở thành nguồn kiến thức — xem Resources → Boards & items). Trường knowledge_hubs cũ đã bị deprecated (không nên dùng nữa).

    await client.chatAi.updateAiAgent(aiAgentId, {
      name: "Support Bot",
      workflow_name: "support_bot_v1",
      folder_ids: [folder._id],
      // board_ids: [boardId],  // tùy chọn: gắn thêm data-board CRM
    })

  4. Kiểm tra và quản lý thư mục và tệp

    // Tìm kiếm thư mục
    const folders = await client.boards.searchFolders({ q: "Product" })
    

    // Lấy thư mục với nội dung
    const contents = await client.boards.getFolderContents(folder._id)
    console.log("Files:", contents.files?.length)
    

    // Đổi tên thư mục
    await client.boards.updateFolder(folder._id, { name: "Product Docs v2" })
    

    // Tìm kiếm tệp trong thư mục
    const files = await client.boards.searchFiles({ folderId: folder._id })
    

    // Xóa thư mục
    await client.boards.deleteFolders({ ids: [folder._id] })

4. Quản lý Data Boards và Mục (CRM Pipelines)

  1. Tạo một board

    Board là một pipeline CRM — khách hàng tiềm năng, giao dịch, nhiệm vụ, hoặc bất kỳ dữ liệu có cấu trúc nào.

    const board = await client.boards.create({
      name: "Sales Pipeline",
      description: "Track all active deals",
    })
    console.log("Board ID:", board._id)

  2. Thêm trường tùy chỉnh

    Các loại trường là ShortText, LongText, Number, Dropdown, Date, Checkbox, v.v. createField trả về trường vừa được tạo. Để xem tất cả các trường trên board, hãy lấy board riêng.

    await client.boards.createField(board._id, {
      name: "Company",
      type: "ShortText",
    })
    

    // Board tự động tạo một trường định danh — lấy board để xem tất cả các trường
    const boardWithFields = await client.boards.get(board._id) as any
    const identifierField = boardWithFields.fields?.find((f: any) => f.is_identifier)

  3. Tạo mục board (bản ghi)

    Các mục sử dụng định dạng { fields: [{ board_field_id, value }] }:

    const item = await client.boards.createItem(board._id, {
      fields: [
        { board_field_id: identifierField._id, value: "Acme Corp" },
      ],
    })
    console.log("Item ID:", item._id)

  4. Liệt kê và tìm kiếm mục

    // Phân trang qua các mục
    const { data: items } = await client.boards.listItems(board._id, { limit: 20, skip: 0 })
    

    // Tìm kiếm toàn văn
    const { data: results } = await client.boards.search(board._id, {
      q: "Acme",
      limit: 10,
    })

  5. Cập nhật và xóa mục

    Cập nhật sử dụng { data: [{ key, value }] } (lưu ý: key, không phải board_field_id):

    await client.boards.updateItem(board._id, item._id, {
      data: [{ key: identifierField._id, value: "Acme Corp — Closed Won" }],
    })
    

    await client.boards.deleteItem(board._id, item._id)

  6. Xuất ra CSV

    const csv = await client.boards.exportCsv(board._id)
    // csv là một chuỗi — ghi vào tệp hoặc gửi dưới dạng tải xuống

Các bước tiếp theo

  • Resources → — tham chiếu method theo từng namespace cho cả bốn quy trình
  • AI Agent → — tìm hiểu sâu hơn về streamChat, embeddings và parquet
  • Workflows → — thao tác flow, MCP server và lịch sử chạy
  • Document AI → — phân tích và trích xuất tài liệu bằng AI
  • Data Board → — trường, item, tìm kiếm, segment và CSV của board