跳到內容
Imbrace SDK

完整流程指南

本指南從頭到尾逐步說明 Imbrace SDK 中的四大主要工作流程。每個章節都是獨立的 — 可以依序閱讀或直接跳到您需要的部分。

1. 建立 AI Agent 並開始聊天

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

  2. 建立 AI agent

    workflow_name 在您的組織內必須是唯一的。

    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",   // 使用組織的預設 LLM 提供者
      model_id: "Default",     // 路由到組織設定的預設模型
      streaming: true,         // 發出 text-delta SSE 事件（見下方 Aside）
    })
    

    const aiAgentId = agent.id  // UUID — 所有後續呼叫使用此 ID
    console.log("AI agent created:", aiAgentId)

    provider_id 和 model_id 是可選的 — SDK 在省略時會自動填入 { provider_id: "default", model_id: "Default" }。"Default" 路由到組織設定的系統預設模型，是跨組織通用的選擇。顯式傳入即可覆寫：provider_id: "<uuid>" 指定自訂 LLM 提供者，或 model_id: "gpt-4o" 等 — 但具體模型名稱只在該組織的 default 提供者實際公開該模型時才有效。在寫死於程式碼前，使用 client.ai.listModels()（TypeScript）/ client.ai.list_models()（Python）列出組織的可用模型。

  3. 使用 AI agent 串流聊天回應

    使用 streamChatText / stream_chat_text — 它包裝了 streamChat，會解析 SSE 事件串流並逐一產出純文字片段。前提是代理以 streaming: true 建立（見步驟 2 的 Aside）。

    for await (const chunk of client.aiAgent.streamChatText({
      assistant_id: aiAgentId,
      messages: [{ role: "user", content: "How do I reset my password?" }],
      // id 是工作階段 UUID — 重複使用以保持對話歷史記錄。
      // 如果省略，每次呼叫會自動產生新的 UUID。
    })) {
      process.stdout.write(chunk)
    }

  4. 維護對話歷史記錄（工作階段 ID）

    在多次呼叫中傳遞相同的 id（必須是 UUID）以保持上下文：

    import { randomUUID } from "crypto"
    

    const sessionId = randomUUID()
    

    // 第一則訊息
    await client.aiAgent.streamChat({
      assistant_id: aiAgentId,
      id: sessionId,
      messages: [{ role: "user", content: "What's your refund policy?" }],
    })
    

    // 後續 — 相同工作階段，AI agent 記住上下文
    await client.aiAgent.streamChat({
      assistant_id: aiAgentId,
      id: sessionId,
      messages: [{ role: "user", content: "How long does it take?" }],
    })

2. 建立工作流程並繫結至 AI Agent

  1. 取得您的專案 ID

    從 Imbrace Dashboard → Workflows 複製您的 Project ID；若您的組織已有流程，也可以透過程式解析：

    // 選項 A — 從 Dashboard 取得後寫死（建議新組織使用）
    const projectId = "your_project_id"
    

    // 選項 B — 從現有流程解析（若組織尚無任何流程會拋出錯誤）
    const projectId = await client.workflows.resolveProjectId()

  2. 建立新流程

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

  3. 新增 Webhook 觸發條件並發佈流程

    新建立的流程處於 DRAFT（草稿）狀態且沒有觸發條件 — Webhook URL 還不存在，因此 triggerFlow 會回傳 404。新增 Webhook 元件作為觸發條件，然後發佈：

    // 將 Webhook 元件設為流程的觸發條件
    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: {},
        },
      },
    })
    

    // 發佈 — 流程狀態從 DISABLED 轉為 ENABLED，Webhook URL 生效
    await client.workflows.applyFlowOperation(flow.id, {
      type: "LOCK_AND_PUBLISH",
      request: {},
    })

  4. 使用酬載手動觸發流程

    // 觸發後即忘（非同步）
    await client.workflows.triggerFlow(flow.id, {
      contact_name: "Jane Smith",
      email: "jane@example.com",
    })
    

    // 同步觸發 — 要讓它實際回傳資料而不會逾時，
    // 流程需要透過 applyFlowOperation ADD_ACTION 新增「回傳回應」動作
    // （否則閘道會等待 30 秒回應然後放棄）。
    const result = await client.workflows.triggerFlowSync(flow.id, {
      contact_name: "Jane Smith",
      email: "jane@example.com",
    })
    console.log("Flow result:", result)

  5. 將流程繫結至您的 AI agent

    在 Imbrace 儀表板中開啟您的 AI agent，前往工具 → 工作流程，然後附加流程。AI agent 將能夠在對話中適當時觸發它。

    或者，更新 AI agent 以依名稱參考工作流程：

    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. 檢查執行歷史記錄

    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. 管理知識中心並附加至 AI Agent

知識中心檔案和資料夾存在於 data-board 服務（client.boards）中。資料夾的 _id 就是您傳遞給 AI agent 作為其知識來源的內容。

  1. 建立資料夾

    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. 上傳檔案至資料夾

    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. 將資料夾附加至 AI agent

    在 folder_ids 中傳遞資料夾 _id — AI agent 從該資料夾中的每個檔案檢索。使用 board_ids 來附加 CRM data-board（其項目成為知識來源 — 請參閱資源 → Boards 與項目）。舊的 knowledge_hubs 欄位已棄用。

    await client.chatAi.updateAiAgent(aiAgentId, {
      name: "Support Bot",
      workflow_name: "support_bot_v1",
      folder_ids: [folder._id],
      // board_ids: [boardId],  // 可選：也附加 CRM data-board
    })

  4. 檢查和管理資料夾與檔案

    // 搜尋資料夾
    const folders = await client.boards.searchFolders({ q: "Product" })
    

    // 取得資料夾內容
    const contents = await client.boards.getFolderContents(folder._id)
    console.log("Files:", contents.files?.length)
    

    // 重新命名資料夾
    await client.boards.updateFolder(folder._id, { name: "Product Docs v2" })
    

    // 搜尋資料夾中的檔案
    const files = await client.boards.searchFiles({ folderId: folder._id })
    

    // 刪除資料夾
    await client.boards.deleteFolders({ ids: [folder._id] })

4. 管理 Data Boards 與項目（CRM 管道）

  1. 建立 Board

    Board 就是一個 CRM 管道 — 潛在客戶、交易、任務或任何結構化資料。

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

  2. 新增自訂欄位

    欄位類型有 ShortText、LongText、Number、Dropdown、Date、Checkbox 等。createField 會回傳新建立的欄位。若要檢視 board 上的所有欄位，請另外擷取該 board。

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

    // Board 會自動建立識別欄位 — 擷取 board 以查看所有欄位
    const boardWithFields = await client.boards.get(board._id) as any
    const identifierField = boardWithFields.fields?.find((f: any) => f.is_identifier)

  3. 建立 board 項目（記錄）

    項目使用 { 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. 列出和搜尋項目

    // 分頁瀏覽項目
    const { data: items } = await client.boards.listItems(board._id, { limit: 20, skip: 0 })
    

    // 全文搜尋
    const { data: results } = await client.boards.search(board._id, {
      q: "Acme",
      limit: 10,
    })

  5. 更新和刪除項目

    更新使用 { data: [{ key, value }] }（注意：是 key，不是 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. 匯出為 CSV

    const csv = await client.boards.exportCsv(board._id)
    // csv 是字串 — 寫入檔案或作為下載傳送

下一步