跳转到内容
Imbrace SDK

资源参考

本页列出 SDK 公开的每个资源命名空间以及每个命名空间中最常用的调用。首先初始化 client（参阅安装或快速入门）。以下所有代码片段均假设 client 是已初始化的实例。

端到端演练请参阅完整流程指南。

助手 — chatAi / chat_ai

管理 AI 助手（CRUD）、运行 OpenAI 兼容的 completions，以及处理 document/file。该命名空间也涵盖 Knowledge Hub 文件夹和 knowledge bases。

助手 CRUD

// 列出账户中的所有助手
const assistants = await client.chatAi.listAssistants();


// 获取单个助手
const assistant = await client.chatAi.getAssistant("9f77692f-33d0-436a-8138-2efb268838e6");


// 创建 — provider_id 和 model_id 为必填
const created = await client.chatAi.createAssistant({
  name: "Support Bot",
  workflow_name: "support_bot_v1",
  provider_id: "system",
  model_id: "gpt-4o",
  description: "处理一级支持问题",
});


// 更新 — 更新时 workflow_name 也是必填
const updated = await client.chatAi.updateAssistant(created.id, {
  name: "Support Bot v2",
  workflow_name: "support_bot_v1",
});


// 仅更新系统指令
await client.chatAi.updateAssistantInstructions(
  created.id,
  "您是一位乐于助人的支持代理。",
);


await client.chatAi.deleteAssistant(created.id);

Completions

const response = await client.chatAi.chat({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "您是 CRM 助手。" },
    { role: "user", content: "总结这位客户的备注：..." },
  ],
});
console.log(response.choices[0].message.content);

模型

const models = await client.chatAi.listModels();

文件处理

// 从 PDF 或图像中提取结构化数据
const result = await client.chatAi.extractFile({
  modelName: "gpt-4o",
  url: "https://example.com/invoice.pdf",
  organizationId: "org_xxx",
});

持久化聊天会话（Python）

chat    = client.chat_ai.create_chat({"title": "Support Chat"})
history = client.chat_ai.list_chats()
client.chat_ai.delete_chat(chat["id"])

Knowledge Hub — 文件夹和 Knowledge Bases

文件夹组织 knowledge bases。创建助手时在 folder_ids 中传入文件夹 ID — 参阅完整流程指南 §3。

// 文件夹
const folders = await client.chatAi.listFolders();
const folder  = await client.chatAi.createFolder({ name: "Q1 报告" });
await client.chatAi.updateFolder(folder.id, { name: "Q1 2025 报告" });
await client.chatAi.deleteFolder(folder.id);


// Knowledge bases
const all = await client.chatAi.listKnowledge();
const kb  = await client.chatAi.getKnowledge("kb_id");
const created = await client.chatAi.createKnowledge({
  name: "支持文档",
  folderId: folder.id,
});
await client.chatAi.deleteKnowledge(created.id);

OpenAI 兼容 AI 服务 — client.ai（Python）

原始 OpenAI 风格的 completions、streaming 和 embeddings。TypeScript SDK 目前不公开此命名空间 — 请改用助手 → Completions。

# 单次 completion
response = client.ai.complete(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "您是 CRM 助手。"},
        {"role": "user",   "content": "总结这位客户的备注：..."},
    ],
    temperature=0.7,
)
print(response["choices"][0]["message"]["content"])


# 流式传输
for chunk in client.ai.stream(
    model="gpt-4o",
    messages=[{"role": "user", "content": "为这个 lead 起草跟进邮件。"}],
):
    print(chunk["choices"][0]["delta"].get("content", ""), end="", flush=True)


# Embeddings
result = client.ai.embed(
    model="text-embedding-ada-002",
    input=["客户投诉计费问题", "计费问题升级"],
)

AI Agent — aiAgent / ai_agent

与助手的流式聊天、knowledge base embedding 管理、parquet 数据和终端用户聊天会话。参阅 AI Agent 获取完整的方法参考。最常用的入口是 streamChat。

流式聊天（SSE）

const sessionId = crypto.randomUUID();


const response = await client.aiAgent.streamChat({
  id: sessionId,
  assistant_id: "asst_xxx",
  organization_id: "org_xxx",
  messages: [{ role: "user", content: "本季度哪些交易已成交？" }],
});


const reader = response.body!.getReader();
const decoder = new TextDecoder();


while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value);
  for (const line of text.split("\n")) {
    if (!line.startsWith("data: ")) continue;
    const raw = line.slice(6).trim();
    if (raw === "[DONE]") break;
    try {
      const event = JSON.parse(raw);
      if (event.type === "text-delta") process.stdout.write(event.textDelta);
    } catch {}
  }
}

提示建议

const suggestions = await client.aiAgent.getAgentPromptSuggestion("asst_xxx");

Embedding 文件（Knowledge Base）

const files = await client.aiAgent.listEmbeddingFiles();
const file  = await client.aiAgent.getEmbeddingFile("file_id");


const classified = await client.aiAgent.classifyFile({
  url: "https://example.com/product-catalog.pdf",
  mime_type: "application/pdf",
});


await client.aiAgent.updateEmbeddingFileStatus("file_id", { status: "active" });
await client.aiAgent.deleteEmbeddingFile("file_id");

Parquet 数据

const job = await client.aiAgent.generateParquet({
  assistant_id: "asst_xxx",
  data: [{ id: "1", name: "Acme Corp", revenue: 120000 }],
});


const parquetFiles = await client.aiAgent.listParquetFiles();
await client.aiAgent.deleteParquetFile("file_id");

终端用户聊天客户端

const chat = await client.aiAgent.createClientChat({
  id: crypto.randomUUID(),
  assistantId: "asst_xxx",
  organizationId: "org_xxx",
  userId: "user_xxx",
  selectedVisibilityType: "private",
  message: {
    id: crypto.randomUUID(),
    role: "user",
    content: "您好，我需要帮助。",
    createdAt: new Date().toISOString(),
    parts: [{ type: "text", text: "您好，我需要帮助。" }],
  },
});


const clientChats = await client.aiAgent.listClientChats();
const messages    = await client.aiAgent.listClientMessages(chat.id);
await client.aiAgent.deleteClientChat(chat.id);

工作流 — Activepieces (client.activepieces，TypeScript)

完整 lifecycle（create → publish → trigger），参阅完整流程指南 §2。

Flows

const { data: flows } = await client.activepieces.listFlows();
const flow = await client.activepieces.getFlow("flow_id");
const newFlow = await client.activepieces.createFlow({
  displayName: "新 Lead 通知",
  folderId: "folder_id",
});
await client.activepieces.deleteFlow("flow_id");

触发 Flow

// 异步触发
await client.activepieces.triggerFlow("flow_id", {
  contactId: "contact_xxx",
  event: "lead_qualified",
});


// 等待结果
const result = await client.activepieces.triggerFlowSync("flow_id", {
  contactId: "contact_xxx",
  event: "lead_qualified",
});

Runs、文件夹、连接、表

const { data: runs }     = await client.activepieces.listRuns({ flowId: "flow_id", limit: 20 });
const run                = await client.activepieces.getRun("run_id");
const { data: folders }  = await client.activepieces.listFolders();
const folder             = await client.activepieces.createFolder({ displayName: "CRM 自动化" });
const { data: connections } = await client.activepieces.listConnections();
const { data: tables }   = await client.activepieces.listTables();
const { data: records }  = await client.activepieces.listRecords({ tableId: "table_id" });

看板 & 条目 — client.boards

看板是 CRM pipeline 的核心数据存储。参阅完整流程指南 §4。

看板 CRUD

const { data: boards } = await client.boards.list();
const board = await client.boards.get("board_id");
const newBoard = await client.boards.create({ name: "企业 Leads" });
await client.boards.update("board_id", { name: "企业 Leads 2025" });
await client.boards.delete("board_id");

条目

const { data: items } = await client.boards.listItems("board_id", { limit: 100 });
const item = await client.boards.getItem("board_id", "item_id");


const lead = await client.boards.createItem("board_id", {
  fields: { name: "Acme Corp", status: "new", value: 50000 },
});


await client.boards.updateItem("board_id", lead.id, {
  fields: { status: "qualified" },
});


await client.boards.deleteItem("board_id", "item_id");
await client.boards.bulkDeleteItems("board_id", ["item_1", "item_2", "item_3"]);

搜索

const results = await client.boards.search("board_id", { q: "enterprise" });

字段、段和导出

// 字段
const field = await client.boards.createField("board_id", {
  name: "交易价值",
  type: "number",
});
await client.boards.updateField("board_id", field.id, { name: "合同价值" });
await client.boards.deleteField("board_id", field.id);


// 段
const { data: segments } = await client.boards.listSegments("board_id");
const segment = await client.boards.createSegment("board_id", {
  name: "高价值 Leads",
  filters: [{ field: "value", op: "gt", value: 10000 }],
});


// 导出 CSV
const csv = await client.boards.exportCsv("board_id");

联系人 — client.contacts

const { data: contacts } = await client.contacts.list({ limit: 50 });
const contact = await client.contacts.get("contact_id");


await client.contacts.update("contact_id", {
  name: "Alice B.",
  email: "alice@example.com",
  phone: "+84901234567",
});


const activity = await client.contacts.getActivity("contact_id");
const comments = await client.contacts.getComments("contact_id");
const files    = await client.contacts.getFiles("contact_id");

对话 — client.conversations

// 搜索
const { data: convs } = await client.conversations.search({
  businessUnitId: "bu_xxx",
  q: "support",
  limit: 20,
});


// 未处理的对话
const { data: open } = await client.conversations.getOutstanding({
  businessUnitId: "bu_xxx",
  limit: 50,
});


// 分配
await client.conversations.assignTeamMember({
  conversation_id: "conv_xxx",
  user_id: "user_xxx",
});


// 更新状态
await client.conversations.updateStatus({
  conversation_id: "conv_xxx",
  status: "resolved",
});

消息 — client.channel、client.messages

const channels = await client.channel.list();


await client.messages.send("conversation_id", {
  parts: [{ type: "text", text: "您好，有什么可以帮您？" }],
});


const msgs = await client.messages.list("conversation_id");
await client.channel.markRead("conversation_id");

渠道自动化工作流 — client.workflows（Python）

automations    = client.workflows.list_channel_automation().get("data", [])
whatsapp_flows = client.workflows.list_channel_automation(channel_type="whatsapp")

营销活动 & 触点 — client.campaign（Python）

# Campaign CRUD
campaigns = client.campaign.list().get("data", [])
campaign  = client.campaign.get("campaign_id")
new_camp  = client.campaign.create({"name": "Q2 推广", "type": "email"})
client.campaign.delete("campaign_id")


# 触点
touchpoints = client.campaign.list_touchpoints().get("data", [])
tp = client.campaign.get_touchpoint("touchpoint_id")


client.campaign.create_touchpoint({
    "campaign_id": "campaign_id",
    "type":        "email",
    "delay_days":  3,
})
client.campaign.update_touchpoint("touchpoint_id", {"delay_days": 5})
client.campaign.delete_touchpoint("touchpoint_id")


# 保存前验证触点配置
result = client.campaign.validate_touchpoint({"type": "email", "template_id": "tpl_xxx"})

消息建议 — client.message_suggestion（Python）

suggestions = client.message_suggestion.get_suggestions({
    "conversation_id": "conv_xxx",
    "limit": 3,
})

预测 — client.predict（Python）

result = client.predict.predict({
    "model": "lead_score_v1",
    "input": {"company_size": 200, "industry": "saas", "mrr": 5000},
})
print(result["score"])   # 0.87