---
title: "将智能体工具层当作公共 API 来设计"
canonical: "https://siyuanailab.com/curation/translations/87f50cccb897490c593832d17ff8b5e0-c1bf48c0aa656599e9abb8590974b710f4926f9b68660bf9e97e8c7c3139eab0/"
dateModified: "2026-11-01"
datePublished: "2026-11-01"
---

[返回日报条目](https://siyuanailab.com/curation/#entry/87f50cccb897490c593832d17ff8b5e0)

 

资料节译

 

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

 

[阅读原文](https://dev.to/dima_kruglov_608741d9a416/your-agents-tool-layer-is-a-public-api-design-it-like-one-57nl)

 

现有资料无法确认原文完整，本页只翻译已取得的材料。

 

现有原件无法确认图片是否齐全。

 

我把第一个代理交给真实用户使用时，它有 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`工具，那么你的分类就毫无意义。应剥离外部文本，或将其隔离标记。

 

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

 

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

 

- 每个已注册工具都有一个`side_effect`字段，注册表拒绝加载缺少该字段的工具。
 
- `write`和`destructive`工具必须有一个`idempotency_key`；运行时根据`run_id` + 工具 + 排序后的参数生成它，绝不从模型获取。
 
- 已设置每次运行的工具调用次数、墙钟时间和破坏性操作次数上限，并且达到上限时会抛出错误，而不是只记日志。
 
- 每个工具都有明确的超时设置，并且超时会取消底层工作。
 
- 凭证按每次运行单独签发且有效期短；其权限范围应限于工具实际调用所需的最少端点。
 
- 至少有一个`destructive`工具具备面向沙盒端点的试运行路径，而不是`if`分支。
 
- 工具输出有大小上限，采用“摘要加句柄”的模式；外部文本在交给模型前会被隔离标记。
 
- 你能回答“是什么阻止这次运行把同一件事做两遍？”而不提系统提示。

 

AI 翻译；具体表述请与原文对照。
