会话事件
处理会话完成、失败和停止事件，读取运行摘要、用量、产物状态与错误原因。
会话事件覆盖一次 Agent 运行的三种结束状态。它们使用相近的 session 和 run 结构，便于接收端共用解析逻辑。
会话完成
事件：session.completed
当 Agent 运行成功完成时触发。示例：
{
"schema_version": "v1",
"event_type": "session.completed",
"event_id": "2d3134c5-0000-4000-8000-000000000001",
"occurred_at": "2026-02-15T14:30:00+00:00",
"is_test": false,
"user": {
"user_id": "1234567890",
"username": "alice",
"full_name": "Alice",
"department": "研发",
"role": "user"
},
"webhook": {
"id": 12,
"owner_scope": "system"
},
"session": {
"session_id": "5f6a0000-0000-4000-8000-000000000001",
"title": "日报总结",
"kind": "chat",
"status": "completed",
"project_id": "97d20000-0000-4000-8000-000000000001",
"created_at": "2026-02-15T14:20:00+00:00",
"updated_at": "2026-02-15T14:30:00+00:00"
},
"run": {
"run_id": "6dc90000-0000-4000-8000-000000000001",
"turn_id": "20cf0000-0000-4000-8000-000000000001",
"status": "completed",
"schedule_mode": "immediate",
"scheduled_task_id": null,
"started_at": "2026-02-15T14:20:10+00:00",
"finished_at": "2026-02-15T14:29:58+00:00"
},
"summary": {
"has_artifacts": true,
"has_assistant_response": true,
"message_count": 9,
"assistant_message_count": 4,
"tool_execution_count": 3,
"total_cost_usd": 0.012345,
"input_tokens": 2345,
"output_tokens": 1234,
"duration_ms": 588000
},
"meta": {
"trigger": "run.done",
"source": "poco.backend.callback.completed",
"idempotency_key": "2d3134c5-0000-4000-8000-000000000001",
"capability_profile_version": 3,
"model_stop_reason": "end_turn"
}
}核心字段
| 字段 | 说明 |
|---|---|
session.session_id | 会话 ID，可用于查询历史消息或会话产物 |
session.kind | chat、api 或 scheduled |
session.project_id | 关联项目，可能为 null |
run.run_id | 本轮运行 ID，可用于查询本轮产物 |
run.turn_id | 运行轮次 ID |
run.schedule_mode | 调度模式 |
run.scheduled_task_id | 定时任务 ID，普通会话通常为 null |
summary.has_artifacts | 会话当前是否已有产物存储记录 |
summary.has_assistant_response | 会话累计是否已有助手响应 |
summary.total_cost_usd | 会话最新 UsageLog 的成本 |
summary.input_tokens、output_tokens | 会话最新 UsageLog 的 Token 用量 |
summary.duration_ms | 本轮执行时长 |
对于 background=true 的 API 后台任务，session.completed 不包含请求中的 background_payload。接收端可使用事件里的 run.run_id，通过提交任务时的同一 API Key 调用 GET /openapi/v1/runs/{run_id}，从 background_results.background_payload 获取原始透传数据。
消息、助手消息和工具计数统计整个会话；成本与 Token 取最新用量记录，不能把 summary 当作准确的本轮聚合。summary.has_artifacts=true 表示会话当前已有产物记录，不能证明本轮新生成了文件，不代表工作区归档已经导出完成。需要稳定读取完整文件时，应等待 workspace_export.completed。
会话失败
事件：session.failed
session、run 与完成事件基本一致，但状态为 failed。错误信息通常位于：
run.last_errormeta.error_message
接收端应保留错误文本用于排查，但不要依赖某段错误文本做稳定业务分支；业务分支应使用 event_type 和状态字段。
建议处理：
- 按
event_id去重。 - 保存
session_id、run_id和错误信息。 - 发送告警或标记业务任务失败。
- 由业务规则决定是否重新发起任务，不要无限重试。
会话停止
事件：session.stopped
当用户停止正在执行的会话时触发。session.status 为 stopped，活动 run.status 通常为 canceled，载荷保留实际运行状态，停止原因可能位于 run.last_error 或 meta.error_message。
停止是用户或业务主动终止，不应默认当成系统故障重试。如果业务需要区分“用户取消”和“运行失败”，直接按 event_type 区分。
过滤规则
三种会话事件都会应用 session_kinds：
- 页面对话：
chat - API 对话：
api - 定时任务会话：
scheduled
项目级配置还会要求 session.project_id 存在并与 WebHook 的 project_id 一致。