[English](../en/tools.md) | 简体中文

# 工具、MCP 与能力登记

这篇讲工作流能调用的工具：内置工具、自定义工具和 MCP，它们的审批档位，管理员怎么在能力登记里管住它们，以及怎么登记外部系统的端点。给搭建者和管理员看。

## 工具种类

- **内置工具**：15 个。
- **自定义工具**：HTTP 模板，或沙箱里的 Python。
- **MCP**：接入 MCP server（stdio 或 http）。
- **数据源工具**：每个数据源的查询工具 `db_query__<源>`，以及运行时查结构的 `db_schema__`（见[数据源](data-sources.md)）。

谁能配：MCP 的 stdio、端点和凭据、能力治理只有管理员能改，搭建者只读，使用者看不到（见[权限表](identity-and-security.md#权限表)）。

## 审批档位

平台看不出 MCP 和自定义工具做什么，所以它们默认每次调用都等审批。审批档位有三档：`ask`、`gated`、`always`。

- 在工具页可以逐个改成「始终允许 · 门控把关」：每次调用先由门控模型审一遍参数，拿不准、出错、超时都交还给人。
- 也可以改成「始终允许」。审批卡上的「始终允许」等于「始终允许 · 门控把关」。
- 档位在发起运行时快照，恢复和接着跑沿用同一份。
- 正式运行不看档位，一律等审批；例外是能力登记里声明为只读、审批设为免审批的能力（见下文）。

## 能力登记

「工具 → 能力」把内置工具、数据源、自定义工具、MCP 工具登记在一处，名字就是图里的工具名。

- 启动时和各对象增删改时自动同步。来源删掉的标为「缺失」，不删除。
- 管理员可以逐项治理：效果（只读 / 写入 / 视参数而定）、审批（跟随信任设置 / 总要确认 / 免审批）、是否允许无人值守写入、返回的表格位置、字段语义（形状和数据目录的「项」相同，推断的项进「待审阅」）、遮罩字段、凭据模式、查询能力。
- 每改一次，版本号加一。正式运行在发起时固定版本，发布时记下版本，之后有变化只提醒。

### 正式运行免审批

声明为只读、审批设为免审批的能力，在正式运行里直接执行。带 MCP、自定义工具的 Agent 因此不会停在半路等审批。可写数据源上的写语句，不会因为一句声明而免审批。

### 写入只能经调用工具节点

写入能力只能放在「调用工具」节点里：

- Agent 或多 Agent 协作的工具清单里有写入能力时，发布检查在各级都报错，运行时也拒绝。
- 工具页的试运行、工具库里的执行，碰到写入能力一律演练：不发送，交回将要发送的方法、地址、请求头名和请求体。
- 试运行没保存的草稿时，请求按草稿的配置拼；读写按已保存的治理和草稿的方法里更严的一个认。
- 试运行和端点的「测试连接」按 HTTP 状态说成败：2xx 才算成功；能连上但回 404、401 的，照实写状态码。
- 查询能力（用来核实写入结果）只能选同一端点上、绑定这个端点的只读能力。

写外部系统的完整规则见[应用](apps.md#写外部系统)。

## 登记端点

管理员按测试、生产两个环境，登记外部系统的地址和认证头。认证头加密存，界面上只回掩码。

- 只有登记过、开了「允许访问内网」的端点能连内网。元数据地址和高危端口照样拦。
- 绑定端点的 HTTP 工具只填方法、路径模板、查询参数和请求体；路径参数逐段编码后代入。模型拿不到任意地址，请求也不跟随跳转。
- 正式运行走生产环境。探索运行里，写入走测试环境（没有测试环境就演练），读取走生产环境。
- 凭据模式选「服务凭据 + 身份断言」时，请求另带 `X-AgentLab-Assertion`：EdDSA JWT，5 分钟有效；`aud` 是端点名，`sub` 是运行发起人，确认动作的人在 `act` 里。公钥在 `/api/auth/jwks`。
- 指向本机或内网的 http MCP，要管理员先在「工具 → 端点」登记。

### 端点读取可以作证

给只读的、绑定端点的工具声明表格（行的位置、各列的位置）后，结果落成和查询快照形状相同的端点快照：

- 报告里照样编号 Q1…，单元格点得开出处；
- 运行对比照样比，比的是请求；
- 遮罩按列名。

Python 工具和 MCP 不在此列。

## 网络和凭据

- HTTP 工具先解析域名，再逐个 IP 检查，拦截内网、回环与云元数据地址；不跟随重定向，每一跳重新校验。模型给出的地址照样做完整的 SSRF 检查。
- 本机代理开了 fake-ip 时，解析结果是 198.18 段的假地址。在 `AGENTLAB_HTTP_TOOL_FAKE_IP_RANGES` 里配上这个网段（例如 `198.18.0.0/15`）后，这类结果改向公共 DNS（DoH）核实真实地址再判断；核实不了按拦截处理。DoH 地址由 `AGENTLAB_HTTP_TOOL_DOH_URLS` 指定，逗号分隔（见[常见问题](faq.md)）。
- 文件工具的路径 `resolve()` 后必须仍在工作区内。
- 自定义工具的请求头、MCP 的环境变量与请求头、端点的认证头都加密存，只回掩码。