返回日报条目

资料节译

将智能体工具层当作公共 API 来设计

阅读原文

我把第一个代理交给真实用户使用时,它有 11 个工具,系统提示写着“执行任何破坏性操作前先请求确认”。它在预发布环境运行了六周。上线第二天,支付 API 返回 502,模型决定重试,而我的封装层照单转发,结果它把同一笔退款操作执行了三次。

这次故障和 LLM 没有关系。问题是缺少幂等键——这是任何 HTTP 客户端在代码审查中都会发现的同一种漏洞。区别在于,代理的重试决策由一个你无法查看的组件作出,重试频率无法预测,参数也不是你硬编码的。

我想强调的是:模型是调用方。你的工具就是 API。你对公共 API 的所有要求——版本控制、超时、幂等性、凭证范围、速率限制——在这里都适用,区别在于调用方是无意中带有对抗性的,而不是有意为之。

我见过的大多数工具注册表都按供应商分组:stripe.*、github.*、s3.*。这种分组无法说明风险。你实际需要的是给每个工具做三类划分:

读取——不会改变外部状态。可以安全重试、安全并行,也可以放在循环中运行。

写入——会创建或修改状态,但可以做到幂等。需要一个键。

破坏性操作——删除、撤销权限、发送给人工处理、转移资金。需要一个键,并且需要一个不由模型控制的关卡。

这种分类不是文档,而是强制措施。只有read工具可以放宽超时并允许无限次重试。destructive工具则必须经过外部审批步骤,或只能在试运行框架中运行。如果你无法把某个工具归入这三类之一,那你还没有充分了解它,不能把它开放出来。

我开头提到的故障有已知的解决办法,而且解决办法不是“告诉模型不要重试”。模型会重试。工具结果被截断、JSON 无法解析、429 看起来像暂时性错误、你升级了模型——这些情况都会引发重试。假设每次工具调用至少会发出两次。

因此,自己根据运行和参数生成键,再把它传给下游:

import hashlib, json, time
from dataclasses import dataclass
class Budget:
    """Hard stop per run. Not a metric â an exception."""
    def __init__(self, max_calls: int = 20, max_seconds: float = 120):
        self.calls = 0
        self.max_calls = max_calls
        self.deadline = time.monotonic() + max_seconds
    def charge(self) -> None:
        if self.calls >= self.max_calls or time.monotonic() > self.deadline:
            # Raise, don't return a string: the runtime converts it into a
            # tool error the model can see, and the loop terminates.
            raise RuntimeError("tool budget exhausted")
        self.calls += 1
@dataclass
class ToolSpec:
    name: str
    fn: callable
    side_effect: str          # "read" | "write" | "destructive"
    timeout_s: float = 5.0
REGISTRY: dict[str, ToolSpec] = {}
def tool(name: str, side_effect: str, timeout_s: float = 5.0):
    def wrap(fn):
        REGISTRY[name] = ToolSpec(name, fn, side_effect, timeout_s)
        return fn
    return wrap
def _stable_key(run_id: str, name: str, args: dict) -> str:
    # Sorted JSON so dict ordering from the model can't change the key.
    blob = json.dumps(args, sort_keys=True, separators=(",", ":"))
    return hashlib.sha256(f"{run_id}:{name}:{blob}".encode()).hexdigest()
@tool("refund.create", side_effect="write", timeout_s=8.0)
def create_refund(order_id: str, amount_cents: int, idempotency_key: str) -> dict:
    # Downstream API dedupes on idempotency_key; a second call is a no-op.
    return payments.refund(order_id, amount_cents, idempotency_key=idempotency_key)
def call(run_id: str, name: str, args: dict, budget: Budget) -> dict:
    budget.charge()
    spec = REGISTRY[name]
    if spec.side_effect != "read" and "idempotency_key" not in args:
        args = {**args, "idempotency_key": _stable_key(run_id, name, args)}
    # Production: run in a worker with spec.timeout_s and kill it on overrun.
    return spec.fn(**args)

有两点很重要。键根据run_id生成,而不是根据时间戳,因此同一次运行中的重试会真正成为空操作——但新的一次运行会得到新键;有人类再次提出请求时,这正是你想要的结果。键是根据排序后的 JSON 哈希生成的,所以模型先发出{"a":1,"b":2}、再发出{"b":2,"a":1}也无法蒙混过关。

这里有个会导致问题的做法:绝不能让模型自己提供idempotency_key。如果模型能选择键,它就能在重试时换一个新键,你就又回到了退款三次、还多费一道工夫的局面。

大家都很关注 token 预算,因为账单看得见。真正能保护你的是每次运行的操作次数。一次工具调用耗时 80 毫秒、不花任何 token,却仍然可能给客户发邮件、创建法律工单,或启动一台每小时 4 美元的虚拟机。循环中的代理会乐此不疲地这么做——故障模式不是恶意,而是模型觉得上次调用“没成功”,于是换个稍有不同的参数再试一次。

三个计数器,全部在运行时强制执行,而不是写在提示里:

每次运行的工具调用次数——我默认交互式代理为 20 次,批处理作业为 100 次。

每次运行的墙钟时间——每次调用前都要检查截止时间。模型并行发起多个调用时,长尾延迟会累积。

每次运行的写入调用次数——对destructive工具设置单独且严格得多的上限(通常为 1 次)。

预算触发时,把它作为工具错误呈现给模型,让模型完成运行。生成过程中直接杀掉进程,会丢失调试所需的调用轨迹。

对于destructive工具,最实用的做法是构建一种模拟模式:工具返回与实际操作结果形状相同的内容,却不真正执行操作。这和面向会操作设备状态的代理所用固件模拟器背后的思路相同:你不会想在真实设备群上才发现参数架构有误。

对某些工具而言,试运行成本很低(返回合成响应);对另一些工具而言,成本很高(需要影子数据库)。应明确说明每个工具的权衡。试运行路径漂移是个问题:模拟路径和生产代码共用同一份代码,只有一个if dry_run:提前返回;六个月后,模拟分支就可能缺少真实路径新增的某项校验。如果可以,把试运行做成一种凭证——让工具指向带只读密钥的沙盒端点,而不是在代码内部走分支。

超时取消封装调用,而不是取消实际工作。asyncio.wait_for用于 HTTP 调用没有问题;执行subprocess.run的线程在你停止等待后仍会继续运行。要终止整个进程组。

**工具输出被截断。**如果把 40KB 的 JSON 响应截成 2KB,模型看到的就是格式错误的 JSON,于是会重试,导致重复写入。应返回摘要和引用句柄,而不是截断后的内容。

**工具结果成为注入向量。**抓取的网页或工单正文都是不可信输入。如果read工具的输出能引导模型去调用write工具,那么你的分类就毫无意义。应剥离外部文本,或将其隔离标记。

**每次运行的凭证在运行结束后仍然有效。**每次运行都签发短时令牌;具有整个组织写入权限的服务账户,其影响范围大到无法纳入预算。

**把重试算作一次调用。**设置每次运行调用上限,目的就是应对模型内部对你不可见的重试循环。每次分发都要计数,包括重试。