跳转到内容
Imbrace SDK

工作流

client.workflows 同时暴露渠道自动化（v2/backend 路由）和流程引擎（增删改查流程、运行、文件夹、连接、组件、MCP 服务器、表格、邀请）。

首先初始化客户端（参见安装或快速入门）。有关将工作流绑定到 AI 代理的端到端演练，请参见完整流程指南 §2。

渠道自动化 — client.workflows

const { data: automations }    = await client.workflows.listChannelAutomation();
const { data: whatsappFlows }  = await client.workflows.listChannelAutomation({ channelType: "whatsapp" });

流程

增删改查

const { data: flows } = await client.workflows.listFlows();


const flow = await client.workflows.getFlow("flow_id");


const newFlow = await client.workflows.createFlow({
  displayName: "New Lead Notification",
  projectId: "project_id",
});


await client.workflows.deleteFlow("flow_id");

Flow Builder — buildFlow / addSteps

TypeScript SDK v1.4.0+。Python SDK 暂未提供 — 请使用 apply_flow_operation（见下文）。

buildFlow 通过一份声明式 spec，一次调用即可创建完整流程 — 触发器加（可嵌套的）步骤。它会自动补全原始 flow-operation API 要求且容易遗漏的两件事：为每个 piece 输入补一条 propertySettings，以及为循环之后添加的 action 补 stepLocationRelativeToParent（缺少它，后续步骤会被静默孤立）。步骤名自动递增（step_1、step_2、…），除非步骤自行设置 name。

const flow = await client.workflows.buildFlow({
  displayName: "Qualify new leads",
  trigger: {
    kind: "piece",
    pieceName: "@activepieces/piece-webhook",
    pieceVersion: "0.1.24",
    triggerName: "catch_webhook",
    displayName: "Webhook",
  },
  steps: [
    {
      kind: "code",
      displayName: "Score lead",
      code: "export const code = async (inputs) => inputs;",
    },
    {
      kind: "loop",
      displayName: "For each lead",
      items: "{{trigger.leads}}",
      steps: [
        {
          kind: "piece",
          displayName: "Notify sales",
          pieceName: "@activepieces/piece-slack",
          pieceVersion: "0.5.1",
          actionName: "send_channel_message",
          input: { channel: "#sales" },
        },
      ],
    },
  ],
});

步骤类型：code（内联 TypeScript）、piece（piece 的 action）、loop（遍历 items，可嵌套 steps）。触发器可以是 piece 触发器或 { kind: "empty" }；省略则保留流程默认的空触发器。

addSteps 以同样的自动补全把步骤追加到现有流程。默认接在触发器之后；传 parentStep / location 可接到其他位置（如循环内部）。startIndex 延续步骤名计数器，保证名称唯一：

await client.workflows.addSteps(
  flow.id,
  [{ kind: "code", displayName: "Log result", code: "export const code = async () => 'done';" }],
  { parentStep: "step_2", location: "INSIDE_LOOP", startIndex: 3 },
);

应用操作

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: {},
      propertySettings: {},
    },
  },
});

触发流程

// 触发并忘记
await client.workflows.triggerFlow("flow_id", {
  contactId: "contact_xxx",
  event: "lead_qualified",
});


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

流程运行

const { data: runs } = await client.workflows.listRuns({ flowId: "flow_id", limit: 20 });
const run            = await client.workflows.getRun("run_id");

文件夹

const { data: folders }  = await client.workflows.listFolders();
const folder             = await client.workflows.getFolder("folder_id");
const newFolder          = await client.workflows.createFolder({ displayName: "CRM Automations", projectId: "project_id" });
const updated            = await client.workflows.updateFolder("folder_id", { displayName: "Updated Name" });
await client.workflows.deleteFolder("folder_id");

应用连接

const { data: connections } = await client.workflows.listConnections();
const connection            = await client.workflows.getConnection("connection_id");
await client.workflows.upsertConnection({
  name: "slack-integration",
  type: "OAUTH2",
  value: { access_token: "xoxb-xxx" },
});
await client.workflows.deleteConnection("connection_id");

组件

const pieces = await client.workflows.listPieces({ limit: 20 });

触发器

const status = await client.workflows.getTriggerRunStatus();
await client.workflows.testTrigger({ pieceName: "@activepieces/piece-webhook", flowId: "flow_id" });

表格与记录

const { data: tables }  = await client.workflows.listTables();
const table             = await client.workflows.getTable("table_id");
const { data: records } = await client.workflows.listRecords({ tableId: "table_id" });

MCP 服务器

const { data: servers } = await client.workflows.listMcpServers("project_id");
const server            = await client.workflows.getMcpServer("mcp_server_id");
const newServer         = await client.workflows.createMcpServer({ projectId: "project_id", name: "My MCP" });
await client.workflows.deleteMcpServer("mcp_server_id");
await client.workflows.rotateMcpToken("mcp_server_id");

用户邀请

const { data: invitations } = await client.workflows.listInvitations({ type: "PROJECT" });
await client.workflows.deleteInvitation("invitation_id");