跳到內容
Imbrace SDK

概覽

Imbrace SDK 是 Imbrace Gateway 的官方用戶端，提供 TypeScript 和 Python 兩種版本。兩個 SDK 都封裝了相同的 Gateway API，具有相同的資源命名空間、相同的認證模型，以及相同的重試/錯誤語義 — 選擇適合您技術堆疊的語言即可。

主要功能

功能詳細說明
型別安全每個資源都有 TypeScript 型別和 Python 型別提示
兩種憑證類型apiKey 或 accessToken — 請參閱認證
自動重試429 和 5xx 使用指數退避重試，無需設定
串流 AISSE / 非同步迭代器用於 streamChat 和 AI 補全
同步與非同步（Python）ImbraceClient（同步）和 AsyncImbraceClient（非同步）
取消（TypeScript）傳遞 AbortSignal 以取消進行中的請求

安裝

目前版本： @imbrace/sdk v1.4.0（npm）· imbrace v1.2.1（PyPI）

Terminal window
npm install @imbrace/sdk

Hello, world

import { ImbraceClient } from "@imbrace/sdk"


const client = new ImbraceClient({ apiKey: "api_your_key" })
const me = await client.platform.getMe()

可用資源

每個命名空間在兩個 SDK 上都存在。方法遵循語言慣例 — TypeScript 中為 client.aiAgent.streamChat()，Python 中為 client.ai_agent.stream_chat()。

命名空間微服務用途
client.aiAgent / client.ai_agentai-agent串流 AI 聊天、嵌入、parquet、聊天用戶端子 API
client.chatAi / client.chat_aiai-service-v2AI Agent CRUD（建立/更新/刪除/列出）
client.documentAi / client.document_aiai-service-v2文件解析、擷取、檔案 AI
client.agentmarketplaceAI agent 範本 + use-case（透過 createUseCase 原子建立 assistant + workflow + channel）
client.workflowsworkflow-engine工作流程自動化 — 流程、觸發條件、執行
client.boardsdata-boardCRM boards — CRUD、項目、欄位、搜尋、區隔、CSV；KnowledgeHub 資料夾與檔案
client.platform、client.organizations、client.teamsplatform使用者、組織、團隊、業務單位
client.contacts、client.conversations、client.messages、client.channel、client.categories、client.campaign、client.outboundchannel-service聯絡人、對話、訊息、頻道/活動管理
client.marketplacemarketplace市集檔案、電子郵件範本、頻道工作流程
client.fileServicefile-service情境感知檔案上傳（board 附件、聯絡人檔案、財務檔案、presigned URL）
client.ips、client.scheduleips程序間排程 / 自動化規則
client.aiai-service-v2相容 OpenAI 的補全、嵌入、提供者、護欄
client.authplatform / 舊版 backend登入（OTP、密碼、SSO）、token 交換

如需完整清單和方法參考，請參閱資源。

完整 API 介面 — client.api（TypeScript）

自 v1.3.0 起，TypeScript SDK 還附帶一個產生的 API 介面，涵蓋 Imbrace 各服務向 AI agent 開放的全部操作 — 5 個服務共 272 個操作，由各服務的 agent-tools OpenAPI 規格產生：

const boards = await client.api.dataBoard.listBoards<{ data: Board[] }>();
const flows  = await client.api.workflow.listFlows();

命名空間：client.api.dataBoard、.channel、.platform、.marketplace、.workflow。

它完整且始終與已部署的服務保持同步，但大多數操作回傳 unknown（規格未宣告回應 schema）— 已知資料結構時請傳入型別參數。若上面的手寫資源已涵蓋您的呼叫，請優先使用；它們未涵蓋的部分再改用 client.api，而不要自己手寫 fetch。

同一操作註冊表也驅動閘道的託管 MCP 伺服器和 CLI 的 imbrace mcp 指令，兩者都把這些操作作為 MCP 工具提供給 AI agent。

何時選擇哪種憑證

API 金鑰（api_...）存取權杖（eyJ...）
取得方式Imbrace Dashboard → Generate External TokenOTP 登入（requestOtp / loginWithOtp）
最適合伺服器腳本、後端整合、CI 管線每個終端使用者各自登入的面向使用者應用程式
範圍您的組織 — 完整 API 存取權每位使用者的工作階段 — 僅限該使用者的權限

完整的決策樹：認證 → · 取得 API 金鑰 →

下一步