工具、MCP 与能力登记

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

工具种类

内置工具：23 个，其中 5 个是分析工具（见下文）。
自定义工具：HTTP 模板，或沙箱里的 Python。
MCP：接入 MCP server（stdio 或 http）。
数据源工具：每个数据源的查询工具 db_query__<源>，以及运行时查结构的 db_schema__（见数据源）。

谁能配：MCP 的 stdio、端点和凭据、能力治理只有管理员能改，搭建者只读，使用者看不到（见权限表）。

分析工具

五个分析工具是平台的确定性分析：analysis_decompose（变化拆解）、analysis_baseline（波动基线）、analysis_trend（趋势判断）、analysis_differ（差异检验）、analysis_comparable（可比性检查）。它们不查库，只分析绑了它的 agent 这次执行里查过的结果，判定由平台按固定的方法和阈值算，判定语由系统写（见Agent 的分析工具）。

参数里没有阈值。绑了任一个，平台就把内置的分析方法注入 agent 的系统提示，同一份只注入一次。
只读、不写任何东西，不算危险工具：缺省的审批策略下不用等审批；使用者的问数据里也能用。
只能绑给 agent：放进「调用工具」节点时画布校验报错，模板里要固定做的分析用分析卡（见分析卡）。
每个 Agent 每次执行最多分析 12 次（「设置 → 偏好设置 → 分析」里改）。
它们不连数据源：读的是这次执行里已经查回来的快照，交回的是分析结论，不是查询结果。

审批档位

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

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

能力登记

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

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

正式运行免审批

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

写入只能经调用工具节点

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

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

写外部系统的完整规则见应用。

登记端点

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

只有登记过、开了「允许访问内网」的端点能连内网。元数据地址和高危端口照样拦。
绑定端点的 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 指定，逗号分隔（见常见问题）。
文件工具的路径 resolve() 后必须仍在工作区内。
自定义工具的请求头、MCP 的环境变量与请求头、端点的认证头都加密存，只回掩码。

6.3 KiB Raw Blame History Unescape Escape