诸事顺，利

1. 工具一多会怎样#

假设一个客服 Agent 挂了 50 个工具：查订单、查物流、查库存、退款、改地址、删订单、发邮件、查数据库、执行 SQL、转账、改配置、重启服务。

平铺在同一个列表里，会同时出现七个问题：

七个问题的根是同一个：工具列表是扁平的，工具背后的风险、权限和成本一点都不扁平。

2. 分层的本质#

分层是按职责、风险、权限、调用频率和成本把工具分组，每一组有自己的调用规则、校验强度和边界。

它要解决的事情有六件：

3. 按风险分五层#

这是最常用的一条分法，五层按风险从低到高排：

每层的门槛不一样，落到代码里就是按层配的一张规则表，见第 7 节。

4. 另外两种分法#

风险不是唯一的分法。职责和成本也能分层，区别在于它们回答的问题不同：

5. 数据工具和动作工具#

这是工具分层里最重要的一组区分。

数据工具只读取信息，不改变系统状态。查订单、查物流、查库存、查政策、查用户信息、搜索知识库都属于这一类。

动作工具会改变系统状态，产生副作用 +。退款、下单、改地址、发邮件、删数据、转账、创建工单、重启服务都属于这一类。

两边的差别不只是「读还是写」，工程要求也不一样：

顺着这张表往前推，两边在设计上的待遇也不同。数据工具可以交给模型自由调用，能并行、能缓存、能重试，权限放宽一点问题不大。动作工具要严格 schema、幂等、阈值、审批、审计日志、可回滚，模型的自由度压到最低。

读放开，写收紧；低危放开，高危收紧。

6. 读写分离#

有几类工具既读又写，放在一起最麻烦：

处理办法是拆成两个工具，一个只读，一个只写。读的那个宽松，写的那个严格。

1
def refund(order_id: str, amount: float, reason: str):
2
    order = query_order(order_id)              # 读
3
    if order["status"] != "paid":
4
        raise ValueError("订单状态不允许退款")
5
    return create_refund(order_id, amount)     # 写

1
def get_refund_eligibility(order_id: str) -> dict:
2
    """查询订单是否可以退款，不改变任何状态。"""
3
    ...
4

5
def create_refund(order_id: str, amount: float, request_id: str):
6
    """发起退款。request_id 是幂等键，同一个键重复调用只会退一次。"""
7
    ...

拆开之后，权限、审计和审批都能分开配。get_refund_eligibility 谁都能调，create_refund 要写权限，金额超过阈值还要人工确认。合成一个工具的时候，这两套规则没法同时挂上去。

7. 落到代码#

1
LAYERS = {
2
    "readonly": {"approval": False, "retry": 3, "parallel": True},
3
    "write_low": {"approval": False, "retry": 1, "parallel": False},
4
    "write_high": {"approval": True, "retry": 0, "parallel": False},
5
    "system": {"approval": True, "dual_review": True, "retry": 0, "parallel": False},
6
}
7

8
def call_tool(layer, name, args, request_id):
9
    spec = LAYERS[layer]
10
    validate(args)                                  # schema 校验
11
    if spec["approval"] and not approved(layer, name, args):
12
        raise NeedApproval(layer, name, args)       # 挂起等人确认
13
    if name in IDEMPOTENT and seen(request_id):
14
        return cached_result(request_id)            # 幂等命中，返回上次结果
15
    return dispatch(name, args)

8. 走一遍退款#

用户说「我要退款，订单 12345」，整条路径是这样的：

flowchart TD
  A[用户：我要退款，订单 12345] --> B[查订单，只读]
  B --> C[查物流，只读]
  C --> D[查退款政策，只读]
  D --> E{满足退款条件?}
  E -- 否 --> F[回复不满足并说明原因]
  E -- 是 --> G{金额大于 1000?}
  G -- 否 --> H[发起退款，幂等]
  G -- 是 --> I[人工审批]
  I -- 批准 --> H
  I -- 驳回 --> F
  H --> J[写审计日志]
  J --> K[通知用户]

每一步的分层待遇：

前面三步都是只读，可以并行，查错了没有后果。从「发起退款」开始收紧：这次调用会真的把钱转出去，所以它没有重试次数，靠幂等键防重复，超过阈值就停下来等人。

9. 新手常踩的四个坑#

1. 把读和写塞进同一个工具。 名字叫 manage_order，里面既能查又能改，权限和审批没法配。拆成 get_order 和 update_order 两个。
2. 把业务规则写进工具描述。 「退款金额不要超过 1000」写在描述里，模型未必照做。阈值判断放调用层。
3. 动作工具没有幂等键。 网络超时之后重试，同一个订单可能退两次款。参数里带上 request_id，服务端按它去重。
4. 小项目也照搬五层。 如果只是内部工具，没有资金和对外发送，读和写两层就够。分层是为了控制风险，层数超过实际风险就只剩开销。

10. 检查清单#

• 每个工具属于哪一层，写在代码或文档里了吗？
• 读和写是不是分开的？
• 动作工具有幂等键吗？
• 阈值和审批规则挂在调用层，还是写在提示词里？
• 每层的日志能单独查吗？
• 新增一个工具，要改几处代码？