AI agent 很容易给人一种错觉：只要 prompt 写清楚，模型自然会知道自己可以用什么工具、这些工具支持什么参数、当前环境有哪些限制。现实里，大量失败恰恰来自这种“默认会知道”。
当系统开始跨环境运行后，本地 runner、远程 VPC、浏览器 runner 和客户自定义工具的能力并不相同。某些地方能截图，某些地方不能；某些工具是 v2 schema，某些租户还停留在 v1；某些会话可以写文件，某些只能只读。如果 agent 对这些差异没有显式感知，它就只能靠猜。
建议先结合 AI agent Tool Registry 治理、AI agent 工具 Schema 演进与兼容策略、AI agent Prompt Contract 设计 和 AI agent 多执行环境路由 一起看。
Agent 不该靠猜测判断自己有哪些手
最稳的做法，是在每次 run 启动前给 agent 一份 capability manifest，而不是让它通过试错去碰。一个最小 manifest 通常应包含：
| 字段 | 用途 |
|---|---|
| tool name | 当前可用工具名 |
| schema version | 当前接受哪些参数结构 |
| allowed actions | 可读、可写、可执行、可外发 |
| hard limits | 超时、大小、速率限制 |
| environment notes | 是否有浏览器、截图、网络出口、私网访问 |
这份 manifest 的价值在于，把“环境约束”从隐式背景变成显式输入。
能力协商不是文档问题，而是运行时协议问题
很多团队把工具能力写在文档或 README 里，但运行时并不传给 agent。这样一来，文档越清楚，系统实际行为却未必越稳定，因为运行时仍然没有协商结果。
一个更可执行的方式，是让系统在 run 开始时生成 environment contract：
{
"environmentId": "runner_browser_cn_01",
"tools": [
{"name": "browser.open", "version": "v3", "limits": {"timeoutMs": 15000}},
{"name": "workspace.write", "version": "v2", "mode": "readonly"}
],
"network": {"publicWeb": true, "privateVpc": false},
"policy": {"externalSend": "forbidden"}
}
之后 agent 的推理，不再以“想做什么”为起点，而是以“当前环境允许我做什么”为起点。
失败案例：prompt 以为浏览器 runner 支持截图，结果整个验证链路都在假前提下运行
某个 QA agent 的 prompt 里一直写着“进入页面、截图并比对结果”。在旧环境里这没问题，但新接入的一类 runner 没有截图能力，只能拿 DOM 和网络日志。系统没有显式 capability negotiation，于是 agent 仍旧尝试调用截图工具，失败后又反复重试，最后把问题错误归因为页面加载慢。
这类事故真正缺的不是“更强的重试机制”，而是 agent 根本不知道当前环境能力已经变了。修复方式不是改 prompt，而是让环境契约明确告诉它：
- screenshot 不可用
- 可用替代能力是 DOM snapshot
- 当前环境只允许 readonly 验证
一旦能力协商明确，agent 才能把失败归因到正确位置。
工具版本和环境限制也该参与 capability negotiation
能力协商不应该只告诉 agent “有哪些工具”，还应告诉它“这些工具当前是什么版本、限制到哪”。这点在 Schema 演进期尤其重要。
例如：
- 某租户仍在使用
draft.create@v1 - 当前 runner 不允许超过 30 秒的长任务
- 当前会话处于只读模式，禁止
workspace.write
这些都不该留给 prompt 自己推断。否则 agent 很容易在逻辑上做对，却在运行时踩中完全没告诉它的限制。
Capability Negotiation Checklist
- 每次 run 是否都生成 capability manifest 或 environment contract
- manifest 是否同时包含工具、版本、限制和环境说明
- agent 是否会根据 contract 调整方案，而不是无条件套用旧 prompt
- 工具 schema 变化时，能力协商是否能显式告诉 agent 当前接受哪版输入
- 环境能力下降时，系统是否能提供替代路径而不是只报错
- 观测系统是否能记录“本次 agent 是依据哪份 contract 做出的决策”
真正该被稳定下来的，不是 prompt，而是契约
多环境 AI agent 真正稳定的前提，不是写一个万能 prompt，而是把每次运行的能力边界显式化。只要 agent 还需要靠猜测判断当前有哪些工具、这些工具能做到哪，它就迟早会在错误前提下做出看似合理的决策。
延伸阅读：
