工具层把开放文本决策压缩为有限动作空间。一个工具不只是名称与描述，还包含参数 schema、前置条件、权限、超时、副作用语义、结果结构和错误分类。模型能生成合法调用，只说明输出通过了语法边界；调用是否允许、是否生效以及是否完成目标，仍由 Runtime 和环境决定。
本章把接口分成三个相邻层。工具契约定义模型可以提出哪些结构化动作；Agent-Computer Interface（ACI）决定环境以什么观察和动作呈现给模型；MCP 等协议规范 Host 与外部能力提供方怎样发现和交换这些对象。三层可以组合，却不能互相替代。JSON Schema 无法决定文件写入权限，MCP 连接成功也不表示远端工具值得信任，浏览器截图更不会自动给出可稳定引用的元素标识。
1. 动作契约
1.1. 输入与结果
输入 schema 应表达必填字段、枚举、资源标识与范围约束；结果要区分数据、错误和状态变化。2.1-工具调用与动作空间进一步讨论工具粒度和选择。
对模型而言，schema 同时是解码约束与动作说明。字段名、类型和描述影响参数生成；对执行器而言，它只是第一层验证，业务前置条件、资源版本和主体权限仍需独立检查。把二者混在一个“参数不正确”错误中，会使模型不知道应修正 JSON、重新读取环境还是请求授权。
1.2. 错误与副作用
可重试故障、参数错误和权限拒绝需要不同返回。写操作还需提供幂等与提交语义，防止响应丢失后重复执行。
错误也属于观察空间。稳定错误码负责机器分支，简短消息说明修正方向，诊断字段提供受控细节。调用超时表示客户端未收到结果，不能直接推断服务端未执行；具有副作用的动作要携带幂等键或事务标识，并提供查询提交状态的接口。
2. 环境接口
2.1. ACI
Agent-Computer Interface 关注模型可见的观察和可用动作如何共同设计。2.2-ACI与协议边界比较 API、Shell、GUI 与协议层。
同一模型面对不同 ACI 会表现出显著差异。SWE-agent 为仓库导航、文件查看、搜索和编辑设计面向语言模型的接口，在 SWE-bench 上展示了专用 ACI 相比裸 Linux Shell 的改进。网页环境也有相同问题：整页 HTML、可访问树、截图和带稳定标识的交互元素提供的信息量、token 成本与定位精度各不相同。
2.2. MCP的范围
MCP 规范资源、提示和工具怎样被发现与调用，但不替应用决定权限、事务、业务正确性或完成条件。协议互通与安全执行属于不同层。
MCP 的 Host、Client 与 Server 分工尤其重要。Server 声明工具、资源和提示，Client 维护一条协议连接，Host 负责模型、用户授权、上下文和多个 Server 的组合。工具列表来自 Server，不代表 Host 必须把全部工具交给模型；Host 可以按任务、信任域和权限过滤，并在执行前再次校验。
3. 设计检验
3.1. 可学性
工具名称、描述、参数和结果应让模型容易区分。大量语义重叠工具会增加选择错误，过度通用工具则扩大权限与参数空间。
可学性可以通过选择准确率、参数有效率、错误恢复率和任务成功率分层评测。若格式正确率提高而任务成功率不变，schema 约束可能只修复了解析；若专用编辑动作减少步骤并提高成功率，则 ACI 改变了模型所需解决的问题。实验需要固定模型、提示、预算和环境，才能把变化归因到接口。
3.2. 可验证性
每个改变环境的动作都应对应可读取的结果。若只能相信模型或工具的成功字符串，系统无法建立完成判定。
可验证接口还要公开动作影响的资源和新版本。文件编辑返回补丁与内容哈希，数据库更新返回受影响记录与事务标识，网页提交后提供可重新读取的订单状态。写动作与读后验证配对，才能区分“调用被接受”“副作用已提交”和“任务目标已满足”。
4. 两条贯穿本章的案例
4.1. 仓库修复
代码 Agent 接到缺陷描述后，动作空间包含搜索、分段查看、补丁编辑、运行命令与读取版本差异。搜索结果需要路径和行号，查看动作限制窗口并提示剩余内容，补丁动作检查基线哈希，命令动作返回退出码和裁剪后的日志。模型可以组合这些动作，却不能直接把任意文本当作 Shell 命令绕过权限。
完成一个修复需要接口连续提供定位、修改和验证所需信息。若查看工具一次输出整个仓库，上下文会被无关内容占满；若编辑工具只接受整文件重写，小改动更容易破坏未读区域；若测试工具只返回“失败”，模型无法定位原因。ACI 的质量体现在模型是否能用有限步骤获得下一项决策所需差异。
4.2. 网页采购
网页 Agent 需要搜索商品、选择规格、填写地址并提交订单。观察可以组合页面 URL、标题、可访问树、截图和当前表单状态；动作可以使用元素标识执行点击、输入、选择与滚动。元素标识随页面版本更新，页面导航后继续使用旧标识应返回明确的 stale-element 错误。
提交订单是高风险动作。模型提出调用后，Runtime 检查商品、数量、总价、收件地址和审批，生成幂等键，再点击最终确认。页面超时后先查询订单列表，确认是否已创建；完成判定读取订单状态和金额，而不是接受按钮点击成功。这个案例同时涉及动作 schema、ACI 定位、权限与提交语义，说明接口设计必须贯穿整个闭环。
5. 学习路线与边界
5.1. 从动作契约进入
先读 2.1-工具调用与动作空间，建立工具选择、参数生成、校验、执行和结果反馈的完整路径。该文还讨论并行动作何时安全、批处理怎样表示部分失败，以及幂等键为何不能由模型随意生成。
随后读 2.2-ACI与协议边界，把单个工具放回环境接口。正文比较代码与浏览器环境，分析 SWE-agent ACI 消融，并用 MCP 说明协议的数据层、传输层和 Host 安全职责。
5.2. 不在本章展开的主题
工具监督微调与 Agentic RL 位于第 6 章，本章只定义训练数据依赖的动作与观察语义。沙箱、审批、凭据和恢复位于第 5 章，本章在接口边界处说明它们需要哪些字段，不重复完整安全模型。
RAG 的召回、重排与索引位于独立知识库。本章只把检索视为一个带查询参数、来源结果和错误语义的工具动作。MCP 也不等于多 Agent 通信；Server 是能力提供方，未必具有独立目标、策略或任务状态。
完成本章后，读者应能从失败轨迹判断问题位于工具选择、参数、接口定位、协议传输、权限、环境执行还是完成验证，并为每一层找到独立证据。