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

Tổng quan

Imbrace SDK là client chính thức cho Imbrace Gateway, có sẵn cho TypeScript và Python. Cả hai SDK đều bao bọc cùng một Gateway API với cùng các resource namespaces, cùng mô hình xác thực, và cùng ngữ nghĩa thử lại/lỗi — hãy chọn ngôn ngữ phù hợp với stack của bạn.

Tính năng chính

Tính năngChi tiết
An toàn kiểu dữ liệuTypeScript types và Python type hints trên mọi resource
Hai loại thông tin xác thựcapiKey hoặc accessToken — xem Xác thực
Tự động thử lạiThử lại 429 và 5xx với exponential backoff, không cần cấu hình
Streaming AISSE / async iterator cho streamChat và AI completions
Async & đồng bộ (Py)ImbraceClient (đồng bộ) và AsyncImbraceClient (bất đồng bộ)
Hủy (TS)Truyền AbortSignal để hủy tác vụ đang thực hiện

Cài đặt

Phiên bản hiện tại: @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()

Các resource có sẵn

Mọi namespace đều có trên cả hai SDK. Các phương thức tuân theo quy ước ngôn ngữ — client.aiAgent.streamChat() trong TS, client.ai_agent.stream_chat() trong Python.

NamespaceMicroserviceMục đích
client.aiAgent / client.ai_agentai-agentChat AI streaming, embeddings, parquet, sub-API chat-client
client.chatAi / client.chat_aiai-service-v2AI Agent CRUD (tạo/cập nhật/xóa/danh sách)
client.documentAi / client.document_aiai-service-v2Phân tích tài liệu, trích xuất, AI trên tệp
client.agentmarketplaceMẫu AI agent + use-case (tạo đồng thời assistant + workflow + channel trong một thao tác qua createUseCase)
client.workflowsworkflow-engineTự động hóa workflow — flows, triggers, runs
client.boardsdata-boardCRM boards — CRUD, items, fields, search, segments, CSV; KnowledgeHub thư mục & tệp
client.platform, client.organizations, client.teamsplatformNgười dùng, tổ chức, nhóm, business unit
client.contacts, client.conversations, client.messages, client.channel, client.categories, client.campaign, client.outboundchannel-serviceLiên hệ, hội thoại, tin nhắn, quản lý kênh/chiến dịch
client.marketplacemarketplaceTệp marketplace, mẫu email, workflow kênh
client.fileServicefile-serviceTải tệp theo ngữ cảnh (đính kèm board, tệp liên hệ, tệp tài chính, presigned URL)
client.ips, client.scheduleipsLịch / quy tắc tự động giữa các tiến trình
client.aiai-service-v2Completions/embeddings tương thích OpenAI, providers, guardrails
client.authplatform / backend cũĐăng nhập (OTP, mật khẩu, SSO), exchange token

Để xem danh sách đầy đủ và tài liệu tham khảo phương thức, hãy xem Resources.

Toàn bộ bề mặt API — client.api (TypeScript)

Từ v1.3.0, TypeScript SDK còn kèm một bề mặt sinh tự động bao phủ mọi operation mà các service Imbrace mở cho AI agent — 272 operation trên 5 service, sinh từ các spec OpenAPI agent-tools của chính các service:

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

Namespace: client.api.dataBoard, .channel, .platform, .marketplace, .workflow.

Bề mặt này đầy đủ và luôn đồng bộ với service đã triển khai, nhưng phần lớn operation trả về unknown (spec không khai báo schema response) — hãy truyền type argument khi bạn biết cấu trúc dữ liệu. Ưu tiên các resource viết tay ở trên khi chúng đáp ứng được; dùng client.api cho phần còn lại thay vì tự viết fetch.

Cùng registry operation này cũng là nền tảng của MCP server host sẵn trên gateway và lệnh imbrace mcp trong CLI — cả hai đều mở các operation này thành tool MCP cho AI agent.

Khi nào nên chọn loại thông tin xác thực nào

API Key (api_...)Access Token (eyJ...)
Cách lấyImbrace Dashboard → Generate External TokenĐăng nhập OTP (requestOtp / loginWithOtp)
Phù hợp nhất choScript phía server, tích hợp backend, pipeline CIỨng dụng hướng đến người dùng cuối, nơi mỗi người dùng đăng nhập
Phạm viTổ chức của bạn — truy cập toàn bộ APIPhiên theo người dùng — giới hạn theo quyền của người dùng đó

Cây quyết định đầy đủ: Xác thực → · Lấy API Key →

Các bước tiếp theo