# 15 后台调用

> 状态：**已实施（2026-10-27）**。

## 1. 问题

接入的外部工具（MCP 服务）中，有些调用要执行很久（导出、跑批、训练，几十分钟到几个小时）。在此之前：

- 网关对外部工具的单次调用最多等 10 分钟（有进度通知时最多 20 分钟），超时即失败。
- 让模型一直等：引擎进程挂着、占用并发；服务重启或断线时前功尽弃；用户在此期间无法继续。
- 让模型轮询：每次询问都是一轮模型调用，花 token、上下文越来越长，模型只起到昂贵的定时器作用。

## 2. 方案：等待交给服务端

外部工具的调用超过一定时间，或者工具被标记为"总是后台执行"时，网关把它转到后台：

1. 网关立即返回给模型："已转为后台执行（后台调用 id），完成后系统会把结果发给你"。模型结束本轮，告诉用户已提交。
2. 服务端继续等待这次调用（不涉及模型，不花 token）。
3. 完成、失败或被取消时，服务端往发起调用的会话（或工作组中发起调用的机器人）发一条消息：`【后台调用完成】服务 · 工具（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 收到后给出总结。