API 文档
介绍
通过 Poco API 发起 Agent 对话、管理会话和产物，并读取发布页与 Office Mode 等更多数据服务。
Poco API 适合把 Agent 能力接入业务系统、机器人、自动化流程或数据平台。所有示例中的 https://<poco-host> 都需要替换为你的 Poco 的后端服务的访问地址。
先选择接口
| 需求 | 推荐接口 | 说明 |
|---|---|---|
| 使用 OpenAI SDK 或现有 OpenAI 客户端 | POST /openapi/v1/chat/completions | 请求和响应兼容 OpenAI Chat Completions 结构 |
| 使用 Messages 协议 | POST /openapi/v1/messages | 支持普通文本、附件、后台执行、SSE 和结构化输出 |
| 获取 API 会话及历史消息 | /openapi/v1/sessions/* | 当前用户且绑定当前具体 Key 的 API 会话 |
| 查询后台运行结果 | GET /openapi/v1/runs/{run_id} | 返回标准非流式 Message 结构和后台状态 |
| 获取整个会话或单轮运行的文件 | /openapi/v1/sessions/*/artifacts、/openapi/v1/runs/*/artifacts | 分别对应完整工作区和本轮变更 |
| 读取公开发布页 | /api/v1/public/publishes* | 无需鉴权，只返回公开数据 |
| 接入管理看板 | /api/v1/office-mode/* | 需要管理员创建的 admin scope API Key |
最小调用流程
- 在 Poco 的“API 访问”页面创建 API Key。
- 根据用途选择 Key 的生效范围和能力配置。
- 将 Key 保存在服务端密钥管理系统中。
- 调用对话接口并保存响应头中的
X-Session-Id和X-Run-Id。 - 需要连续追问时传入
metadata.session_id；需要文件时按会话或运行 ID 查询产物。
下面是一个最小的非流式请求：
curl -X POST 'https://<poco-host>/openapi/v1/messages' \
-H 'x-api-key: sk-xxxxxxxxxxxxxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{
"model": "poco-agent",
"stream": false,
"messages": [
{"role": "user", "content": "请生成一份今日工作总结模板。"}
]
}'通用行为
- 对话接口当前只使用
messages中最后一条role=user消息作为本轮输入。 system、developer、assistant、tool和function消息当前不会进入执行输入。stream=false返回完整 JSON；stream=true返回 SSE。background=true只支持stream=false，提交后通过运行结果端点轮询；普通请求行为保持不变。- 请求中的
model用于协议兼容和响应回显。实际执行模型按 API Key、绑定专家或团队及账号场景配置解析。 - 不传
metadata.session_id时通常新建，首次创建也支持幂等；续聊检查用户与绑定 Key。
阅读顺序
- 管理密钥与执行目标：阅读 API Key 管理。
- 响应人工问答：阅读 人工输入接口。
- 第一次接入：先阅读鉴权，再选择 OpenAI Chat Completions 或 Messages。
- 需要稳定 JSON：阅读结构化输出。
- 需要文件结果：阅读产物管理。
- 接入失败：根据错误处理定位状态码和错误类型。
如果你的系统不需要自己渲染对话 UI，可以直接把现成对话页面嵌入业务系统，参见 Agent 外部嵌入。如果需要 Poco 主动通知业务系统，参见 WebHook。