API 与 WebHook

通过 API 创建会话，并用 WebHook 把执行结果推送到外部系统。

Poco 支持把 Agent 能力接入外部系统。常见方式有两种：外部系统通过 API 发起任务，Poco 通过 WebHook 把事件推回外部系统。

如果你只是想在业务系统里“发起一个任务并拿到结果”，先看 API；如果你希望 Poco 在任务完成、失败、请求人工输入或发布页面时主动通知系统，配置 WebHook。

API 访问

在“API 访问”页面创建密钥后，可通过兼容接口发起对话任务。

创建密钥时建议配置：

配置	建议
名称	写清楚用途，例如“飞书机器人测试”
生效范围	普通对话选“对话”范围
过期时间	临时测试不要设置永久有效
能力配置	按需绑定 MCP、Skills、Subagents、插件
浏览器	只有网页任务才开启

API Key 应按业务系统拆分，不要多个系统共用同一个 Key。生产 Key 建议设置明确用途、合理过期时间和最小能力范围。

调用示例：

curl -X POST http://localhost:8000/openapi/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "poco-agent",
    "stream": false,
    "messages": [
      {
        "role": "user",
        "content": "请生成一份今日工作总结模板。"
      }
    ]
  }'

更多协议细节见 API 文档。

会话复用

外部系统可以通过 metadata.session_id 继续同一个会话。适合：

在同一个工单里连续追问。
基于上一次产物继续补充。
让业务系统保留一次任务的上下文。

不适合复用的场景：

用户已经换了完全不同的问题。
需要新的仓库、能力或权限。
上一轮上下文明显错误。

如果不传 session_id，Poco 会创建新会话。

附件和文件

API 支持文本、图片和文件输入。文件更适合提供材料，不适合直接作为最终产物。需要交付文件时，请在提示词里明确要求 Poco Agent 写入工作区文件，例如：

请读取附件中的需求文档，并生成 `delivery-plan.md`。

WebHook

WebHook 用于订阅事件，并把事件推送到你的 HTTP 地址。适合：

会话完成后通知业务系统。
定时任务失败后触发告警。
发布页生成后同步到内容平台。
用户输入请求出现时通知人工处理。

常见事件：

事件	说明
`session.completed`	会话成功完成
`session.failed`	会话失败
`session.stopped`	会话被停止
`scheduled_task.run_status_changed`	定时任务运行状态变化
`user_input.requested`	Agent 请求用户输入
`publish_page.published`	发布页成功发布
`workspace_export.completed`	工作区文件导出完成

配置 WebHook

建议按下面顺序配置：

填写名称和推送地址。
选择订阅事件。
选择生效范围：全局或指定项目。
如只关心某类会话，配置会话类型过滤。
配置签名密钥。
设置超时、重试次数和退避时间。
使用测试推送验证接收端。

签名密钥建议始终配置。接收端应校验 X-Poco-Signature，避免伪造请求。

事件过滤建议：

只关心某个项目时，使用项目范围。
只关心定时任务时，选择 scheduled 会话类型。
需要拿到文件清单或归档信息时，订阅 workspace_export.completed，不要只订阅 session.completed。
需要处理人工输入时，同时订阅 user_input.requested 和 user_input.answered。

接收端示例

from fastapi import FastAPI, Request

app = FastAPI()


@app.post("/poco/webhook")
async def poco_webhook(request: Request) -> dict[str, str]:
    event_type = request.headers.get("X-Poco-Event")
    payload = await request.json()

    if event_type == "session.completed":
        session = payload.get("session", {})
        print("session completed:", session.get("title"))

    return {"status": "ok"}

生产环境必须补充签名校验、幂等处理和错误日志。

Webhook 接收端要快速返回。建议收到事件后先校验签名、记录 event_id，再把耗时业务放入自己的异步队列。不要在 WebHook 请求里直接执行长任务。

使用技巧

API Key 只在创建时完整展示，创建后立即保存到安全位置。
测试用 Key 设置短过期时间，生产 Key 按系统拆分用途。
WebHook 接收端要快速返回，耗时处理放到异步队列。
外部系统收到失败事件后，不要盲目无限重试，应结合事件 ID 做幂等。
详细事件结构见 WebHook 文档。
需要文件结果时，等 workspace_export.completed 后再读取工作区文件。
需要公开页面结果时，订阅 publish_page.published，它比会话完成事件更贴近发布结果。