02-工具调用与权限模型

核对日期：2026-05-13。

不稳定项：工具调用协议、MCP 生态、浏览器/电脑操作能力、企业权限系统和模型结构化输出能力变化较快；真实工具接入前必须按目标 SDK 和安全策略复核。

1. 学习目标

本专题关注 Agent 的“手”：工具。工具设计决定 Agent 能做什么，也决定它能造成多大破坏。

学完后你应该能做到：

设计包含权限、幂等性、错误码和审批规则的工具 schema。
区分只读工具、草稿写入、低风险写入和高风险执行。
明确模型建议调用与系统允许执行之间的边界。
为工具调用设计审计、参数校验、速率限制和预算。
识别工具描述模糊、权限过宽、返回污染等常见问题。

2. 工具不是普通 API

普通 API 文档给工程师看，Agent 工具 schema 给模型和系统共同使用。

一个合格工具定义要同时服务：

模型：理解什么时候用、需要什么参数。
系统：校验权限、参数、预算和审批。
审计：知道谁在什么上下文中调用了什么。
评测：判断工具选择和参数是否正确。

工具 schema 越模糊，模型越容易猜。

3. 工具 schema 模板

{
  "name": "create_refund_draft",
  "description": "创建退款申请草稿，不会直接退款。必须由人工审批后才能提交。",
  "permission": "write_draft",
  "risk_level": "medium",
  "idempotent": true,
  "requires_approval": true,
  "side_effect": "draft_only",
  "input_schema": {
    "type": "object",
    "required": ["order_id", "amount", "reason"],
    "properties": {
      "order_id": {"type": "string"},
      "amount": {"type": "number", "minimum": 0},
      "reason": {"type": "string", "maxLength": 200}
    }
  },
  "output_schema": {
    "type": "object",
    "required": ["draft_id", "status"],
    "properties": {
      "draft_id": {"type": "string"},
      "status": {"type": "string"}
    }
  },
  "error_codes": ["PERMISSION_DENIED", "VALIDATION_ERROR", "ORDER_NOT_FOUND"],
  "example": {
    "order_id": "ord_123",
    "amount": 99.0,
    "reason": "用户反馈重复扣费，需要人工审核。"
  }
}

关键字段：

permission：系统权限级别。
risk_level：风险等级。
idempotent：是否可安全重试。
requires_approval：是否需要人工确认。
side_effect：是否有外部副作用。

4. 权限分级

等级	能力	示例	策略
L0	无外部访问	文本总结	无需审批
L1	公开只读	Web 搜索、公开文档	记录来源
L2	内部只读	CRM 查询、代码读取	鉴权、脱敏
L3	创建草稿	工单草稿、退款草稿	人工确认
L4	低风险写入	打标签、更新备注	审计、可撤销
L5	高风险写入	付款、退款、删除、发邮件	强审批、双人复核
L6	执行环境	shell、浏览器、数据库写入	沙箱、最小权限、人工批准

模型可以提出“想调用什么工具”，但系统必须决定是否允许。

5. 参数校验

工具调用前必须校验：

参数类型。
必填字段。
范围限制。
字符串长度。
枚举值。
用户和资源归属。
当前任务是否允许。
是否超过预算。

示例：退款金额不能只由模型填写，还要由规则引擎校验订单金额、退款政策和用户归属。

6. 幂等性与副作用

自动重试前必须知道工具是否幂等。

类型	示例	重试策略
幂等只读	查询订单	可重试
幂等草稿	用 idempotency key 创建草稿	可有限重试
非幂等写入	发送邮件、提交退款	不自动重试
高风险执行	删除、支付、生产变更	人工审批

所有写操作都应支持：

idempotency key。
审计日志。
预览或 dry-run。
回滚或撤销路径。

7. 工具返回设计

工具返回不应是一大段无结构文本。

推荐返回：

{
  "ok": true,
  "data": {},
  "source": {
    "system": "crm",
    "record_id": "ord_123",
    "updated_at": "2026-05-13"
  },
  "warnings": [],
  "next_allowed_actions": ["create_refund_draft"]
}

好处：

模型能理解结果。
系统能做下一步限制。
trace 能记录来源。
eval 能判断工具是否成功。

8. MCP 与工具生态

MCP 或类似协议解决的是工具连接和上下文暴露方式，不自动解决安全。

接入时要问：

工具发现是否可控。
工具描述是否可信。
谁授权工具访问。
工具返回是否可能包含恶意指令。
工具调用是否有审计。
是否支持按用户和任务限制权限。

协议能让工具更容易接入，也会让错误工具更容易被暴露。连接越方便，治理越重要。

9. 工程案例

9.1 客服工单 Agent

工具：

read_ticket：L2，只读。
search_policy：L2，只读。
create_reply_draft：L3，草稿。
send_reply：L5，高风险外发，需要人工确认。

安全设计：

Agent 只能创建草稿。
发送动作由固定 Workflow 执行。
审批卡片展示证据、影响和撤销方式。

9.2 代码修改 Agent

工具：

search_files：L2。
read_file：L2。
edit_file：L4。
run_tests：L6 沙箱。
git_push：禁用或人工执行。

安全设计：

限制工作目录。
禁止读取密钥文件。
测试命令沙箱执行。
diff 必须人工 review。

10. 常见反模式

反模式	表现	后果	修正
工具描述含糊	“处理订单”	模型误用	具体动词和边界
权限只写 Prompt	让模型别越权	不可靠	系统鉴权
直接暴露高危 API	refund/delete/send	事故不可逆	草稿和审批
返回大段文本	噪声入上下文	决策变差	结构化返回
无错误码	只有异常字符串	无法恢复	标准错误
无审计字段	不知道谁调用	无法追责	trace 和 request id

11. 练习

为“退款申请 Agent”设计 4 个工具：

查询订单。
查询退款政策。
创建退款草稿。
提交审批请求。

每个工具写出权限等级、schema、错误码、是否幂等、是否需要审批和审计字段。

12. 验收题

Agent 工具 schema 为什么不是普通 API 文档？
工具权限应该如何分级？
为什么写操作优先设计成草稿或申请单？
哪些工具可以自动重试，哪些不可以？
工具返回为什么要结构化？
MCP 解决了什么问题，又没有解决什么问题？

1. 学习目标​

2. 工具不是普通 API​

3. 工具 schema 模板​

4. 权限分级​

5. 参数校验​

6. 幂等性与副作用​

7. 工具返回设计​

8. MCP 与工具生态​

9. 工程案例​

9.1 客服工单 Agent​

9.2 代码修改 Agent​

10. 常见反模式​

11. 练习​

12. 验收题​