Agent 工具执行层实战:超时、重试、幂等与审计

1 阅读13分钟

一个 Agent 能正确选择 send_email,并不等于这封邮件就能安全发出。

真实执行中还可能发生:

  • 模型漏传参数,或者额外生成了工具不接受的字段;
  • 上游服务临时返回 503,第一次失败、第二次成功;
  • 请求超时,但远端实际上已经完成发送;
  • 工作流恢复后重复执行同一个节点,用户收到两封邮件;
  • 日志只留下“工具失败”,无法确认调用了几次、为什么重试;
  • 为了排错把邮件正文、令牌等敏感参数全部写进日志。

这些问题不能靠一句“请谨慎调用工具”的 Prompt 解决。Prompt 影响模型决策,执行层负责在模型之外强制落实约束。

本文用 Python 和 Pydantic 实现一个最小工具执行器:

模型生成工具参数
        ↓
Pydantic 参数校验
        ↓
幂等键占位与请求摘要比对
        ↓
超时边界 + 分类重试
        ↓
执行真实工具
        ↓
保存成功结果 + 写入审计事件

代码不依赖 LangGraph,但可以放在 ToolNode、工作流节点或 FastAPI 服务与真实工具之间。

1. 为什么要在工具外再包一层

许多 Agent 项目的调用链是:

tool_name = model_output["name"]
arguments = model_output["arguments"]
result = await tools[tool_name](**arguments)

这段代码把五类责任混在了一起:

  1. 模型能否选择正确工具;
  2. 参数是否符合 Schema;
  3. 失败是否应该重试;
  4. 重复请求是否应该再次产生副作用;
  5. 调用过程能否追踪和复盘。

更稳妥的边界是:模型只负责提出“想调用什么”,执行器决定“这次调用是否允许、怎样执行、失败后怎样处理”。

执行器不是另一个 Agent,也不需要大模型参与。它应尽量是确定性代码,行为可以通过测试验证。

2. 先定义工具参数,而不是信任模型 JSON

以发送邮件为例:

from pydantic import BaseModel, ConfigDict, Field


class EmailArgs(BaseModel):
    model_config = ConfigDict(extra="forbid")

    recipient: str = Field(min_length=3)
    subject: str = Field(min_length=1, max_length=100)
    body: str = Field(min_length=1, max_length=1000)

extra="forbid" 很重要。默认忽略未知字段虽然宽松,却可能掩盖模型生成的错误参数名。例如模型输出 email_to,而工具需要 recipient,静默丢弃会让问题更难定位。

执行前调用:

args = EmailArgs.model_validate(raw_args)

Pydantic 模型既能描述字段,也能完成验证与序列化。官方文档将 BaseModel 定义为创建数据 Schema 的主要方式,并提供 model_validate() 验证输入。Pydantic Models

校验失败后不要把完整 ValidationError 原样写进审计日志,因为错误对象可能包含用户输入。本文只保留字段位置和错误类型:

safe_details = [
    {
        "location": list(item["loc"]),
        "type": item["type"],
    }
    for item in error.errors()
]

工具参数错误属于调用方错误。它不应进入重试循环,因为相同参数重试十次仍然无效。正确做法是把结构化错误反馈给工作流,让模型修正参数,或者直接结束当前操作。

3. 错误必须分类,不能见异常就重试

本文将执行错误分成四类:

类型示例默认处理
参数错误缺字段、类型错误、额外字段不执行工具,返回安全错误
可重试错误503、限流、临时连接失败有上限地退避重试
永久错误收件人被禁用、无权限、业务规则拒绝立即失败
未知错误代码 Bug、意外异常立即失败并报警

对应的异常类型很简单:

class ToolExecutionError(Exception):
    pass


class RetryableToolError(ToolExecutionError):
    pass


class PermanentToolError(ToolExecutionError):
    pass


class ToolTimeoutError(ToolExecutionError):
    pass

不要把所有 Exception 都当成暂时错误。假设工具内部出现 KeyError,盲目重试只会重复触发相同 Bug,还会放大流量和日志噪声。

真正决定错误类型的通常是适配器:HTTP 适配器可以把 429、502、503 转成 RetryableToolError,把 400、401、403 转成永久错误;数据库适配器可以根据驱动异常和事务状态进行分类。

4. 重试需要上限、指数退避和随机抖动

重试策略定义为:

from dataclasses import dataclass


@dataclass(frozen=True)
class RetryPolicy:
    max_attempts: int = 3
    base_delay_seconds: float = 0.2
    max_delay_seconds: float = 2.0
    retry_on_timeout: bool = False

第 nn 次失败后的等待上限为:

dn=min⁡(dmax,dbase×2n−1)d_n=\min(d_{max}, d_{base}\times 2^{n-1})

然后在 [0,dn][0,d_n] 中随机取实际等待时间:

delay_cap = min(
    policy.max_delay_seconds,
    policy.base_delay_seconds * (2 ** (attempt - 1)),
)
await asyncio.sleep(random.random() * delay_cap)

随机抖动的目的不是让单个请求更快,而是避免大量失败请求在同一时刻整齐重试,再次压垮刚恢复的服务。

AWS 的可靠性资料把指数退避、jitter、幂等和事务列为提升分布式系统容错能力的常见技术,并强调只有幂等事务才能安全地重复执行。AWS Availability and Beyond

本文只对明确抛出的 RetryableToolError 自动重试。达到 max_attempts 后,最后一次错误继续向上抛出,不再隐藏失败。

5. 超时最危险的误解:超时不等于没有执行

Python 可以用 asyncio.wait_for() 限制一次异步调用:

result = await asyncio.wait_for(
    tool.handler(args, context),
    timeout=tool.timeout_seconds,
)

官方文档说明,超时发生时 wait_for() 会取消被等待对象并抛出 TimeoutError;它还会等待取消真正完成,所以实际等待时间可能略超过设定值。Python asyncio.wait_for

但这只描述本地协程,不代表远端副作用被撤销。

例如:

0 ms    本地发出“发送邮件”请求
300 ms  邮件服务完成发送
500 ms  响应在网络中丢失
1000 ms 本地超时

本地只看见超时,用户却已经收到邮件。如果立刻重试,可能发送第二封。

因此本文默认:

retry_on_timeout = False

只有同时满足以下条件,才考虑对超时自动重试:

  • 下游 API 本身接受幂等键;
  • 每次重试传递完全相同的键;
  • 下游保证相同键不会重复产生副作用;
  • 幂等记录的有效期覆盖重试窗口。

本地执行器的缓存只能阻止“执行器收到两次相同请求”,不能阻止“一次请求内部重试时远端重复执行”。真正的端到端幂等必须把键传到产生副作用的最下游。

6. 幂等键不能只是一个缓存键

一个可靠的幂等层至少要区分三种情况:

相同键 + 相同参数 + 已完成 → 返回上次结果
相同键 + 相同参数 + 执行中 → 等待同一个执行
相同键 + 不同参数           → 拒绝,防止键被误用

只检查键、不检查参数会出现危险情况:

第一次:key=order-18,amount=100
第二次:key=order-18,amount=1000

如果第二次直接返回第一次结果,调用方可能误以为 1000 元操作已经执行。本文先将经过 Pydantic 验证的参数规范化,再计算 SHA-256:

def digest(value: dict) -> str:
    canonical = json.dumps(
        value,
        ensure_ascii=False,
        sort_keys=True,
        separators=(",", ":"),
    )
    return hashlib.sha256(
        canonical.encode("utf-8")
    ).hexdigest()

并发重复请求如何处理

内存存储为第一个请求创建 Future:

async def acquire(self, key: str, payload_digest: str):
    async with self._lock:
        entry = self._entries.get(key)

        if entry is None:
            future = asyncio.get_running_loop().create_future()
            self._entries[key] = Entry(
                payload_digest=payload_digest,
                state="in_progress",
                future=future,
            )
            return Reservation("owner", future=future)

        if entry.payload_digest != payload_digest:
            raise IdempotencyConflictError(
                "same key, different payload"
            )

        if entry.state == "completed":
            return Reservation("hit", result=entry.result)

        return Reservation("join", future=entry.future)

第一个请求成为 owner,真正调用工具;同时到达的请求执行:

result = await asyncio.shield(reservation.future)

shield() 防止某个等待者被取消时,顺带取消所有请求共享的工具任务。Python 文档同时提醒,传给 shield() 的 Task 应保留强引用,避免执行中被垃圾回收。Python asyncio.shield

owner 成功后保存结果并唤醒等待者;失败则移除占位,使之后的新请求有机会重新执行。

AWS Powertools 的幂等文档同样区分 INPROGRESS 和已完成记录,并说明并发收到相同 payload 时需要锁定,不能让第二个执行同时产生副作用。AWS Powertools Idempotency

幂等键应该从哪里来

幂等键应表示一个稳定的业务操作,例如:

thread_id:order_id:send_confirmation
user_id:document_id:publish_version_3
payment_id:create_refund

不要在每次重试前重新生成随机 UUID,否则每一次都会被视为新操作。也不要跨租户直接复用业务编号;生产键通常还要包含 tenant 或 user 范围。

7. 一个可测试的 ToolSpec

工具定义包含参数模型、处理函数、超时和重试策略:

from dataclasses import dataclass
from typing import Any, Awaitable, Callable


@dataclass(frozen=True)
class ExecutionContext:
    idempotency_key: str
    attempt: int


ToolHandler = Callable[
    [BaseModel, ExecutionContext],
    Awaitable[Any],
]


@dataclass(frozen=True)
class ToolSpec:
    name: str
    args_model: type[BaseModel]
    handler: ToolHandler
    timeout_seconds: float
    retry_policy: RetryPolicy = RetryPolicy()

ExecutionContext 会把相同幂等键传给每一次内部尝试。真实适配器应继续把它放进下游请求头或业务参数,而不是只留在本地日志里。

8. 核心执行流程

省略数据类和日志辅助函数后,主流程如下:

async def execute(
    self,
    tool: ToolSpec,
    raw_args: dict,
    *,
    idempotency_key: str,
):
    # 1. 参数校验
    try:
        args = tool.args_model.model_validate(raw_args)
    except ValidationError as error:
        self.audit_validation_error(tool, raw_args, error)
        raise ToolValidationError(...) from error

    args_digest = digest(args.model_dump(mode="json"))
    store_key = f"{tool.name}:{idempotency_key}"

    # 2. 幂等占位
    reservation = await self.idempotency_store.acquire(
        store_key,
        args_digest,
    )

    if reservation.mode == "hit":
        self.audit_idempotency_hit(tool, args_digest)
        return reservation.result

    if reservation.mode == "join":
        return await asyncio.shield(reservation.future)

    # 3. owner 执行;只缓存成功结果
    try:
        result = await self.run_with_policy(
            tool,
            args,
            idempotency_key,
            args_digest,
        )
    except BaseException as error:
        await self.idempotency_store.fail(store_key, error)
        raise

    await self.idempotency_store.complete(store_key, result)
    return result

重试循环只负责一次 owner 调用:

async def run_with_policy(self, tool, args, key, digest):
    policy = tool.retry_policy

    for attempt in range(1, policy.max_attempts + 1):
        context = ExecutionContext(key, attempt)
        started = time.perf_counter()

        try:
            result = await asyncio.wait_for(
                tool.handler(args, context),
                timeout=tool.timeout_seconds,
            )
        except TimeoutError as error:
            can_retry = (
                policy.retry_on_timeout
                and attempt < policy.max_attempts
            )
            self.audit("timeout", attempt, started)
            if not can_retry:
                raise ToolTimeoutError(...) from error
        except RetryableToolError:
            self.audit("retryable_error", attempt, started)
            if attempt == policy.max_attempts:
                raise
        except PermanentToolError:
            self.audit("permanent_error", attempt, started)
            raise
        except BaseException:
            self.audit("unexpected_error", attempt, started)
            raise
        else:
            self.audit("success", attempt, started)
            return result

        delay_cap = min(
            policy.max_delay_seconds,
            policy.base_delay_seconds * 2 ** (attempt - 1),
        )
        await asyncio.sleep(random.random() * delay_cap)

这里故意没有做“智能错误判断”。执行器只相信适配器给出的明确错误类型,避免根据异常文本猜测是否重试。

9. 审计日志应该记什么,不应该记什么

本文每次尝试记录:

@dataclass(frozen=True)
class AuditEvent:
    occurred_at: str
    tool_name: str
    idempotency_key_hash: str
    args_digest: str
    attempt: int
    status: str
    duration_ms: float
    error_type: str | None = None

status 可以是:

validation_error
retryable_error
retry_exhausted
permanent_error
timeout
success
idempotency_hit
idempotency_join
idempotency_conflict

审计事件没有记录 body、收件人、令牌和异常消息,只记录参数摘要与错误类型。这样仍能判断“两次请求是否使用相同规范化参数”,却不会直接暴露正文。

生产系统还可以增加:

  • trace ID、workflow ID、thread ID;
  • 模型请求 ID 与工具调用 ID;
  • 租户和用户的不可逆标识;
  • 下游 HTTP 状态码;
  • 重试原因与最终结果位置。

需要排错的原始参数应进入有单独权限、保留期限和脱敏策略的安全存储,而不是普通应用日志。

10. 七个测试验证哪些不变量

本文代码使用 unittest.IsolatedAsyncioTestCase 编写了 7 个测试:

  1. 参数缺失时处理函数一次也不执行,审计事件不包含原始邮件内容;
  2. 前两次暂时失败、第三次成功时,恰好执行三次;
  3. 永久错误不会重试;
  4. 超时默认不会重试;
  5. 相同键和相同参数再次调用时直接回放结果;
  6. 相同键搭配不同参数时拒绝执行;
  7. 两个并发重复请求共享一次真实执行。

并发测试的核心断言是:

first_result, second_result = await asyncio.gather(
    first,
    second,
)

self.assertEqual(first_result, second_result)
self.assertEqual(1, handler_calls)

我在 Windows 11、Python 3.13.7、Pydantic 2.12.5 环境运行了完整测试集,7 个测试全部通过;最终复核运行耗时约 0.15 秒。

这只验证示例执行器的状态机,不代表外部邮件服务、数据库持久化、跨进程竞争和线上延迟已经测试。尤其是内存幂等存储,进程重启后记录会全部丢失。

11. 接入 LangGraph 时放在哪里

执行器可以放在实际副作用节点内部:

async def send_confirmation_node(state, config):
    thread_id = config["configurable"]["thread_id"]
    order_id = state["order_id"]

    key = f"{thread_id}:{order_id}:send_confirmation"
    result = await executor.execute(
        send_email_tool,
        {
            "recipient": state["email"],
            "subject": "订单确认",
            "body": state["confirmation_text"],
        },
        idempotency_key=key,
    )

    return {"email_message_id": result["message_id"]}

工作流 checkpoint 解决“从哪里恢复”,幂等层解决“恢复后副作用是否会重复”。二者不能互相替代。

如果节点已经成功发送邮件,却在写 checkpoint 前崩溃,恢复后仍可能再次进入该节点。稳定的业务幂等键会让第二次调用返回第一次结果,而不是重新发送。

12. 从示例升级到生产还缺什么

12.1 持久化与原子占位

内存字典只能处理单进程并发。生产环境可以使用:

  • MySQL/PostgreSQL 唯一键和条件更新;
  • Redis SET NX 加状态与过期时间;
  • DynamoDB conditional write;
  • 具备去重语义的任务队列。

核心要求是“检查不存在并写入 IN_PROGRESS”必须原子完成,否则两个进程仍可能同时成为 owner。

12.2 IN_PROGRESS 租约与崩溃恢复

owner 崩溃后,记录不能永久停留在执行中。需要保存租约到期时间,并为不同工具设置合理 TTL。

但过期也有风险:远端操作可能仍在执行。高风险工具需要结合下游幂等、业务状态查询或人工处理,不能只看本地 TTL 就重新执行。

12.3 结果序列化与大小限制

成功结果可能包含不可序列化对象或大量数据。幂等存储应定义稳定结果 Schema,只保存后续恢复需要的字段,例如 message_id,而不是完整 SDK 响应。

12.4 权限和审批

可靠执行不代表有权执行。删除、付款、改权限等高风险工具还要经过授权校验、策略引擎或人工审批。幂等层只是防止同一操作被重复做,不负责判断操作本身是否应该发生。

12.5 指标与告警

至少观察:

  • 各工具成功率;
  • 参数校验失败率;
  • 每次成功前的平均尝试次数;
  • 超时率和重试耗尽率;
  • 幂等命中与冲突数量;
  • P50、P95、P99 执行时延。

只有结构化审计事件,没有聚合指标,仍然很难快速发现某个工具正在持续退化。

结语

Agent 工具调用的可靠性不能只看“模型有没有选对工具”。真正产生副作用之前,还需要一层确定性执行协议:

Pydantic 拦截错误参数
错误分类决定能否重试
指数退避与抖动控制重试节奏
超时边界限制单次等待
幂等键阻止重复副作用
请求摘要发现键与参数冲突
审计事件还原每次尝试

其中最值得记住的边界是:超时不等于没有执行,本地幂等也不等于端到端幂等。

把这两点处理清楚后,Agent 才不只是“会调用工具”,而是开始具备可恢复、可追踪、可验证的执行能力。

参考资料