工具设计与安全执行

通过清晰边界、参数防错、最小权限、沙箱、幂等与评测设计可被模型可靠使用的工具。

学习目标

能解释“工具设计与安全执行”如何把工具当作面向非确定性调用者的安全接口
能区分agent-computer interface、参数防错、最小权限、沙箱、工具评测，并指出它们在请求、状态或执行边界中的位置
能固定输入，沿以下证据定位首个分叉：工具版本、描述、参数、校验、权限身份、沙箱策略、审批、结果、失败类别与评测统计
能注入“工具接受任意路径与命令字符串，并以应用全部权限直接执行”，在同一预算和权限下完成故障、恢复与重放

来源、课程编排与适用边界

“工具设计与安全执行”以Anthropic 公开全文《Building effective agents》为总纲，并用Anthropic《Writing effective tools for agents》核对本单元机制；工具与外部能力的角色再由MCP 官方规范交叉检查。

这不是一本具有“官方九章目录”的纸质书。平台把公开文章中的 augmented LLM、工作流、智能体、上下文和工具工程重组为 9 个教学单元；下列 72 个节点是站内课程地图，不冒充 Anthropic 原文目录。正文、代码、图表和练习均为独立教学重写，产品或模型版本变化时应重新验证。

本单元的八个课程坐标

工具设计与安全执行：作为“把工具当作面向非确定性调用者的安全接口”的第 1 个课程坐标，必须进入正文解释、交互观察或练习证据。
工具边界：作为“把工具当作面向非确定性调用者的安全接口”的第 2 个课程坐标，必须进入正文解释、交互观察或练习证据。
参数防错：作为“把工具当作面向非确定性调用者的安全接口”的第 3 个课程坐标，必须进入正文解释、交互观察或练习证据。
结构化返回：作为“把工具当作面向非确定性调用者的安全接口”的第 4 个课程坐标，必须进入正文解释、交互观察或练习证据。
错误分类：作为“把工具当作面向非确定性调用者的安全接口”的第 5 个课程坐标，必须进入正文解释、交互观察或练习证据。
最小权限：作为“把工具当作面向非确定性调用者的安全接口”的第 6 个课程坐标，必须进入正文解释、交互观察或练习证据。
沙箱执行：作为“把工具当作面向非确定性调用者的安全接口”的第 7 个课程坐标，必须进入正文解释、交互观察或练习证据。
工具评测：作为“把工具当作面向非确定性调用者的安全接口”的第 8 个课程坐标，必须进入正文解释、交互观察或练习证据。

术语与状态合同

、、、、。

本页不变量是：任何模型请求都在副作用前完成参数、权限和风险校验，失败以最小必要信息返回。任何“成功”结论都要保存以下证据：工具版本、描述、参数、校验、权限身份、沙箱策略、审批、结果、失败类别与评测统计，不能把模型口头确认当作环境事实。

关键机制与可推翻实验

工具名称与描述要减少歧义

一个高层任务通常有多种 API 表达。工具应围绕模型能理解的任务意图组织，明确何时使用、何时不用和相邻工具差异。

动手试：从真实失败轨迹提取误选样本，迭代名称、描述和示例后重跑评测。

参数设计优先防错

枚举、绝对路径、受限标识和分离的 dry-run 能让错误更难发生。只在描述里写“请小心”不能替代类型与运行时校验。

动手试：尝试相对路径、目录穿越、空枚举和超大范围，确认都在副作用前失败。

权限与沙箱限制最坏影响

工具身份只获得任务所需资源；文件、网络和命令在可观测边界中执行。高风险或不可逆动作需要明确审批和预览。

动手试：在沙箱内请求越界文件和外网地址，保存拒绝原因与零副作用证明。

工具质量由 agent 轨迹评测

单元测试证明实现正确，却不能证明模型会选对和填对。还要在代表任务上测工具选择、参数错误、恢复率、token 成本和任务成功。

动手试：把工具版本作为实验变量，对同一任务集比较端到端成功率和失败簇。

先预测，再操作三类证据

分步1 / 3

1. 模型与结构边界

在“工具设计与安全执行”中先画出责任、数据或候选空间，再预测“把工具当作面向非确定性调用者的安全接口”会在哪个节点改变结果。

好工具 vs 坏工具：模型看到的不是函数源码，而是这份说明书

坏工具：像万能电话

描述清晰度

`run_task`：执行一些操作

参数粒度

`payload: string` 让模型自己拼一整坨文本

错误信息

失败就抛异常，主循环断掉

权限边界

能读写所有路径、能执行任意命令

好工具：像有标签的专线

描述清晰度

`search_docs`：只搜索公开文档，不读取本地文件

参数粒度

`query` / `limit` / `source` 分开校验

错误信息

`{ok:false, error:{code,message}}` 回灌

权限边界

白名单路径、只读默认、危险操作先确认

工具设计越具体，模型越容易选对；权限边界越窄，运行时越容易守住安全线。

最小可运行实现

def invoke_tool(tool, raw_args, actor, approval=None):
    args = tool.schema.validate(raw_args)
    tool.policy.authorize(actor, args)
    preview = tool.preview(args)
    if preview.risk == "high" and approval != preview.approval_token:
        return {"ok": False, "error": "approval_required", "preview": preview}
    with sandbox(tool.permissions) as isolated:
        return isolated.run(tool, args, idempotency_key=stable_key(args))

这段实现只负责暴露“把工具当作面向非确定性调用者的安全接口”的最小合同。交付版本还要补齐超时、日志、权限、密钥隔离和可重复评测；缺少以下证据时，代码能运行也不代表本章结论成立：工具版本、描述、参数、校验、权限身份、沙箱策略、审批、结果、失败类别与评测统计。

练习与答案

练习

问题 1：系统边界。 怎样用最小输入证明“任何模型请求都在副作用前完成参数、权限和风险校验，失败以最小必要信息返回”？

问题 2：课程坐标。 工具设计与安全执行、工具边界、参数防错、结构化返回、错误分类、最小权限、沙箱执行、工具评测如何进入可操作验证？

问题 3：故障恢复。 怎样证明“工具接受任意路径与命令字符串，并以应用全部权限直接执行”已经修复？

本章回顾

“工具设计与安全执行”的主问题是把工具当作面向非确定性调用者的安全接口。
核心不变量是任何模型请求都在副作用前完成参数、权限和风险校验，失败以最小必要信息返回。
首要反例是工具接受任意路径与命令字符串，并以应用全部权限直接执行。
最小证据包包含工具版本、描述、参数、校验、权限身份、沙箱策略、审批、结果、失败类别与评测统计。

名词解释

本章出现的专业名词，用大白话再讲一遍。

agent-computer interface: 为模型选择和使用工具而设计的交互界面。在“工具设计与安全执行”中必须能按以下证据重新定位：工具版本、描述、参数、校验、权限身份、沙箱策略、审批、结果、失败类别与评测统计。
参数防错: 通过类型、枚举和结构让错误输入更难产生。在“工具设计与安全执行”中必须能按以下证据重新定位：工具版本、描述、参数、校验、权限身份、沙箱策略、审批、结果、失败类别与评测统计。
最小权限: 主体只获得完成当前任务所必需的权限。在“工具设计与安全执行”中必须能按以下证据重新定位：工具版本、描述、参数、校验、权限身份、沙箱策略、审批、结果、失败类别与评测统计。
沙箱: 限制代码、文件、网络和系统调用影响范围的执行环境。在“工具设计与安全执行”中必须能按以下证据重新定位：工具版本、描述、参数、校验、权限身份、沙箱策略、审批、结果、失败类别与评测统计。
工具评测: 在代表任务轨迹上测量工具选择与使用效果。在“工具设计与安全执行”中必须能按以下证据重新定位：工具版本、描述、参数、校验、权限身份、沙箱策略、审批、结果、失败类别与评测统计。

阅读导航

← ReAct 循环 · 本课程终点 →