OpenAPI

本文档介绍 bit-Agent OpenAPI 的使用方法，帮助开发者通过 API 集成 bit-Agent 的能力。

获取API-KEY

企业版租户的的管理员，可以在控制台上看到"API-KEY"的菜单，点进去即可创建 API-KEY。

可在当前页面看到租户 Code, 部分接口需要使用。

基础信息

Base URL: https://bitagent.ninetechone.com/api
所有接口均以 /v3/openapi 为前缀
请求/响应格式: JSON
认证方式: Bearer Token（通过 Authorization header 或 access_token query 参数传递）

统一响应格式

{
  "code": "200",
  "message": "",
  "data": ...
}

code: 响应状态码，"200" 表示成功
message: 错误时返回错误信息
data: 响应数据，具体结构因接口而异

完整场景示例：从认证到执行任务

以下示例串联了所有核心接口，演示一个完整的工作流：获取令牌 → 浏览能力 → 查看详情 → 创建任务 → 实时监控 → 获取结果。

Step 1: 获取访问令牌

curl -X POST '{{BASE_URL}}/v3/openapi/auth/user-token' \
  -H 'Authorization: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "user_001",
    "tenant_code": "my-tenant"
  }'

响应：

{
  "code": "200",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 86400
  }
}

后续所有接口都使用此 access_token 进行认证。该令牌基于传入的 user_id 生成，包含用户身份信息。持有此令牌的调用方将以该用户的身份执行所有操作，拥有与该用户完全相同的数据权限和操作权限。请妥善保管令牌，避免泄露。

Step 2: 查询可用能力列表

curl -X POST '{{BASE_URL}}/v3/openapi/ability/page' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "page_index": 0,
    "page_size": 10,
    "name": "数据抓取"
  }'

响应：

{
  "code": "200",
  "data": [
    {
      "id": "ability_001",
      "name": "网页数据抓取",
      "description": "自动抓取指定网页的数据并提取结构化信息",
      "created_by_id": "admin",
      "created_by_name": "管理员",
      "created_at": "2025-01-01T00:00:00"
    }
  ],
  "total": 1
}

Step 3: 查看能力详情（了解输入输出）

curl -X GET '{{BASE_URL}}/v3/openapi/ability/detail/ability_001' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...'

响应：

{
  "code": "200",
  "data": {
    "id": "ability_001",
    "name": "网页数据抓取",
    "description": "自动抓取指定网页的数据并提取结构化信息",
    "inputs": {
      "type": "object",
      "properties": {
        "url": { "type": "string", "description": "目标网址", "format": "uri" },
        "selector": { "type": "string", "description": "CSS选择器" }
      },
      "required": ["url"]
    },
    "outputs": {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "title": { "type": "string" },
              "price": { "type": "number" }
            }
          }
        }
      }
    },
    "config": {}
  }
}

inputs 定义了创建任务时需要传入的参数结构，outputs 定义了任务成功后的返回结构。

Step 4: （可选）查询可用 LLM 模型

curl -X GET '{{BASE_URL}}/v3/openapi/common/llm_names' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...'

响应：

{
  "code": "200",
  "data": ["Qwen", "GPT-4o", "DeepSeek-V3"]
}

Step 5: 创建任务

curl -X POST '{{BASE_URL}}/v3/openapi/task/create' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{
    "ability_id": "ability_001",
    "executor_type": "cloud",
    "inputs": {
      "url": "https://example.com",
      "selector": ".price"
    },
    "extensions": {
      "use_incognito": false,
      "skip_error": false,
      "close_browser": true,
      "llm_registry": "Qwen3"
    }
  }'

响应：

{
  "code": "200",
  "data": "task_12345"
}

返回的 data 即为任务 ID，用于后续查询和监控。

Step 6: 实时监控任务执行（SSE 流）

curl -N '{{BASE_URL}}/v3/openapi/task/stream/task_12345' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...'

服务端通过 SSE 持续推送事件：

event: step
data: {"step_id":"step_001","index":1,"activity_name":"打开浏览器","activity_icon":"🌐","purpose":"访问目标网页","status":"waiting"}

event: step-event
data: {"step_id":"step_001","status":"running","message":"正在加载页面..."}

event: thinking
data: 我需要先定位到价格元素...

event: step-event
data: {"step_id":"step_001","status":"ok"}

event: close
data: 关闭

Step 7: 获取任务结果

curl -X GET '{{BASE_URL}}/v3/openapi/task/detail/task_12345' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...'

响应：

{
  "code": "200",
  "data": {
    "id": "task_12345",
    "ability_id": "ability_001",
    "ability_name": "网页数据抓取",
    "executor_type": "cloud",
    "state": "success",
    "created_at": "2025-01-01T10:00:00",
    "started_at": "2025-01-01T10:00:01",
    "ended_at": "2025-01-01T10:02:25",
    "duration": 145,
    "inputs": { "url": "https://example.com", "selector": ".price" },
    "outputs": {
      "data": [
        { "product": "商品A", "price": 99.99 },
        { "product": "商品B", "price": 149.0 }
      ]
    }
  }
}

Step 8: （可选）取消正在执行的任务

curl -X POST '{{BASE_URL}}/v3/openapi/task/cancel/task_12345' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...'

接口详细说明

1. 认证

POST /v3/openapi/auth/user-token

创建用户访问令牌。该令牌用于后续所有 OpenAPI 接口的身份验证。

请求头：

参数	类型	必填	说明
Authorization	string	是	API Key，用于验证调用方身份

请求体：

参数	类型	必填	说明
user_id	string	是	用户唯一标识符（1-128字符）
tenant_code	string	是	租户唯一标识符（1-128字符）

响应 data：

字段	类型	说明
access_token	string	JWT 访问令牌
token_type	string	固定为 `Bearer`
expires_in	integer \| null	过期时间（秒），null 表示永不过期

错误码：

401: API Key 无效或缺失
403: 租户不匹配
400: user_id 或 tenant_code 格式不正确

2. 能力管理

POST /v3/openapi/ability/page

分页查询能力列表，支持按名称模糊搜索。

请求体：

参数	类型	必填	默认值	说明
page_index	integer	否	0	页码（从 0 开始）
page_size	integer	否	10	每页数量（最大 100）
name	string	否	-	名称模糊匹配

响应 data（数组）：

字段	类型	说明
id	string	能力 ID
name	string	能力名称
description	string \| null	能力描述
created_by_id	string	创建人 ID
created_by_name	string	创建人名称
created_at	datetime	创建时间

响应还包含 total 字段表示数据总数。

GET /v3/openapi/ability/detail/{ability_id}

获取能力的完整详情，包括输入输出定义和配置参数。创建任务前应先调用此接口了解需要提供哪些输入参数。

路径参数：

参数	类型	必填	说明
ability_id	string	是	能力 ID

响应 data：

字段	类型	说明
id	string	能力 ID
name	string	能力名称
description	string \| null	能力描述
inputs	object	输入参数定义（JSON Schema 格式）
outputs	object	输出参数定义（JSON Schema 格式）
config	object	能力配置参数

3. 通用服务

GET /v3/openapi/common/llm_names

获取当前用户可用的 LLM 模型名称列表。返回的名称可在创建任务时通过 extensions.llm_registry 指定。

响应 data： string[] — LLM 名称数组

GET /v3/openapi/common/file/{file_id}

根据文件 ID 获取文件元信息（文件名、下载链接）。

路径参数：

参数	类型	必填	说明
file_id	string	是	文件 ID

响应 data：

字段	类型	说明
name	string \| null	文件名
url	string \| null	文件下载链接

POST /v3/openapi/common/file/upload

上传文件。使用 multipart/form-data 格式。

请求体：

参数	类型	必填	说明
file	binary	是	要上传的文件

curl -X POST '{{BASE_URL}}/v3/openapi/common/file/upload' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...' \
  -F 'file=@/path/to/file.xlsx'

响应 data： object — 键值对，包含上传后的文件信息

4. 任务管理

POST /v3/openapi/task/create

创建任务并返回任务 ID。支持客户端执行（client）和云端执行（cloud）两种模式。

请求体：

参数	类型	必填	说明
ability_id	string	是	要执行的能力 ID
executor_type	string	是	执行器类型：`client`（本地客户端）或 `cloud`（云端）
executor_id	string	否	执行器 ID，仅 `executor_type=client` 时生效。client_id 可以在设置中查看。不填则默认发给最近在线的客户端。
inputs	object	否	输入参数，需符合能力定义的 inputs schema
extensions	object	否	扩展配置（见下表）

extensions 字段：

参数	类型	默认值	说明
use_incognito	boolean	false	是否使用浏览器无痕模式
skip_error	boolean	false	是否忽略步骤错误继续执行
close_browser	boolean	false	任务结束后是否关闭浏览器
llm_registry	string \| null	null	指定 LLM 模型名称，不填使用默认模型

响应 data： string — 任务 ID

GET /v3/openapi/task/detail/{task_id}

获取任务详情，包括执行状态、输入输出、时间统计等。

路径参数：

参数	类型	必填	说明
task_id	string	是	任务 ID

响应 data：

字段	类型	说明
id	string	任务 ID
ability_id	string	关联的能力 ID
ability_name	string	能力名称（创建时快照）
executor_type	string	执行器类型
executor_id	string \| null	执行器 ID
state	string	任务状态：`pending` / `running` / `success` / `failed` / `cancelled`/ `paused`/ `terminated`
error_message	string \| null	错误信息（仅 `failed` 状态）
created_by	object	创建人信息（含 id、name）
created_at	datetime	创建时间
started_at	datetime \| null	开始时间
ended_at	datetime \| null	结束时间
duration	integer \| null	运行时长（秒）
inputs	object	输入参数（快照）
outputs	object \| null	输出结果（仅 `success` 状态）
extensions	object	扩展配置（快照）
aux_infos	object	辅助信息（能力元数据快照）

POST /v3/openapi/task/cancel/{task_id}

取消正在执行或等待执行的任务。已完成、已失败或已取消的任务无法再次取消。

路径参数：

参数	类型	必填	说明
task_id	string	是	任务 ID

响应 data： string — 操作结果

GET /v3/openapi/task/stream/{task_id}

通过 SSE（Server-Sent Events）实时获取任务执行过程。连接建立后，服务端持续推送步骤状态直到任务完成。

路径参数：

参数	类型	必填	说明
task_id	string	是	任务 ID

事件类型：

事件名	说明	data 格式
`step`	步骤创建	`{"step_id", "index", "activity_name", "activity_icon", "purpose", "status"}`
`step-event`	步骤更新	`{"step_id", "status", "message", "screenshots", "outputs", "datas", "files", "labels"}`
`thinking`	思考过程	纯文本
`message`	LLM 消息	纯文本
`error`	错误事件	纯文本
`card`	卡片展示	`{"title", "style", "body", "actions"}`
`close`	关闭连接	纯文本

步骤状态枚举： waiting → running → ok / fail / abandoned

GET /v3/openapi/task/space_view

获取任务的空间视图信息，包含文件、备忘录和步骤树。

Query 参数：

参数	类型	必填	说明
task_id	string	是	任务 ID

响应 data：

字段	类型	说明
files	array	文件列表（含 id、origin、name、desc、text_content）
memos	array	备忘录列表（含 id、type、content）
steps	array	步骤树节点列表

5. 会话管理

POST /v3/openapi/session/create

创建一个新的会话。

请求体：

参数	类型	必填	说明
client_id	string	是	客户端 ID

响应 data： string — 会话 ID

POST /v3/openapi/session/chat

在会话中发送消息（SSE 流式响应）。

请求体：

参数	类型	必填	说明
session_id	string	是	会话 ID
client_id	string	是	客户端 ID
text	string \| null	否	文本内容
files	string[] \| null	否	文件 ID 列表

GET /v3/openapi/session/space_view

获取会话的空间视图信息。

Query 参数：

参数	类型	必填	说明
session_id	string	是	会话 ID

响应 data： 同任务 space_view，包含 files、memos、steps。

获取API-KEY​

基础信息​

统一响应格式​

完整场景示例：从认证到执行任务​

Step 1: 获取访问令牌​

Step 2: 查询可用能力列表​

Step 3: 查看能力详情（了解输入输出）​

Step 4: （可选）查询可用 LLM 模型​

Step 5: 创建任务​

Step 6: 实时监控任务执行（SSE 流）​

Step 7: 获取任务结果​

Step 8: （可选）取消正在执行的任务​

接口详细说明​

1. 认证​

POST /v3/openapi/auth/user-token​

2. 能力管理​

POST /v3/openapi/ability/page​

GET /v3/openapi/ability/detail/{ability_id}​

3. 通用服务​

GET /v3/openapi/common/llm_names​

GET /v3/openapi/common/file/{file_id}​

POST /v3/openapi/common/file/upload​

4. 任务管理​

POST /v3/openapi/task/create​

GET /v3/openapi/task/detail/{task_id}​

POST /v3/openapi/task/cancel/{task_id}​

GET /v3/openapi/task/stream/{task_id}​

GET /v3/openapi/task/space_view​

5. 会话管理​

POST /v3/openapi/session/create​

POST /v3/openapi/session/chat​

GET /v3/openapi/session/space_view​

获取API-KEY

基础信息

统一响应格式

完整场景示例：从认证到执行任务

Step 1: 获取访问令牌

Step 2: 查询可用能力列表

Step 3: 查看能力详情（了解输入输出）

Step 4: （可选）查询可用 LLM 模型

Step 5: 创建任务

Step 6: 实时监控任务执行（SSE 流）

Step 7: 获取任务结果

Step 8: （可选）取消正在执行的任务

接口详细说明

1. 认证

POST /v3/openapi/auth/user-token

2. 能力管理

POST /v3/openapi/ability/page

GET /v3/openapi/ability/detail/{ability_id}

3. 通用服务

GET /v3/openapi/common/llm_names

GET /v3/openapi/common/file/{file_id}

POST /v3/openapi/common/file/upload

4. 任务管理

POST /v3/openapi/task/create

GET /v3/openapi/task/detail/{task_id}

POST /v3/openapi/task/cancel/{task_id}

GET /v3/openapi/task/stream/{task_id}

GET /v3/openapi/task/space_view

5. 会话管理

POST /v3/openapi/session/create

POST /v3/openapi/session/chat

GET /v3/openapi/session/space_view