AI智能体和机器人集成FlowZap图表创建API的完整指南

快速开始

将此视为开始使用FlowZap智能体API的3步流程。

1. 注册您的智能体 - 通过注册智能体获取您的API令牌
2. 身份验证 - 将您的API令牌交换为短期JWT
3. 创建图表 - 在项目中创建图表；使用Playground通过公开URL分享FlowZap Code

API端点

智能体注册

POST https://flowzap.xyz/api/agent/register

请求体：

{
  "name": "您的智能体名称",
  "email": "agent@example.com",
  "termsAccepted": true
}

响应：

{
  "success": true,
  "user": {
    "id": "user-id",
    "email": "agent@example.com"
  },
  "apiToken": "您的api令牌",
  "tokenType": "Bearer",
  "expiresAt": "2025-08-01T12:00:00Z"
}

身份验证

POST https://flowzap.xyz/api/agent/auth

请求体：

{
  "apiToken": "注册时获得的api令牌"
}

响应：

{
  "success": true,
  "accessToken": "jwt-token",
  "tokenType": "Bearer",
  "expiresIn": 900
}

创建图表

POST https://flowzap.xyz/api/agent/diagrams

请求头：

Authorization: Bearer <来自认证的jwt>
Content-Type: application/json

请求体：

{
  "name": "用户注册流程",
  "projectId": "project-id",
  "colorScheme": "purple"
}

响应：

{
  "success": true,
  "data": {
    "diagram": {
      "id": "diagram-id",
      "name": "用户注册流程",
      "colorScheme": "purple",
      "createdAt": "2025-08-13T12:00:00.000Z",
      "project": { "id": "project-id", "name": "Default Project" }
    }
  },
  "agent": { "id": "agent-user-id", "email": "agent@example.com" },
  "attribution": "Powered by FlowZap.xyz"
}

Playground 会话（公开URL）

POST https://flowzap.xyz/api/agent/playground

请求头：

Authorization: Bearer <来自认证的jwt>
Content-Type: application/json

请求体：

{
  "code": "planning {\n  n1: circle label:"Start"\n  n2: rectangle label:"Do Task"\n  n1.handle(right) -> n2.handle(left)\n}",
  "ttlDays": 14
}

响应：

{
  "success": true,
  "url": "https://flowzap.xyz/playground/abcd1234",
  "tokenExpiresAt": "2025-08-20T12:00:00.000Z",
  "attribution": "Powered by FlowZap.xyz"
}

• • 该URL会以未登录、未保存状态打开编辑器，并预填代码。
• • 只有在用户注册并明确保存后，才会创建图表。
• • 这可避免低质量图表被无意间公开或被索引。

FlowZap Code语法

FlowZap使用其自有的语法称为"FlowZap Code"来创建业务流程图。

布局样式与句柄（handle）规则（用于 Agent API）

• 车道含义： 将车道视为执行任务的特定人员或系统。
• 布局目标： 在每个车道内，流程通常应水平从左到右（类似BPMN）。仅在提示中明确要求时才使用垂直布局。
• 先定义再连接： 先定义组件，再连接它们：在每个车道中，先声明形状，再声明边。
• 句柄使用： 优先使用 right/left；仅在短暂的跨车道或次要分支时使用 top/bottom，随后回到水平。
• 决策： 将菱形放在车道主线上。“是/主路径”继续向右；“否/备选”可短暂上下后回到水平。
• 跨车道连线： 在某车道内，可引用其他车道的节点为 otherLane.node.handle(direction)；尽量减少垂直跳转。
• 对齐： 避免在车道中堆叠过高的垂直节点；保持水平对齐以减少 top/bottom 边。
• 边语法（精确）： node.handle(direction) -> node.handle(direction) [label:"文本"]，其中 direction ∈ { right, left, top, bottom }。
• 形状： 除非用户明确要求，否则不要在工作流中使用 Taskbox 形状。

基础FlowZap Code示例

1 { # 1
  n1: circle label:"开始"
  n2: rectangle label:"与AI头脑风暴想法"
  n3: diamond label:"其中有好的吗？"
  n4: rectangle label:"更深入地分析这个想法。"
  n5: rectangle label:"寻找新想法。与AI头脑风暴可以无穷无尽。"
  n6: circle label:"结束"
  n1.handle(right) -> n2.handle(left)
  n2.handle(right) -> n3.handle(left)
  n3.handle(top) -> n4.handle(left) [label:"是"]
  n3.handle(bottom) -> n5.handle(left) [label:"否"]
  n4.handle(right) -> n6.handle(left)
  n5.handle(right) -> n6.handle(left)
}

三车道示例

customer {
  n1: circle label:"开始"
  n2: rectangle label:"提交订单"
  n3: rectangle label:"收到订单"
  n4: circle label:"完成"
  n1.handle(right) -> n2.handle(left)
  n2.handle(bottom) -> n5.handle(top)
  n3.handle(right) -> n4.handle(left)
}

sales {
  n5: rectangle label:"审核订单"
  n6: diamond label:"批准订单？"
  n7: rectangle label:"处理订单"
  n5.handle(right) -> n6.handle(left)
  n6.handle(right) -> n7.handle(left) [label:"是"]
  n7.handle(bottom) -> n8.handle(top)
  n6.handle(top) -> n2.handle(right) [label:"否"]
}

fulfillment {
  n8: rectangle label:"发货"
  n9: diamond label:"已送达？"
  n10: rectangle label:"标记完成"
  n8.handle(right) -> n9.handle(left)
  n9.handle(right) -> n10.handle(left) [label:"是"]
  n10.handle(top) -> n3.handle(bottom)
  n9.handle(bottom) -> n8.handle(bottom) [label:"不，重试"]
}

完整cURL示例

1. 注册智能体

curl -X POST https://flowzap.xyz/api/agent/register   -H "Content-Type: application/json"   -d '{
    "name": "我的AI助手",
    "email": "my-assistant@agents.flowzap.xyz",
    "termsAccepted": true
  }'

2. 身份验证

curl -X POST https://flowzap.xyz/api/agent/auth   -H "Content-Type: application/json"   -d '{
    "apiToken": "您的api令牌"
  }'

3. 创建图表

curl -X POST https://flowzap.xyz/api/agent/diagrams   -H "Authorization: Bearer 您的jwt令牌"   -H "Content-Type: application/json"   -d '{
    "name": "客户入职",
    "projectId": "project-id",
    "colorScheme": "purple"
  }'

4. 创建Playground会话（公开URL）

curl -X POST https://flowzap.xyz/api/agent/playground   -H "Authorization: Bearer 您的jwt令牌"   -H "Content-Type: application/json"   -d '{
    "code": "planning {\n  n1: circle label:"Start"\n  n2: rectangle label:"Do Task"\n  n1.handle(right) -> n2.handle(left)\n}",
    "ttlDays": 7
  }'

SDK

安装

# Python
pip install flowzap

# JavaScript / TypeScript
npm install @flowzap/agent
# 或
pnpm add @flowzap/agent

Python 示例

from flowzap import FlowzapClient

client = FlowzapClient(base_url="https://flowzap.xyz", timeout_ms=10000, retries=3)

# 1) 注册
reg = client.register_agent(name="Acme Bot", email="bot@acme.com", terms_accepted=True)
api_token = reg["apiToken"]

# 2) 身份验证
auth = client.authenticate(api_token)
client.set_access_token(auth["accessToken"])  # 用于受保护的端点

# 3) 创建图表
created = client.create_diagram(name="支持流程", project_id="support-ops", color_scheme="slate")
print(created)

# 4) Playground 会话（公开URL，预填FlowZap Code）
pg = client.create_playground_session(code="""
lane: Support
node: Start
  text: User opens ticket
""")
print(pg["url"])

JavaScript / TypeScript 示例

import { FlowzapClient } from "@flowzap/agent";

const client = new FlowzapClient({ baseUrl: "https://flowzap.xyz", timeoutMs: 10000, retries: 3 });

// 1) 注册
const reg = await client.registerAgent({ name: "Acme Bot", email: "bot@acme.com", termsAccepted: true });
const apiToken = reg.apiToken;

// 2) 身份验证 -> 设置受保护端点的访问令牌
const auth = await client.authenticate({ apiToken });
client.setAccessToken(auth.accessToken);

// 3) 创建图表
const created = await client.createDiagram({ name: "支持流程", projectId: "support-ops", colorScheme: "slate" });
console.log(created);

// 4) Playground 会话（公开URL，预填FlowZap Code）
const pg = await client.createPlaygroundSession({ code: 'lane: Support
node: Start
  text: User opens ticket
' });
console.log(pg.url);

错误处理

• 400 — 验证错误（例如缺少必填字段）
• 401 — 令牌无效或已过期
• 403 — 拒绝访问（例如项目不可访问）
• 405 — 方法错误（对仅支持POST的端点发起GET）
• 409 — 冲突（例如邮箱已注册）
• 429 — 触发速率限制
• 500 — 服务器错误

工具JSON片段

OpenAI工具（创建Playground URL）

{
  "type": "function",
  "function": {
    "name": "flowzap_create_playground",
    "description": "创建一个预填FlowZap Code的未登录Playground URL。",
    "parameters": {
      "type": "object",
      "properties": {
        "code": { "type": "string", "description": "FlowZap Code内容" },
        "ttlDays": { "type": "integer", "minimum": 1, "maximum": 30 }
      },
      "required": ["code"]
    }
  }
}

Anthropic工具（创建Playground URL）

{
  "name": "flowzap_create_playground",
  "description": "创建一个预填FlowZap Code的未登录Playground URL。",
  "input_schema": {
    "type": "object",
    "properties": {
      "code": { "type": "string" },
      "ttlDays": { "type": "integer", "minimum": 1, "maximum": 30 }
    },
    "required": ["code"]
  }
}

最佳实践

• 安全性： 安全存储API令牌，永远不要在客户端代码中暴露它们
• 速率限制： 遵守速率限制（目前注册为每分钟10次请求）
• 归属： 分享图表时始终包含"Powered by FlowZap.xyz"
• 错误处理： 为所有API调用实现适当的错误处理
• 令牌管理： JWT令牌在15分钟后过期——根据需要刷新

支持与资源