15-background-calls.md 5.1 KB
15 后台调用
状态：已实施（2026-10-27）。
1. 问题
接入的外部工具（MCP 服务）中，有些调用要执行很久（导出、跑批、训练，几十分钟到几个小时）。在此之前：
- 网关对外部工具的单次调用最多等 10 分钟（有进度通知时最多 20 分钟），超时即失败。
- 让模型一直等：引擎进程挂着、占用并发；服务重启或断线时前功尽弃；用户在此期间无法继续。
- 让模型轮询：每次询问都是一轮模型调用，花 token、上下文越来越长，模型只起到昂贵的定时器作用。
2. 方案：等待交给服务端
外部工具的调用超过一定时间，或者工具被标记为"总是后台执行"时，网关把它转到后台：
- 网关立即返回给模型："已转为后台执行（后台调用 id），完成后系统会把结果发给你"。模型结束本轮，告诉用户已提交。
- 服务端继续等待这次调用（不涉及模型，不花 token）。
- 完成、失败或被取消时，服务端往发起调用的会话（或工作组中发起调用的机器人）发一条消息：
【后台调用完成】服务 · 工具（id，耗时）+ 结果。这条消息唤醒 AI 继续处理。- 会话正在执行时，等这一轮结束后再发。
- 结果较长时保存为文件（工作区
.agent/mcp/下），消息中给出路径。
3. 何时转为后台
| 条件 | 说明 |
|---|---|
| 自动 | 调用超过 backgroundCalls.autoAfterSec（默认 180 秒）仍未返回 |
| 总是 | 管理员在"MCP 服务"页面把工具标记为"后台执行"：调用开始时就转到后台 |
| 不转 | 发起方（会话 / 工作组）正在进行的后台调用已达 backgroundCalls.maxPerTarget（默认 3）：按原来的方式等待（10 分钟超时） |
- 后台调用的最长时间
backgroundCalls.maxHours（默认 24 小时），超时按失败处理。 - 转为后台之前用户中断了这一轮，调用随之取消；转为后台之后与这一轮无关，只能单独取消。
- 只针对外部 MCP 服务的工具；内置工具（文档转换等）不转后台。
4. 工作组中的子任务
组员在执行子任务时发起的调用被转到后台：
- 这一轮结束时如果组员没有调用
task_complete/task_fail，子任务进入"等待后台调用"（background）状态，不汇报给组长。 - 后台调用结束后，子任务重新排队；组员下一轮收到的输入是"后台调用结果 + 继续完成子任务"，完成后照常
task_complete。 - 子任务被取消（组长取消、任务结束）时，它等待的后台调用一并取消。
- 不在子任务中的调用（成员直接 @ 组员，或组长自己调用），结果以系统消息发给发起调用的机器人。
- 任务的时长限额照常生效：后台调用很长时，组长下次被唤醒时任务可能因超时暂停，由成员选择继续。
5. 服务重启
- 后台调用依赖与外部服务的连接，服务重启后无法接续：进行中的调用标记为失败，并通知发起方（"服务重启，后台调用中断"），由 AI 决定是否重试。
- 外部服务本身是异步作业（提交后返回作业 id、可以查询状态）的，建议提供"提交"和"查询"两个工具；MCP 规范中的异步任务机制成熟后再直接对接。
- 连接管理：有调用在执行的上游连接不会因空闲被关闭（之前空闲 10 分钟会关闭，长调用会被中断）。
6. 数据模型
background_calls：id、会话 id、工作组 id 与机器人 id（工作组中发起时）、子任务 id、MCP 服务 id 与名称、工具名、参数、状态（running / completed / failed / cancelled）、开始与结束时间、结果文本、错误、是否已通知。
7. API 与界面
| API | 接口 |
|---|---|
| Agent API | GET /v1/sessions/:id/background-calls；POST /v1/background-calls/:id/cancel |
| Bot API | GET /bot/v1/teams/:id/background-calls；POST /bot/v1/teams/:id/background-calls/:callId/cancel |
| 后台 | GET /admin/v1/background-calls；POST /admin/v1/background-calls/:id/cancel；MCP 服务的工具可以标记"后台执行" |
<AgentChat>、<TeamChat>：有进行中的后台调用时，顶部显示后台调用栏（工具、已执行时长，可以取消）。- 后台"后台调用"页面：全部后台调用，查看参数和结果，取消进行中的调用。
- 系统设置增加"后台调用"一节（§3 的三个值）。
8. 实施记录（2026-10-27）
- 修复了上游连接的空闲回收：之前按最后使用时间回收，执行超过 10 分钟的调用会在中途被关闭；现在有调用在执行的连接不回收。
- 系统提示词的"运行环境"中说明：工具返回"已转为后台执行"时结束本轮并告诉用户，不要等待或轮询。
- 已用真实 Claude（haiku）验收：
- 模拟的报表系统
export_report需要 90 秒，转后台时限设为 20 秒。 - Claude 调用后第 20 秒转为后台，Claude 告诉用户"已提交、完成后再总结"并结束本轮；Playground 顶部显示"后台执行中"。
- 90 秒后结果作为新消息发到会话，Claude 收到后给出总结。
- 模拟的报表系统