外部集成快速开始

Poco 提供三种外部集成方式：API 用于由业务系统发起 Agent 任务；WebHook 用于把异步事件主动推送给业务系统；Agent 外部嵌入用于直接复用现成对话界面。

需求	选择
业务系统发起任务，并自己处理请求与响应	API
Poco 在任务完成、失败、请求输入或发布页面时主动通知系统	WebHook
在业务页面直接展示完整对话、历史记录和产物预览	Agent 外部嵌入

API 访问

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

创建密钥时建议配置：

配置	建议
名称	写清楚用途，例如“飞书机器人测试”
生效范围	普通对话选“对话”范围
过期时间	临时测试不要设置永久有效
执行目标	自由模式、单个专家或专家团；创建后固定
能力配置	自由模式配置能力；绑定专家时从执行目标读取
浏览器	只有网页任务才开启

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": "请生成一份今日工作总结模板。"
      }
    ]
  }'

执行目标、scope、授权和 Key 管理见 API Key 管理。同一账号的不同 Key 不能交叉访问已经绑定 Key 的会话。更多协议细节见 API 文档。

会话复用

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

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

不适合复用的场景：

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

不传 session_id 时通常新建会话；提供请求体字段 idempotency_key 后，相同创建请求可复用已有会话和运行。重试同一业务请求保留原幂等键，新的业务操作使用新键。

附件和文件

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，它比会话完成事件更贴近发布结果。

Agent 外部嵌入

如果不希望自行开发消息列表、历史会话和产物预览，可以把场景专家中已配置的 Agent 直接嵌入业务页面。

接入时需要：

在场景专家启用外部嵌入并配置允许来源。
在宿主页面加载 Script SDK 或 npm 包。
通过 getAccessToken 返回当前访问用户的 Poco 登录 Token。
验证不同用户之间的历史记录隔离，以及 Token 过期后的重新获取。

完整步骤见 Agent 外部嵌入。

On this page