agent-Specialization/api_doc/messages_tasks.md

发送消息与任务系统（后台运行 + 轮询）

本节覆盖：

• 创建对话（可选）：POST /api/v1/conversations
• 发送消息（创建后台任务）：POST /api/v1/messages
• 轮询事件：GET /api/v1/tasks/<task_id>
• 停止任务：POST /api/v1/tasks/<task_id>/cancel

1) 创建对话

POST /api/v1/conversations

创建一个新的对话，并返回 conversation_id。

请求：

• Headers：Authorization: Bearer <TOKEN>
• Body：无

响应（200）：

{
  "success": true,
  "conversation_id": "conv_20260123_234245_036"
}

可能错误：

• 401：缺少或无效 token
• 503：系统未初始化（资源繁忙/容器不可用等）
• 500：创建失败

2) 发送消息（创建后台任务）

POST /api/v1/messages

创建一个后台任务执行智能体流程，并立即返回 task_id。

请求

Headers：

• Authorization: Bearer <TOKEN>
• Content-Type: application/json

Body(JSON)：

字段	类型	必填	说明
message	string	是（或 images）	用户消息文本；message 与 images 至少其一不为空
conversation_id	string	否	不传则自动新建对话；建议显式传入以便客户端管理会话
model_key	string/null	否	指定模型 key（可选）；具体可用值取决于服务端配置
run_mode	string/null	否	运行模式："fast" | "thinking" | "deep"；若传入则优先使用
thinking_mode	boolean/null	否	兼容字段：true=thinking，false=fast；当 run_mode 为空时才使用
max_iterations	integer/null	否	最大迭代次数，默认服务端配置为 100（config.MAX_ITERATIONS_PER_TASK）；传入可覆盖
images	string[]	否	图片路径列表（服务端可访问的路径）；一般配合特定模型使用

优先级：run_mode > thinking_mode > 终端当前配置。run_mode="deep" 将启用深度思考模式（若模型与配置允许）。

响应

成功（202）：

{
  "success": true,
  "task_id": "60322db3-f884-4a1e-a9b3-6eeb07fbab47",
  "conversation_id": "conv_20260123_234245_036",
  "status": "running",
  "created_at": 1769182965.3038778
}

字段说明：

• task_id：任务唯一 ID（用于轮询/停止）
• conversation_id：本次任务归属对话
• status：初始为 running
• created_at：UNIX 时间戳（秒，float）

可能错误：

• 400：message/images 都为空；或 conversation_id 无法加载
• 401：缺少或无效 token
• 409：该 API 用户已有运行中的任务（禁止并发）
• 503：系统未初始化/资源繁忙

并发冲突示例（409）：

{ "success": false, "error": "已有运行中的任务，请稍后再试。" }

3) 轮询任务事件（增量）

GET /api/v1/tasks/<task_id>?from=<offset>

用于以 HTTP 轮询方式获取任务执行过程中的流式事件（与 WebSocket 同粒度）。

请求

• Headers：Authorization: Bearer <TOKEN>
• Query：
  • from：起始 offset（默认 0）

响应（200）

{
  "success": true,
  "data": {
    "task_id": "60322db3-f884-4a1e-a9b3-6eeb07fbab47",
    "status": "running",
    "created_at": 1769182965.30,
    "updated_at": 1769182968.15,
    "error": null,
    "events": [
      { "idx": 0, "type": "ai_message_start", "data": {}, "ts": 1769182965.30 },
      { "idx": 1, "type": "text_start", "data": {}, "ts": 1769182968.09 },
      { "idx": 2, "type": "text_chunk", "data": { "content": "我来", "index": 1, "elapsed": 0.0 }, "ts": 1769182968.15 }
    ],
    "next_offset": 3
  }
}

字段说明：

• status：任务状态，常见值：
  • running：执行中
  • cancel_requested：已请求停止，等待实际停下
  • canceled：已停止
  • succeeded：成功结束
  • failed：失败结束（error 会给出原因）
• events：从 idx>=from 的事件列表（按 idx 升序）
• next_offset：建议下一次轮询的 from 值

可能错误：

• 401：缺少或无效 token
• 404：任务不存在（或不属于该 API 用户）

推荐轮询策略

• 轮询间隔：0.5s ~ 2s（任务越密集越推荐更快）
• 客户端必须：
  1. 保存 next_offset
  2. 追加处理 events
  3. 当 status != running 时停止轮询

重要：服务端事件缓冲是 deque(maxlen=1000)，轮询过慢会丢失早期事件；客户端应自行落盘你需要的内容。

4) 停止任务

POST /api/v1/tasks/<task_id>/cancel

请求停止某个任务。

请求：

• Headers：Authorization: Bearer <TOKEN>
• Body：无

成功（200）：

{ "success": true }

说明：

• 该接口是“请求停止”，任务可能不会立刻停下；
• 停止后的最终状态在轮询里体现：status 变为 canceled 或 failed/succeeded（极少数情况下已接近结束）。

可能错误：

• 401：缺少或无效 token
• 404：任务不存在