会话管理

查询 API 会话与历史消息，停止或删除会话，并读取会话能力配置。

会话接口用于管理通过 OpenAI Chat Completions 或 Messages 创建的 API 会话。API Key 只能访问所属用户的数据；已绑定 Key 的会话还必须使用同一 Key，即使同一账号也不能跨 Key 操作。

鉴权

推荐请求头：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx

也可使用 x-api-key: sk-...。

获取 API 会话列表

端点：GET /openapi/v1/sessions

查询参数	类型	默认值	范围	说明
`limit`	integer	`100`	`1-500`	本页最多返回多少条
`offset`	integer	`0`	大于等于 `0`	跳过多少条记录

接口只返回当前用户、kind=api 且 api_access_key_id 等于当前 Key 的会话，按 updated_at 降序、created_at 降序排列。

curl 'https://<poco-host>/openapi/v1/sessions?limit=20&offset=0' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx'

{
  "items": [
    {
      "session_id": "<session-uuid>",
      "title": "请帮我总结这个仓库",
      "status": "completed",
      "created_at": "2026-02-14T08:30:00Z",
      "updated_at": "2026-02-14T08:31:05Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

total 是满足条件的总数，不是当前页的条数。下一页的 offset 通常使用当前 offset + limit。

获取历史消息

端点：GET /openapi/v1/sessions/{session_id}/messages

返回会话历史消息以及每条消息关联的上传附件信息：

curl 'https://<poco-host>/openapi/v1/sessions/<session-uuid>/messages' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx'

{
  "session_id": "<session-uuid>",
  "messages": [
    {
      "id": 123,
      "role": "user",
      "text_preview": "你好",
      "content": { "_type": "UserMessage", "content": [] },
      "attachments": []
    }
  ]
}

text_preview 适合列表摘要；需要还原完整消息内容时读取 content。附件元数据位于 attachments。

查询后台运行结果

端点：GET /openapi/v1/runs/{run_id}

该端点只接受由 POST /openapi/v1/messages 的 background=true 创建的运行，并要求使用创建任务时的同一个 API Key。运行不存在或不是后台 Run 返回 404，其他 API Key 查询返回 403。

curl 'https://<poco-host>/openapi/v1/runs/<run-uuid>' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx'

查询始终返回 HTTP 200 的标准非流式 Message 结构，业务状态位于 background_results.status：

状态	说明	是否继续轮询
`queued`	已进入队列，尚未开始执行	是
`running`	已被 Worker 领取或正在执行	是
`finalizing`	Agent 已结束，正在同步最终消息和用量	是
`completed`	结果完整，可读取 `content` 或 `structured_output`	否
`failed`	执行失败或排队超时，查看 `error`	否
`canceled`	运行已取消	否
`incomplete`	最终结果同步不完整，查看 `error.retryable`	可有限重试

等待状态下，content=[]、stop_reason=null、用量为零，并返回 retry_after_ms=2000 与 Retry-After: 2。完成后会填充与普通非流式 Messages 相同的 content、stop_reason、usage 和可选 structured_output，同时保留 background_results：

{
  "id": "msg_<stable-run-message-id>",
  "type": "message",
  "role": "assistant",
  "content": [{ "type": "text", "text": "分析已完成。" }],
  "model": "poco-agent",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 123,
    "output_tokens": 456,
    "cache_creation_input_tokens": null,
    "cache_read_input_tokens": null
  },
  "structured_output": null,
  "background_results": {
    "session_id": "<session-uuid>",
    "run_id": "<run-uuid>",
    "status": "completed",
    "result_url": "/openapi/v1/runs/<run-uuid>",
    "retry_after_ms": null,
    "background_payload": "<original-base64-payload>",
    "error": null
  }
}

每个 Backend 实例内，单个 API Key 默认每秒最多查询 10 次；超过限制返回 HTTP 429、rate_limit_error 和 Retry-After: 1。多实例部署如需限制集群总查询频率，应在统一入口配置限流。客户端应优先使用 retry_after_ms 或 Retry-After 控制轮询间隔，不要并发高频查询同一个运行。

停止会话

端点：POST /openapi/v1/sessions/{session_id}/stop

不需要请求体：

curl -X POST 'https://<poco-host>/openapi/v1/sessions/<session-uuid>/stop' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx'

{
  "session_id": "<session-uuid>",
  "status": "stopped",
  "stop_state": "stopped",
  "termination_reason": "user_requested_stop",
  "cancelled_runs": 1,
  "expired_user_input_requests": 0,
  "executor_cancelled": true
}

stop_state 含义：

值	说明
`stopped`	执行器已经确认取消
`stopping`	会话已标记停止，仍在等待执行器确认
`already_stopped`	此前已经完成停止，不会重复发送停止事件
`not_running`	会话已完成或失败，没有正在执行的运行

取消请求进行中，或上次取消未确认后的 5 秒内，重复请求返回 200 和 stopping，不会重复修改数据或发送停止 WebHook。5 秒后再次调用只会重试执行器取消。

会话不存在返回 404；属于其他用户返回 403。

删除会话

端点：DELETE /openapi/v1/sessions/{session_id}

curl -X DELETE 'https://<poco-host>/openapi/v1/sessions/<session-uuid>' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx'

{
  "id": "<session-uuid>",
  "cleanup": { "scheduled": true }
}

删除会话后不能继续使用该 session_id 发起后续轮次。cleanup.scheduled=true 表示相关执行资源的清理由后台调度。

获取能力配置

端点：GET /openapi/v1/sessions/{session_id}/capability-config

用于确认本会话实际使用的浏览器、MCP、技能、连接器、插件和 Subagent 配置：

{
  "session_id": "<session-uuid>",
  "capability_config": {
    "browser_enabled": true,
    "browser_impl": "playwright_mcp",
    "mcp_server_ids": [1, 2],
    "skill_ids": [3],
    "connector_connection_ids": ["<connector-connection-uuid>"],
    "plugin_ids": [4],
    "subagent_ids": [5]
  }
}

该接口用于读取，不会修改当前会话的能力配置。连接器 ID 来自会话保存的能力配置；自由模式由 Key 配置提供，绑定专家或团队时由执行目标提供。每次运行都会重新校验连接状态并生成仅对当次运行有效的访问令牌。