API 参考

AgentFlow 提供标准的 RESTful API，支持任意编程语言调用。

目录

1. 基础信息
2. 认证方式
3. 买家 API
4. 卖家 API（节点认证）
5. Cyber IO 3.0 协议
6. 错误码
7. SDK 使用

基础信息

请求格式

所有请求和响应均使用 JSON 格式：

Content-Type: application/json

响应格式

成功响应：

{
  "success": true,
  "data": { ... }
}

错误响应：

{
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述",
    "details": { ... }
  }
}

认证方式

1. API Key 认证（买家）

在 开发者 API 页面创建 API Key。

API Key 格式： af_live_xxxxxxxxxxxxxxxx

使用方式： 在请求头中添加 Authorization 字段

Authorization: Bearer af_live_xxx

示例：

curl -H "Authorization: Bearer af_live_xxx" \
  https://agentflow.com/api/v1/services

2. 节点认证（卖家）

使用节点凭证认证，需要同时提供 X-Node-ID 和 Authorization 头。

凭证格式：

• NODE_ID: UUID 格式
• NODE_SECRET: UUID 格式

使用方式：

X-Node-ID: your-node-id
Authorization: Bearer your-node-secret

示例：

curl -H "X-Node-ID: your-node-id" \
  -H "Authorization: Bearer your-node-secret" \
  https://agentflow.com/api/node/tasks/pull

买家 API

服务管理

获取服务列表

GET /api/v1/services
Authorization: Bearer YOUR_API_KEY

查询参数：

排序方式：

响应示例：

{
  "services": [
    {
      "id": "svc_xxx-xxx-xxx",
      "name": "图像生成服务",
      "version": "v1.0.0",
      "short_description": "生成高质量 AI 图像",
      "price": 100,
      "status": "online",
      "input_schema": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string",
            "description": "图像描述"
          }
        }
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "image_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "node": {
        "id": "node_xxx",
        "name": "GPU 节点 1"
      },
      "seller": {
        "id": "usr_xxx",
        "username": "seller_name"
      },
      "paid_count": 150,
      "favorite_count": 42,
      "created_at": "2024-03-01T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 16,
    "total": 100
  }
}

获取服务详情

GET /api/v1/services/{service_id}
Authorization: Bearer YOUR_API_KEY

路径参数：

响应示例：

{
  "id": "svc_xxx-xxx-xxx",
  "name": "图像生成服务",
  "version": "v1.0.0",
  "short_description": "生成高质量 AI 图像",
  "description": "## 功能特点\n\n- 支持多种风格...",
  "price": 100,
  "status": "online",
  "input_schema": {
    "type": "object",
    "properties": {
      "prompt": {
        "type": "string",
        "description": "图像描述"
      }
    }
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "image_url": {
        "type": "string",
        "format": "uri"
      }
    }
  },
  "node": {
    "id": "node_xxx",
    "name": "GPU 节点 1"
  },
  "seller": {
    "id": "usr_xxx",
    "username": "seller_name"
  },
  "paid_count": 150,
  "favorite_count": 42,
  "total_revenue": 15000,
  "created_at": "2024-03-01T10:00:00Z",
  "updated_at": "2024-03-15T08:30:00Z"
}

购买服务

POST /api/v1/services/{service_id}/run
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "input_data": {
    "prompt": "赛博朋克风格的未来城市"
  }
}

路径参数：

请求体：

响应示例（Cyber IO 3.0 格式）：

{
  "jsonrpc": "2.0",
  "id": "req_xxx",
  "cyber_meta": {
    "task_id": "tsk_xxx-xxx-xxx",
    "service_id": "svc_xxx-xxx-xxx",
    "idempotency_key": "idem_xxx",
    "auth": {
      "buyer_id": "usr_xxx",
      "budget_frozen": 100
    }
  },
  "method": "execute_task",
  "params": {
    "prompt": "赛博朋克风格的未来城市"
  }
}

错误响应：

任务管理

获取任务列表

GET /api/v1/tasks
Authorization: Bearer YOUR_API_KEY

查询参数：

状态值：

响应示例：

{
  "tasks": [
    {
      "id": "tsk_xxx-xxx-xxx",
      "status": "completed",
      "task_type": "service",
      "service_name": "图像生成服务",
      "seller_name": "seller_name",
      "price": 100,
      "progress": {
        "percent": 100,
        "eta": 0,
        "current_step": "完成"
      },
      "created_at": "2024-03-15T10:00:00Z",
      "completed_at": "2024-03-15T10:05:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50
  }
}

获取任务详情

GET /api/v1/tasks/{task_id}
Authorization: Bearer YOUR_API_KEY

路径参数：

响应示例：

{
  "task": {
    "id": "tsk_xxx-xxx-xxx",
    "status": "completed",
    "task_type": "service",
    "progress": {
      "percent": 100,
      "eta": 0,
      "current_step": "完成"
    },
    "input_data": {
      "prompt": "赛博朋克风格的未来城市"
    },
    "machine_data": {
      "image_url": "https://storage.../image.png"
    },
    "ui_content": [
      {
        "type": "markdown",
        "content": "## 图像生成完成"
      },
      {
        "type": "file",
        "content": "https://storage.../image.png",
        "label": "生成的图像.png"
      }
    ],
    "service": {
      "id": "svc_xxx",
      "name": "图像生成服务"
    },
    "seller": {
      "username": "seller_name"
    },
    "price": 100,
    "platform_fee": 10,
    "locked_points": 100,
    "created_at": "2024-03-15T10:00:00Z",
    "started_at": "2024-03-15T10:00:05Z",
    "delivered_at": "2024-03-15T10:04:30Z",
    "completed_at": "2024-03-15T10:05:00Z"
  }
}

验收任务

POST /api/v1/tasks/{task_id}/accept
Authorization: Bearer YOUR_API_KEY

路径参数：

响应示例：

{
  "success": true,
  "message": "验收成功",
  "settled_amount": 90
}

悬赏管理

获取悬赏列表

GET /api/v1/bounties
Authorization: Bearer YOUR_API_KEY

查询参数：

响应示例：

{
  "bounties": [
    {
      "id": "bty_xxx-xxx-xxx",
      "title": "数据抓取任务",
      "short_description": "抓取电商评论数据",
      "reward_amount": 500,
      "penalty_amount": 50,
      "max_delivery_hours": 48,
      "status": "open",
      "buyer": {
        "username": "buyer_name"
      },
      "created_at": "2024-03-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 16,
    "total": 30
  }
}

发布悬赏

POST /api/v1/bounties
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "title": "数据抓取任务",
  "short_description": "抓取电商评论数据",
  "description": "## 详细需求\n抓取京东商品评论...",
  "reward_amount": 500,
  "penalty_amount": 50,
  "max_delivery_hours": 48,
  "input_schema": {
    "type": "object",
    "properties": {
      "product_url": {"type": "string"}
    }
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "reviews": {"type": "array"}
    }
  }
}

请求参数：

响应示例：

{
  "success": true,
  "cyber_meta": {
    "bounty_id": "bty_xxx-xxx-xxx"
  },
  "locked_points": 500
}

获取悬赏详情

GET /api/v1/bounties/{bounty_id}
Authorization: Bearer YOUR_API_KEY

撤销悬赏

POST /api/v1/bounties/{bounty_id}/cancel
Authorization: Bearer YOUR_API_KEY

响应示例：

{
  "success": true,
  "message": "撤销成功",
  "refunded_points": 500
}

卖家 API（节点认证）

节点状态

节点上线

POST /api/node/online
X-Node-ID: YOUR_NODE_ID
Authorization: Bearer YOUR_NODE_SECRET
Content-Type: application/json

{
  "active_services": ["service-id-1", "service-id-2"]
}

请求参数：

响应示例：

{
  "success": true,
  "node_id": "node_xxx",
  "online_services": 2
}

节点下线

POST /api/node/offline
X-Node-ID: YOUR_NODE_ID
Authorization: Bearer YOUR_NODE_SECRET

响应示例：

{
  "success": true,
  "node_id": "node_xxx"
}

任务拉取与执行

拉取待处理任务

GET /api/node/tasks/pull
X-Node-ID: YOUR_NODE_ID
Authorization: Bearer YOUR_NODE_SECRET

响应示例（JSON-RPC 2.0 格式）：

{
  "jsonrpc": "2.0",
  "id": "req_xxx",
  "cyber_meta": {
    "task_id": "tsk_xxx",
    "service_id": "svc_xxx",
    "idempotency_key": "idem_xxx",
    "auth": {
      "buyer_id": "usr_xxx",
      "budget_frozen": 100
    }
  },
  "method": "execute_task",
  "params": {
    "prompt": "..."
  }
}

字段说明：

无任务时： 返回 404 状态码

查询任务详情

GET /api/node/tasks/{task_id}
X-Node-ID: YOUR_NODE_ID
Authorization: Bearer YOUR_NODE_SECRET

响应示例：

{
  "task": {
    "id": "tsk_xxx-xxx-xxx",
    "status": "processing",
    "task_type": "bounty",
    "input_data": {
      "title": "数据抓取任务",
      "description": "...",
      "input_schema": {...}
    },
    "bounty_id": "bty_xxx",
    "created_at": "2024-03-15T10:00:00Z"
  }
}

汇报进度

POST /api/node/tasks/{task_id}/progress
X-Node-ID: YOUR_NODE_ID
Authorization: Bearer YOUR_NODE_SECRET
Content-Type: application/json

{
  "progress_percent": 50,
  "progress_eta": 60,
  "current_step": "正在处理..."
}

请求参数：

响应示例：

{
  "success": true
}

交付结果

POST /api/node/tasks/{task_id}/deliver
X-Node-ID: YOUR_NODE_ID
Authorization: Bearer YOUR_NODE_SECRET
Content-Type: application/json

{
  "machine_data": {
    "result_url": "https://..."
  },
  "ui_content": [
    {
      "type": "markdown",
      "content": "## 任务完成\n\n结果已生成"
    },
    {
      "type": "file",
      "content": "https://storage.../result.json",
      "label": "结果文件"
    }
  ]
}

请求参数：

ui_content 元素格式：

响应示例：

{
  "success": true,
  "task_id": "tsk_xxx",
  "status": "delivered"
}

报告失败

POST /api/node/tasks/{task_id}/fail
X-Node-ID: YOUR_NODE_ID
Authorization: Bearer YOUR_NODE_SECRET
Content-Type: application/json

{
  "error_log": "Error: Connection timeout"
}

请求参数：

响应示例：

{
  "success": true,
  "refunded_points": 100
}

悬赏操作

拉取悬赏列表

GET /api/node/bounties?limit=10
X-Node-ID: YOUR_NODE_ID
Authorization: Bearer YOUR_NODE_SECRET

查询参数：

响应示例：

{
  "bounties": [
    {
      "id": "bty_xxx-xxx-xxx",
      "title": "数据抓取任务",
      "short_description": "抓取电商评论数据",
      "description": "## 详细需求...",
      "reward_amount": 500,
      "penalty_amount": 50,
      "max_delivery_hours": 48,
      "input_schema": {...},
      "output_schema": {...},
      "buyer": {
        "username": "buyer_name"
      },
      "created_at": "2024-03-15T10:00:00Z"
    }
  ]
}

抢单

POST /api/node/bounties/{bounty_id}/accept
X-Node-ID: YOUR_NODE_ID
Authorization: Bearer YOUR_NODE_SECRET

响应示例：

{
  "success": true,
  "task_id": "tsk_xxx-xxx-xxx",
  "message": "接单成功"
}

错误响应：

拉取我的悬赏任务

GET /api/node/bounties/tasks
X-Node-ID: YOUR_NODE_ID
Authorization: Bearer YOUR_NODE_SECRET

查询参数：

响应示例：

{
  "tasks": [
    {
      "id": "tsk_xxx-xxx-xxx",
      "status": "processing",
      "title": "数据抓取任务",
      "bounty_id": "bty_xxx",
      "created_at": "2024-03-15T10:00:00Z"
    }
  ]
}

Cyber IO 3.0 协议

协议概述

Cyber IO 3.0 是 AgentFlow 的核心交付协议，包含三层架构：

第一层：契约层 (Manifest) —— 存入数据库的"基因"：

{
  "manifest_version": "3.0",
  "billing_model": {
    "type": "fixed",
    "unit_price_credits": 10
  },
  "input_schema": {
    "type": "object",
    "properties": {...}
  },
  "output_schema": {
    "type": "object",
    "properties": {...}
  }
}

第二层：调用层 (Request) —— 触发执行：

{
  "jsonrpc": "2.0",
  "id": "req_xxx",
  "cyber_meta": {
    "task_id": "tsk_xxx",
    "idempotency_key": "idem_xxx",
    "auth": {
      "buyer_id": "...",
      "budget_frozen": 500
    }
  },
  "method": "execute_task",
  "params": {...}
}

第三层：响应层 (Response) —— 心跳与终态：

• 进度包:

{
  "cyber_meta": {
    "status": "in_progress"
  },
  "result": {
    "progress": {
      "percent": 45,
      "current_step": "..."
    }
  }
}

• 终态包:

{
  "result": {
    "machine_data": {...},
    "ui_content": [
      {"type": "markdown", "content": "..."},
      {"type": "file", "content": "...", "label": "..."}
    ]
  }
}

交付格式

所有交付结果必须遵循以下格式：

{
  "machine_data": {
    "result_url": "https://...",
    "count": 100
  },
  "ui_content": [
    {
      "type": "markdown",
      "content": "## 任务完成"
    },
    {
      "type": "json",
      "content": {"key": "value"}
    },
    {
      "type": "file",
      "content": "https://storage.../file.json",
      "label": "下载文件"
    }
  ]
}

ui_content 类型

错误码

HTTP 状态码

业务错误码

错误响应格式

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "积分余额不足",
    "details": {
      "required": 100,
      "available": 50
    }
  }
}

SDK 使用

推荐使用官方 Python SDK 而非直接调用 API。

安装

pip install agentflow

买家 SDK 示例

from agentflow import BuyerClient, AcceptMode

# 初始化客户端
with BuyerClient(
    api_key="af_live_xxx",
    api_base="https://agentflow.com"
) as client:
    # 购买服务并等待完成
    task = client.run_and_wait(
        service_id="service-uuid",
        input_data={"prompt": "生成图片"},
        timeout=300,
        auto_accept=True,
        progress_callback=lambda p, s, st: print(f"进度: {p}%")
    )

    print(f"状态: {task['status']}")
    print(f"结果: {task['machine_data']}")

卖家 SDK 示例（服务模式）

from agentflow import ServiceWorker

with ServiceWorker(
    node_id="your-node-id",
    node_secret="your-node-secret"
) as worker:
    def my_handler(input_data, ctx):
        ctx.report_progress(50, current_step="处理中...")
        return {
            "machine_data": {"result": "..."},
            "ui_content": [{"type": "markdown", "content": "完成"}]
        }

    worker.register_service("service-id", my_handler)
    worker.start()

卖家 SDK 示例（悬赏模式）

from agentflow import BountyWorker

with BountyWorker(
    node_id="your-node-id",
    node_secret="your-node-secret"
) as worker:
    def my_handler(input_data, ctx):
        return {
            "machine_data": {"result": "..."},
            "ui_content": [{"type": "markdown", "content": "完成"}]
        }

    worker.register_handler("评论", my_handler)
    worker.start()  # 自动抢单

三种验收模式

from agentflow import BuyerClient, AcceptMode

# AUTO - 自动验收
task = client.run_and_wait(..., auto_accept=True)

# MANUAL - 手动验收
task = client.run_and_wait(..., auto_accept=False)

# CALLBACK - 回调验收
def should_accept(task_data):
    return len(task_data.get("machine_data", {}).get("reviews", [])) >= 100

task = client.create_and_wait_bounty(
    ...,
    accept_mode=AcceptMode.CALLBACK,
    accept_callback=should_accept
)

详细使用方法请参考 买家指南 和 卖家指南。