AI Agent 为什么一上线就出错？从工具调用到 API 调试

一个能读取 Issue、检索代码库、修改文件并运行测试的编程 Agent，在演示环境里跑得很顺。单独问模型 “这个空指针异常可能出在哪”，它给出的修复建议条理清晰。但把同一套流程放进真实仓库、接上 CI、连续跑二十个 Issue 之后，失败开始以各种不体面的方式出现：工具参数缺字段、同一个读取操作被重复调用七次、测试没跑就宣布完成、HTTP 401 被当成 “工具暂时不可用” 直接重试到超时。

这不是某一个模型 “不够聪明” 的故事。模型的单轮回答质量，和 Agent 在真实执行链路中能否稳定完成任务，是两个不同的工程问题。前者靠基准分可以粗略衡量，后者需要把工具定义、API 协议、状态管理、错误处理和运行环境放在一起看。

下面按 Agent 的实际执行顺序，拆开这条链路里最常见的失败位置，以及可以落地的排查和验证方法。

一、Agent 的失败，很少发生在 “模型会不会回答” 这一层

普通聊天的主要评价标准是回答是否合理。Agent 不一样：它需要连续完成多个步骤，并根据每一步的执行结果决定下一步做什么。一次任务可能包含模型调用、工具调用、外部 API 请求、结果校验和错误恢复，任何一环断裂，最终任务都会失败，而最终回复却可能仍然 “看起来正常”。

Google 在 2026 年 10 月公开的 Agent 评测文章里描述了一个典型案例：客服 Agent 接到 “查退款进度”，订单号为空，它自行重试了三次，又调用退款详情，最后根据缓存信息回复 “退款正在处理中”。用户暂时没有发现异常，测试截图里也有一个合理答案。但这条链路至少暴露四个风险：缺少订单号时没有停下、重复调用浪费额度、缓存信息可能不属于当前订单、多个失败工具被最终文本掩盖。

这个案例的价值在于它说明了一件事：Agent 最危险的错误，往往不是 “答错了”，而是 “答案看起来对，但执行轨迹已经坏了”。只断言最终回复是否包含某个关键词，上述四个风险全部会被判为通过。

更系统的量化数据来自 reliability 研究。τ-bench 显示，GPT-4o 在零售 Agent 任务上的 pass@1 为 61%，但 pass@8 只有 25%—— 也就是说，当同一任务运行八次时，至少出现一次失败的概率接近 75%。Thinkingbox 基准进一步给出了状态化业务流程中的落差：Claude Opus 5 从 pass@1 的 66.50% 降到 47.53%，Kimi-K3 从 57.37% 降到 17.60%（pass^20）。这些数字指向同一个结论：单次成功率和重复调用下的可靠性，不是同一个指标。

二、先把执行链路画出来：Function Calling 不执行函数

在讨论失败之前，需要先固定一个常被模糊的概念。Function Calling（也常被称为 Tool Calling）指的是模型根据工具描述和用户目标，生成结构化的工具名称和参数请求。模型负责生成 tool_calls，应用负责解析、校验、执行，再把结果回传给模型。模型本身并不直接运行函数。

阿里云开发者社区对此有一个清晰的表述：Function Calling 本质上是 “模型的结构化输出能力” 加 “协议规约”，不是模型获得了 “执行函数” 的能力。火山引擎的 Agent 调用实践文档也把链路拆成 “模型输出工具调用请求 — 应用执行 — 结果回传” 三个独立环节。

这意味着 Agent 的失败至少可以落在四个不同的层：模型生成的工具选择和参数是否正确、应用的解析和校验是否健壮、外部工具或 API 是否按预期返回、运行时是否正确处理了失败和重试。把所有问题笼统归为 “模型不行”，会让排查停在最没有信息量的那一层。

典型的执行链路可以概括为：
任务输入 → 模型分析并决定是否调用工具 → 生成工具名与参数 → 应用校验参数并执行 → 工具返回结果 → 模型判断成功或进入修正 / 重试 → 循环直到完成或触发终止条件。

三、五类高频失败：现象、原因与排查重点

1. 工具调用失败：模型选了工具，但不是你想要的那个

Redpanda 的 Agent 排查文档列出了一个直接的信号：如果工具调用卡片显示的是一个意料之外的工具，通常意味着模型在名称相似或描述模糊的工具之间做了选择。工具数量越多、描述越笼统，选择错误的概率越高。

排查重点不在模型本身，而在工具定义。减少同类工具的冗余、把名称改到语义可区分、在描述中写清楚 “什么时候该用” 和 “什么时候不该用”，比反复换模型更有效。

1. API 请求报错：401、429 和超时不是同一种错误

外部 API 返回错误时，最常见的错误处理方式是 “重试”。但 HTTP 401 通常指向鉴权失败，重试不会让凭证变得有效；429 是限流，需要退避而不是立即重发；5xx 可能是上游服务故障，超时可能是工具执行过慢或网络问题。把这几种情况放进同一个 except 分支无差别重试，会把一个本应快速失败的问题拖成长时间挂起。

Redpanda 的文档在 “Access denied” 一节中特意区分了 “授权拒绝” 和 “上游失败”：前者不是用户拒绝，也不是系统故障，而是 Agent 或测试者缺少某项权限。如果错误处理不区分这两类，排查方向从一开始就会偏。

1. 参数格式不正确：JSON Schema 对了，不代表参数语义对了

Redpanda 将 “工具调用卡片带校验错误” 归因为模型发送的参数与工具 Schema 不匹配，推荐的修法是收紧参数描述并在系统提示中加入示例。但更隐蔽的一类问题是 Schema 校验通过、字段类型正确，参数语义却是错的：路径指向不存在的文件、ID 属于另一个租户、时间范围写反。

火山引擎的文档记录了一个与参数生成稳定性直接相关的现象：多轮工具调用效果随轮数增加而下降，原因之一是思考内容没有回传，导致每一轮工具返回后丢失了上一轮的推理上下文。这不是 Schema 问题，而是 Agent 运行时没有把模型需要的状态完整地带入下一轮。参数错误的排查，因此不能只盯着单次请求的 JSON，还要检查轮次之间的上下文回传是否完整。

1. Agent 陷入循环：缺少终止条件，还是工具返回从未满足预期

循环的典型信号是同一个工具以相同参数被反复调用，或者任务到达最大迭代次数仍未完成。Redpanda 给出了两个常见原因：工具返回了 Agent 不知道如何处理的错误，或者 Agent 没有识别出任务已经完成。

这两种原因对应的修法不同。如果是前者，需要让工具返回结构化的错误信息，而不是一段模糊的自然语言；如果是后者，需要在提示词或运行时中加入明确的终止条件和步数上限。把循环简单归因为 “模型太笨”，往往会忽略工具返回值本身就不具备可解析性这个更前置的问题。

1. 最终答案正确，任务实际上没有完成

这是 Google 那篇文章里最值得记住的一类失败：Agent 烧掉大量 Token、重复调用工具，最后交出一段通顺、礼貌、甚至看起来正确的回答，但它声称完成的操作并没有发生在真实环境中。Google 的表述很直接：最终答案看起来没问题，已经不足以证明 Agent 可以上线；真正昂贵和危险的错误，往往发生在最终输出之前。

对应到编程 Agent，这意味着不能只看它说 “测试通过”，而要检查测试命令是否真的执行、退出码是什么、文件是否被修改、修改是否被写回。任务成功应当由可执行的状态断言来定义，而不是由模型的自我报告来定义。

四、API 接入方式如何影响 Agent 的稳定性

Agent 的失败分析走到外部 API 这一层，就会遇到一个无法回避的事实：不同模型服务的工具调用协议、参数生成行为和错误语义并不完全一致。“兼容 OpenAI 格式” 解决的是请求结构，不解决行为一致性。

协议层面的差异是真实存在的
腾讯云的一篇跨模型适配分析指出，多模型应用最大的挑战不是接口调用方式不同，而是不同模型对指令的理解、工具调用规范和上下文管理方式存在差异。即使都支持类似 OpenAI API 的格式，System Prompt 的执行效果、Function Calling 参数生成稳定性以及工具调用流程仍可能出现明显差异。

具体到 2026 年 10 月的公开记录，差异可以落到接口层面：GPT-6.1 Sol 的 Chat Completions 不支持带工具，需要走 Responses API；Gemini 4 Argon 的 Chat Completions 可用工具，但 Responses 不支持；DeepSeek V4 系列同样在 Chat Completions 上可用，Responses 上不支持。Gemini 的工具声明使用 functionDeclarations，模型返回 functionCall，结果通过 functionResponse 回传，并且 Gemini 3 需要保留匹配的 id。DeepSeek 的 Chat Completions 风格则支持 tool_choice、thinking mode tool calls 和 beta strict schema。

这些差异意味着：把一个在 A 模型上跑通的 Agent 循环迁移到 B 模型，不能只替换模型名。工具定义的位置、并行调用的处理方式、工具结果的回传格式、思考内容是否需要显式拼回下一轮，都需要重新验证。火山引擎的文档甚至记录了一个更隐蔽的情况：同一模型的不同版本可能属于不同的 “思考内容回传类别”，升级版本时如果不同步更新调用代码，回传方式会失效，而且不会触发 API 报错。

错误处理、模型切换和调用记录
在网络异常、超时、限流和服务端错误之间做区分，是 Agent 运行时的基本职责。但多模型接入会让这件事变得更复杂：不同供应商的状态码语义、重试建议和速率限制窗口并不相同。统一的重试策略可能在 A 供应商上合理，在 B 供应商上造成更严重的限流。

模型切换同样需要谨慎。当一个模型在特定任务上持续失败时，切换是合理的动作，但切换后必须重新评估工具调用的参数稳定性、并行调用的行为和长上下文下的表现，而不是假设 “换了更强的模型就会自动变好”。

调用记录的完整性直接决定排查效率。建议每次调用至少保存：模型版本、请求参数、工具定义快照、Token 用量、响应时间、状态码、工具调用结果和失败原因。当同一个 Agent 在不同模型或不同轮次之间表现不一致时，这些记录是把 “感觉不稳定” 转化为可定位问题的唯一依据。

在多模型并行接入的场景中，统一接入层可以减少逐个维护不同协议、密钥和端点的重复工作。KoalaAPI 这类 API 中转站的作用是把多个模型的调用入口收拢到一套兼容协议下，但它不改变各模型自身的工具调用行为和错误语义，协议差异仍然需要在应用层验证。

五、建立可复现的 Agent 测试体系

Google 的评测路径给出了一个反直觉但实用的起点：第一天不要急着做自动评分，先人工读一批完整的 Trace。如果团队还不知道 Agent 真实会怎样失败，自动生成的评分标准大概率只是把想象中的风险写得更工整。建议从 10 到 20 条高风险链路开始，每条 Trace 保留用户输入、模型版本、提示词哈希、工具名、参数、参数来源、工具返回、重试次数、最终回复、Token 和延迟。

覆盖五类任务的测试集
一套有区分度的 Agent 测试集，至少应当覆盖：
正常完成的任务，确认基础链路可用，作为对照组。工具返回异常的任务，检查 Agent 是否在收到结构化错误后停止、修正或合理降级。参数缺失的任务，检查模型能否识别缺失字段并主动补全，而不是带着空参数继续调用。外部 API 超时的任务，检查重试是否有上限、退避是否有策略、终止是否可预期。需要多轮操作的任务，检查状态是否在轮次之间丢失、是否出现重复执行同一副作用操作。

每次测试应当记录的指标

表格

Google 的评测路径还强调，成本、延迟和工具副作用应当进入上线门禁，而不只是作为观测指标。一个 Agent 即使在 80% 的任务上给出了正确回复，如果另外 20% 的任务在失败前执行了不可逆的写操作，这个成功率不能支撑生产上线。

RELY-SE 的工作提供了一个补充视角：仅看任务成功率（TSR）不够，还需要同时看提交失败率（CFR）和人工干预率（HIR）。在其示例数据中，Claude Code 的 TSR 为 68.5%、CFR 为 3.6%，而 AutoCodeRover 的 TSR 为 14.7%、CFR 为 13.6%—— 两者的差距在只看正确性的评测中不可见，但对 CI 稳定性是决定性的。

六、Agent 的 API 成本不是单价乘以一次调用

Agent 的一项任务通常包含多轮模型调用，每一轮的输入都可能携带前几轮的工具返回和对话历史。工具返回如果很长 —— 比如读取了一个大文件或查询了一大段日志 —— 后续每一轮请求的输入 Token 都会因此膨胀。按 “单次请求单价 × 任务数” 估算预算，会系统性低估 Agent 的真实成本。

更合理的估算方式，是把一次任务拆成若干轮调用，逐轮累计输入与输出 Token 的计费金额，再按实际模型的缓存折扣、分时定价和长上下文档位分别核算。不能用一个平均单价覆盖全部轮次，因为不同轮次的输入长度、缓存命中情况和输出规模往往差异很大。

提示词缓存在这里的影响是实质性的。主流供应商的缓存读取价格通常是基础输入价的 0.1 倍，DeepSeek V4 在空闲时段可以低至 0.032 倍。一个 30 轮、20K Token 前缀的 Agent 会话，在 90% 缓存命中率下，DeepSeek V4 Flash 的成本可以从 $0.184 降到 $0.064。

但缓存对前缀的逐字节精确匹配有要求：前缀中任何一个字节变化、切换模型、或路由到不同的工作节点，都会导致缓存失效并触发全量 prefill。这意味着在 Agent 循环中，System Prompt、工具定义和固定上下文应当尽可能保持稳定；如果每一轮都动态改写工具描述或调整会话参数，缓存命中率会显著下降。火山引擎的文档也把 “System Prompt 或工具定义在轮次间发生变化” 列为缓存命中率异常偏低的常见原因。

重试策略同样有成本后果。没有上限的重试不仅可能重复执行副作用操作，还会在每次重试中重新发送完整上下文。步数上限、超时和单任务预算上限，应当作为 Agent 运行时的默认配置，而不是可选项。

在多模型接入的场景中，统一入口可以减少逐个供应商维护计费规则和端点的工作量。KoalaAPI 在这类架构中承担的是调用聚合的角色，但成本是否更低，仍然要以实际模型价格、请求用量和服务条款核算为准。

七、从原型到生产：Agent 是系统，不是模型

把前面几部分收拢，生产环境中的 Agent 需要的不只是 “一个能生成合理回答的模型”，而是模型、工具、权限、状态管理和运行环境共同构成的系统。这个系统至少在以下几个方面需要明确约束：

工具权限最小化。Agent 不应默认拥有写文件、执行命令或调用生产 API 的全部权限。只读操作和写操作应当分开授权，高风险操作需要人工确认。Redpanda 的排查文档中，“Access denied” 被单独列出，正是因为权限拒绝和工具失败是两类需要不同处理路径的事件。

输入与工具返回的校验。外部输入和工具返回内容都可能携带意外的指令。对工具返回的结构化解析、对自由文本的边界检查、以及不在系统提示中无条件信任工具输出，是降低提示词注入风险的基本动作。

执行步数、超时和预算上限。这三项应当作为运行时强制约束，而不是依赖模型 “自己停下来”。Google 的案例已经说明，Agent 可能在烧掉大量 Token、重复调用工具之后仍然给出一个看起来合理的回答。

保留可复盘执行轨迹。模型版本、工具定义、参数来源、重试次数和最终状态，需要能够回答 “这个任务为什么被判定为成功或失败”。没有轨迹，回归测试和故障定位都只能靠猜测。

回到开头的问题：一个 Agent 在单独测试时表现合理，一上线就出错，原因通常不在 “模型不够聪明” 这个笼统的判断里，而在工具描述是否可区分、参数在轮次之间是否完整传递、错误是否被分类处理、执行结果是否被真实校验、以及缓存和重试是否被纳入成本与稳定性设计。把这些层面分别验证、分别约束，Agent 的可靠性才从 “演示可用” 变成 “可上线” 的候选。

了解更多：https://koalaapi.com/