一个 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)
这段代码把五类责任混在了一起:
- 模型能否选择正确工具;
- 参数是否符合 Schema;
- 失败是否应该重试;
- 重复请求是否应该再次产生副作用;
- 调用过程能否追踪和复盘。
更稳妥的边界是:模型只负责提出“想调用什么”,执行器决定“这次调用是否允许、怎样执行、失败后怎样处理”。
执行器不是另一个 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
第 次失败后的等待上限为:
然后在 中随机取实际等待时间:
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 个测试:
- 参数缺失时处理函数一次也不执行,审计事件不包含原始邮件内容;
- 前两次暂时失败、第三次成功时,恰好执行三次;
- 永久错误不会重试;
- 超时默认不会重试;
- 相同键和相同参数再次调用时直接回放结果;
- 相同键搭配不同参数时拒绝执行;
- 两个并发重复请求共享一次真实执行。
并发测试的核心断言是:
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 才不只是“会调用工具”,而是开始具备可恢复、可追踪、可验证的执行能力。