当大模型从”问答助手”进化为能调用外部工具的智能体，大模型工具调用的可靠性就成了生产系统的命门。一次工具超时、一个幻觉出的错误参数、或下游服务宕机，都可能让整个对话链路雪崩。本文聚焦工具调用的可靠性工程：用超时、重试、幂等与熔断，把”可能翻车”的链路变成”稳得住”的服务。
一、为什么工具调用比纯聊天更容易翻车
纯文本生成是自包含的——模型算完就返回，没有外部依赖。但一旦接入工具（查订单、发短信、调支付、跑 SQL），链路里就多了”模型”和”外部系统”两个不确定源。常见的四类翻车现场：
- 超时：下游接口慢，调用方一直挂起，线程池被占满；
- 幻觉参数：模型编造不存在的字段或枚举值，工具直接报错；
- 外部故障：数据库主从切换、第三方限流、网络抖动；
- 重复执行：重试把同一笔订单下了两遍，破坏幂等。
如果你刚接触 Function Calling，建议先读《Function Calling 工具调用实战指南》把调用链路跑通，再回来补这一层的工程化加固。
二、超时控制：别让一次调用卡死整条链路
2.1 给模型侧的调用也设上限
即便模型本身很少”卡住”，也要给 HTTP 请求层强制超时。下面用 Python 的 httpx 为例，给工具服务统一加上超时与连接池限制：
import httpx
# 连接 3s、读 8s、写 5s；超过即抛 TimeoutException
client = httpx.Client(
timeout=httpx.Timeout(connect=3.0, read=8.0, write=5.0, pool=2.0),
limits=httpx.Limits(max_connections=50, max_keepalive_connections=20),
)
def call_weather_tool(city: str) -> dict:
try:
r = client.get("https://api.internal/weather", params={"city": city}, timeout=8.0)
r.raise_for_status()
return r.json()
except httpx.TimeoutException:
# 交给上层走降级逻辑，不要原地重试到天荒地老
raise ToolTimeout("weather tool timed out")
2.2 把”外部慢”和”模型慢”分开度量
很多团队只盯着模型推理延迟，却忽视了工具服务的 P99。建议把”模型决策耗时”和”工具执行耗时”分别打点，这样超时发生时能立刻定位是哪一段。可结合《SSE 流式响应实战》把长链路进度实时推给前端，避免用户以为页面卡死。
三、重试策略：指数退避 + 抖动
瞬时抖动（网络闪断、限流 429）适合重试，但盲目重试会放大故障。正确做法是指数退避 + 随机抖动（jitter），并限制最大次数：
import asyncio, random
async def retry_with_backoff(fn, max_retries=3, base=0.5):
last = None
for i in range(max_retries):
try:
return await fn()
except (ToolTimeout, httpx.TransportError) as e:
last = e
if i == max_retries - 1:
break
# 退避 = base * 2^i + 随机抖动，避免"重试风暴"对齐
wait = base * (2 ** i) + random.uniform(0, 0.3)
await asyncio.sleep(wait)
raise last
# 用法：把工具调用包一层即可
result = await retry_with_backoff(lambda: call_weather_tool("Shanghai"))
3.1 什么能重试，什么不能
重试的前提是幂等。只读查询（查天气、查库存）随便重试；写操作（下单、扣款、发短信）必须带上幂等键，否则重试一次就重复一次。这条规则下文细说。
四、优雅降级：工具挂了，对话照样能进行
可靠性不是”永不失败”，而是”失败了也能兜住”。当工具连续失败，与其让智能体抛出 500，不如降级为”用模型自身知识回答 + 明确提示能力受限”：
def run_agent_with_fallback(user_msg: str) -> str:
try:
return agent.invoke(user_msg) # 正常走工具
except ToolUnavailable:
# 降级：关闭工具、仅用模型知识，并显式告知
return llm.complete(
f"{user_msg}\n[注意：外部工具暂不可用，以下为模型通用知识，仅供参考]"
)
在 Java 体系里，《LangChain4j 实战》和《Spring AI 实战》都提供了 @Tool 与 ChatMemory 机制，可以把上面的 try/except 收敛成统一的 Advisor（拦截器），在工具异常时自动切降级分支。
五、幂等设计：避免重试把订单下了两遍
所有写类工具都必须支持幂等键（Idempotency-Key）。调用方生成一次 UUID，下游用唯一索引去重：
# 调用方：每次业务动作生成稳定的幂等键
import uuid
idem_key = f"order-{user_id}-{action_id}" # 业务维度，而非随机 uuid
r = client.post("https://api.internal/order",
json={"item": item, "idem_key": idem_key},
headers={"Idempotency-Key": idem_key})
# 下游（伪代码）：用唯一约束挡住重复
# INSERT INTO orders (idem_key, ...) VALUES (%s, ...)
# ON CONFLICT (idem_key) DO NOTHING; -- 第二次重试直接忽略
关键点：幂等键要由业务语义生成（同一笔”用户 A 的退款动作”永远同一个 key），而不是每次请求随机生成——否则重试等于新请求，去重毫无意义。
六、用熔断器挡住连环雪崩
当下游持续失败时，继续重试只会把压力转嫁过去、并拖垮调用方。熔断器（Circuit Breaker）在错误率超阈值时”跳闸”，直接快速失败，给下游喘息时间：
from pybreaker import CircuitBreaker
breaker = CircuitBreaker(fail_max=5, reset_timeout=30)
@breaker
def call_payment_tool(payload: dict) -> dict:
return client.post("https://api.internal/pay", json=payload).json()
# 跳闸期间调用会抛 CircuitBreakerError，接降级逻辑即可
try:
return call_payment_tool(payload)
except pybreaker.CircuitBreakerError:
return run_agent_with_fallback("支付工具暂时不可用")
七、可观测：把每次工具调用都记下来
可靠性工程离不开观测。至少记录：工具名、入参（脱敏）、耗时、结果状态、重试次数。把这些 span 串到一条链路里，排障时一目了然。可接入《Langfuse 实战：LLM 应用链路与成本可观测》，或用《LiteLLM 多模型网关》统一做网关层埋点。若你的智能体跑在私有化环境，《Dify + Ollama 本地部署》也内置了调用日志，足够小团队起步。
八、生产落地检查清单
上线前对照下表逐项确认，缺一项就多一分半夜被叫醒的风险：
| 加固项 | 必须做 | 可选增强 |
|---|---|---|
| 超时 | 每个工具调用强制超时 | 区分连接/读/写超时 |
| 重试 | 指数退避 + 抖动，≤3 次 | 按错误类型决定是否重试 |
| 幂等 | 写操作带幂等键 | 下游唯一索引兜底 |
| 降级 | 工具不可用不抛 500 | 降级分支显式告知用户 |
| 熔断 | 错误率超阈值跳闸 | 半开探测自动恢复 |
| 观测 | 记录工具名/耗时/状态 | 链路追踪 + 成本看板 |
九、用故障注入验证可靠性，而不是上线后才发现
上面六条写进代码只是起点，真正验证它们”有没有用”，要靠故障注入（Chaos Testing）。很多团队在联调环境一切正常，一上生产就被真实的网络抖动打穿——因为从没人为制造过故障。最简单的做法是在工具服务前面挂一个”故障代理”，按比例随机返回超时或 500：
# 故障代理（伪代码）：10% 概率注入超时，验证调用方是否真的兜底
import random
def fault_proxy(handler):
if random.random() < 0.10:
raise httpx.TimeoutException("injected timeout")
if random.random() < 0.05:
return Response(500, "injected 500")
return handler()
# 跑一轮压测：观察重试是否生效、熔断是否跳闸、降级是否返回、幂等是否守住
# 全绿才算通过，否则回到对应小节补强
9.1 在网关层统一加固，别让每个智能体各写一遍
当智能体数量变多，把超时、重试、熔断、观测下沉到网关是更省心的方案：业务代码只管"调什么工具"，治理逻辑由网关统一收口。《LiteLLM 多模型网关》就提供了这类统一接入与成本路由能力，可以复用它的中间件机制挂载重试与限流。这样无论新增多少个 Agent，可靠性底座都相同，不会出现"这个智能体有熔断、那个没有"的参差。
工具调用让大模型真正"动手做事"，但也把不确定的外部世界拉进了链路。超时兜底、重试有度、幂等护身、熔断止损、降级不崩、观测可溯——把这六条做成脚手架默认能力，你的智能体才配得上"生产可用"四个字。
