概览
Imbrace SDK 是 Imbrace Gateway 的官方客户端，提供 TypeScript 和 Python 两种版本。两个 SDK 封装了相同的 Gateway API，具有相同的资源命名空间、相同的认证模型以及相同的重试/错误语义 — 选择适合你技术栈的语言即可。
主要特性
| 特性 | 详情 |
|---|---|
| 类型安全 | 每个资源都有 TypeScript 类型和 Python 类型提示 |
| 两种凭证类型 | apiKey 或 accessToken — 参见认证 |
| 自动重试 | 429 和 5xx 重试带指数退避，无需配置 |
| AI 流式传输 | SSE / 异步迭代器，用于 streamChat 和 AI 补全 |
| 异步与同步（Python） | ImbraceClient（同步）和 AsyncImbraceClient（异步） |
| 取消（TS） | 通过 AbortSignal 传播实现进行中的请求取消 |
安装
当前版本：
@imbrace/sdkv1.4.0（npm）·imbracev1.2.1（PyPI）
npm install @imbrace/sdkpip install imbraceHello, world
import { ImbraceClient } from "@imbrace/sdk"
const client = new ImbraceClient({ apiKey: "api_your_key" })const me = await client.platform.getMe()from imbrace import ImbraceClient
with ImbraceClient(api_key="api_your_key") as client: me = client.platform.get_me()可用资源
每个命名空间在两个 SDK 中都有。方法遵循语言惯例 — TypeScript 中为 client.aiAgent.streamChat()，Python 中为 client.ai_agent.stream_chat()。
| 命名空间 | 微服务 | 用途 |
|---|---|---|
client.aiAgent / client.ai_agent | ai-agent | 流式 AI 聊天、嵌入、parquet、聊天客户端子 API |
client.chatAi / client.chat_ai | ai-service-v2 | AI 代理增删改查（创建/更新/删除/列出） |
client.documentAi / client.document_ai | ai-service-v2 | 文档解析、提取、文件 AI |
client.agent | marketplace | AI 代理模板 + 用例（通过 createUseCase 原子创建 assistant + workflow + channel） |
client.workflows | workflow-engine | 工作流自动化 — 流程、触发器、运行 |
client.boards | data-board | CRM 面板 — 增删改查、条目、字段、搜索、分段、CSV；知识中心文件夹和文件 |
client.platform, client.organizations, client.teams | platform | 用户、组织、团队、业务单元 |
client.contacts, client.conversations, client.messages, client.channel, client.categories, client.campaign, client.outbound | channel-service | 联系人、对话、消息、渠道/营销活动管理 |
client.marketplace | marketplace | 市场文件、邮件模板、渠道工作流 |
client.fileService | file-service | 上下文感知文件上传（面板附件、联系人文件、财务文件、预签名 URL） |
client.ips, client.schedule | ips | 进程间调度 / 自动化规则 |
client.ai | ai-service-v2 | 兼容 OpenAI 的补全/嵌入、providers、guardrails |
client.auth | platform / 旧后端 | 登录（OTP、密码、SSO）、token 交换 |
完整列表和方法参考请参见资源。
完整 API 表面 — client.api（TypeScript）
自 v1.3.0 起，TypeScript SDK 还附带一个生成的 API 表面，覆盖 Imbrace 各服务向 AI 代理开放的全部操作 — 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 代理。
如何选择凭证
API Key（api_...） | Access Token（eyJ...） | |
|---|---|---|
| 如何获取 | Imbrace 控制台 → Generate External Token | OTP 登录（requestOtp / loginWithOtp） |
| 最适合 | 服务器脚本、后端集成、CI 流水线 | 面向用户的应用，每个终端用户各自登录 |
| 范围 | 你的组织 — 完整 API 访问权限 | 按用户会话 — 限定在该用户的权限内 |
完整决策树：认证 → · 获取 API Key →