OpenAI Agents SDK 工程笔记：AgentsException 族、失败分类与生产恢复禁区

千笔-AIWritePaper · https://www.aiwritepaper.com线上 Agent 挂掉时最危险的操作是「反正再跑一遍」。OpenAI Agents SDK 把运行失败收进AgentsException族回合耗尽、模型行为异常、调用方误配、模型超时、工具超时、护栏触发等。它们有的挂着run_data快照有的根本不在这个族里例如缺OPENAI_API_KEY时的openai.OpenAIError。能不能重试取决于异常类型 是否幂等 是否已经产生写副作用不取决于值班同学的耐心。本文在openai-agents 0.23.1下用脚本化假模型离线实跑故意触发回合耗尽、未知工具、坏结构化 JSON、误配call_model_input_filter、缺密钥以及超时后盲目整段重试导致charge副作用翻倍。全部结果进_w/agents-exception-smoke/的 CSV 与smoke_output.txt。图上排为 AgentsException 族与恢复分类中部为 Runner.run 成功/抛错路径与 run_data 字段底部为 F1至F5 实测禁区。目标说明读完你应能独立完成五件事。按类型把失败分进三桶条件可重试、不可重试、必须人工介入并把缺密钥等基础设施错误单独隔离。在except AgentsException里读取exc.run_data若有把raw_responses、new_items、last_agent写入结构化日志。用max_turns故意打爆一轮确认抛出MaxTurnsExceeded且run_data.raw_responses条数等于预算。对写工具路径禁用「整段 Runner.run 重试」超时只允许在幂等读路径或带幂等键的补偿路径重试。把 5 条失败样本写进禁区表和告警分级盲目重试翻倍、原样重跑耗尽、吞异常伪造成功、缺密钥空转、坏工具 JSON 伪健康。适用与边界适合已经在跑Runner.run/run_sync/run_streamed需要统一异常出口、日志字段与告警要把「再试一次」写成可执行策略写进口头习惯不够。不讲tool 循环与单工具超时调参细节、as_tool、MCP 接线、guardrails 设计、lifecycle hooks、ModelSettings、RunContext、SQLiteSession 落盘见 10-02 A。护栏触发类异常只在分类表里占位本文不展开 tripwire 业务规则。失败含义假模型按脚本返回调用用来固定触发路径「有没有挂上 run_data」「缺密钥是否属于 AgentsException」「坏工具 JSON 会不会默默回灌错误串」由 SDK 与 Runner 决定。ModelTimeoutError的分类用例直接构造异常对象验证分桶真实超时依赖ModelSettings.timeout以你安装版本为准。机制异常族、返回路径、日志字段类型典型触发恢复分桶告警建议MaxTurnsExceededmax_turns用尽人工介入加预算或拆任务P1/P2带 run_dataModelBehaviorError未知工具、坏结构化 JSON、非法工具载荷不可重试修工具表或输出约束P1禁止自动重跑UserError调用方误配如 filter 返回类型错不可重试修代码/配置P1走发布门禁ModelTimeoutError模型调用超过 timeout仅幂等可读路径可重试P2写路径要幂等键ToolTimeoutError工具timeout_behaviorraise_exception视工具是否幂等P2护栏 tripwire 诸类输入/输出/工具护栏触发默认人工或降级策略按业务定级openai.OpenAIError等缺密钥、凭据、网络基建不在AgentsException 族禁盲目重试P0 配置/密钥Runner.run成功时返回RunResult读final_output。失败时抛上述异常Runner 会尽量把当时的input、new_items、raw_responses、last_agent、护栏结果塞进exc.run_dataRunErrorDetails。日志至少落四类字段exc_type、exc_message、run_id/trace_id、run_data摘要响应条数、最后 agent 名、new_items 类型直方图。告警分级建议配置/密钥 → P0Behavior/User → P1 且禁止自动重跑MaxTurns → P1/P2 并附预算Timeout → P2由幂等标记决定是否进入重试队列。可选的error_handlers如max_turns/model_refusal/invalid_final_output可以把部分错误收成受控final_output它替代抛错不会替你撤销已经执行过的写工具。把它当成产品文案降级可以当成「副作用自动回滚」不行。fromagentsimportAgent,Runner,MaxTurnsExceeded,ModelBehaviorError,UserErrorfromagentsimportModelTimeoutError,AgentsExceptiondefclassify(exc:BaseException)-str:ifisinstance(exc,MaxTurnsExceeded):returnhuman_interveneifisinstance(exc,ModelTimeoutError):returnretryable_if_idempotentifisinstance(exc,(ModelBehaviorError,UserError)):returnnon_retryableifisinstance(exc,AgentsException):returnagents_other_no_blind_retryreturninfra_config_no_retrytry:resultawaitRunner.run(agent,user_input,max_turns8)exceptAgentsExceptionasexc:log.exception(agent_failed,extra{exc_type:type(exc).__name__,recover:classify(exc),raw_n:len(exc.run_data.raw_responses)ifexc.run_dataelse0,agent:exc.run_data.last_agent.nameifexc.run_dataelseNone,})raise离线 smoke6 条通过 5 条失败P1 PASS 回合耗尽 MaxTurnsExceededrun_data - raw_responses3 new_items6 last_agentbudget side_effects3 P2 PASS 未知工具名触发 ModelBehaviorError - Tool no_such_tool not found P3 PASS output_type 解析失败 ModelBehaviorError - Invalid JSON when parsing model output P4 PASS call_model_input_filter 误配 UserError - must return a ModelInputData instance P5 PASS 缺 OPENAI_API_KEY 落在 infra 层 - openai.OpenAIError agents_excFalse P6 PASS ModelTimeoutError 分类为条件可重试 - timeout_seconds1.5 F1 FAIL 超时后盲目整段重试导致写副作用翻倍 - charge:99 × 2 F2 FAIL 回合耗尽后原样重跑仍耗尽 - second MaxTurnsExceeded F3 FAIL 吞掉 ModelBehaviorError 伪造成功 - returned_okTrue F4 FAIL 缺密钥盲目重试空转 - OpenAIError × 3 F5 FAIL 坏工具 JSON 未抛异常仅回灌错误串 - raisedFalse saw_tool_error_stringTrue CSV rows: 11逐条读法。P1max_turns3时模型每轮都调charge抛MaxTurnsExceededrun_data.raw_responses恰好 3且副作用日志已有 3 条。预算耗尽前写工具可能已经发生。P2模型点名不存在的工具默认行为抛ModelBehaviorError可改为tool_not_found_behaviorreturn_error_to_model回灌那是另一条产品策略。P3output_type为 Pydantic 模型时助手只回非 JSON 文本抛ModelBehaviorError: Invalid JSON when parsing model output。P4call_model_input_filter返回了普通字符串抛UserError。这是调用方代码病重试无意义。P5不设密钥走默认真模型路径得到openai.OpenAIError它落在 AgentsException 族外。只写except AgentsException会漏掉它。P6ModelTimeoutError(1.5)进入「条件可重试」桶是否真重试还要看路径幂等。F1工具已charge:99随后模拟超时调用方把整段Runner.run再跑一遍副作用变成两条。这是写路径盲目重试的标准事故。F2第一次max_turns2耗尽后不改预算、不拆任务原样再跑第二次仍然MaxTurnsExceeded。F3except ModelBehaviorError后直接return {ok: True}监控显示成功用户拿到空结果。F4缺密钥连打三次三次同一基建错误告警风暴与空耗。F5工具参数是{not-json时SDK 默认把错误串写进function_call_output让模型继续整次 run 成功返回。没有异常不等于工具健康。生产禁区表编号禁区实测证据替代做法D1超时后整段重跑含写工具的 runF1charge:99× 2写工具带幂等键超时只重试未确认的读步骤D2MaxTurns 后原样同预算重跑F2第二次仍耗尽升预算、拆子任务或走error_handlers[max_turns]给受控文案D3吞掉 Behavior/User 当成功F3okTrue必须记账并失败返回CI 禁止裸 exceptD4缺密钥/凭据当可重试F4空转 × 3启动期校验密钥该类进 P0重试队列直接拒绝D5「没抛异常」当成工具成功F5错误串回灌扫描function_call_output错误模式指标单独计数D6只 catchAgentsExceptionP5OpenAIError 漏网外层再接基建异常字段进同一日志模式告警与重试对照分桶谁进自动动作人工动作条件可重试幂等读上的ModelTimeoutError有限次退避重试超限后升级不可重试ModelBehaviorError/UserError不重试记 P1修工具表、输出约束或配置人工介入MaxTurnsExceeded可选受控降级文案加预算或拆任务并看 run_data基建禁重试缺密钥等非 Agents 异常拒绝入队修密钥与网络最小复现断言「写副作用不会因超时翻倍」smoke 里用内存列表当账本。你的项目里换成数据库幂等表即可。SIDE[]function_tooldefcharge(amount:int)-str:SIDE.append(fcharge:{amount})returnfcharged:{amount}# 业务层同一 payment_id 只允许成功落账一次asyncdefrun_payment(payment_id:str):ifalready_charged(payment_id):returnduplicate-ignoredawaitRunner.run(pay_agent,fpay{payment_id},max_turns5)mark_charged(payment_id)CI 断言模拟「成功扣费 随后超时 调用方重试」后SIDE.count(charge:99) 1或账本行数唯一。谁把整段 run 当重试单元谁就红。常见误判「catch 住了 AgentsException 就等于覆盖所有运行失败」P5 证明缺密钥走另一条继承树。「run 返回了 final_output 说明工具都成功」F5 证明坏 JSON 可以只回灌错误串仍算跑完。「error_handlers 接住 max_turns 就等于没副作用」P1 在抛错前已经执行了 3 次chargehandler 只改返回不回滚。「超时都可以重试」只有幂等读或带幂等键的写才可以F1 是反例。与已写主题的咬合相邻主题关系一句话tool 循环 / 超时专文单工具超时策略本篇管异常出口与是否允许整段重跑guardrails 专文tripwire 如何设计本篇只把 tripwire 放进分桶表ModelSettingstimeout 等旋钮来源本篇消费超时异常的恢复边界SQLiteSession10-02 A失败时历史是否仍在异常与 session 正交run_data 不替代会话库日志字段最小集生产里建议每条失败日志固定带这些键方便和 trace 对上。字段来源用途exc_typetype(exc).__name__分桶与看板recover上文classify(exc)决定是否入重试队列messagestr(exc)截断值班可读raw_nlen(run_data.raw_responses)对照 max_turnsitem_histnew_items 的 type 直方图看失败前是否已调工具last_agentrun_data.last_agent.name多 agent 时定位side_effect_hint业务侧幂等表查询判断能否安全重试trace_idRunConfig / 追踪系统串联模型与工具跨度缺side_effect_hint时超时重试决策会退化成猜。P1 已经证明回合耗尽前charge可以发生三次你若只看异常类型、不看账本就会把「已经扣过」的请求再次送进 Runner。与 error_handlers 的边界SDK 允许为max_turns、model_refusal、invalid_final_output注册 handler返回受控final_output。这在产品层很有用例如告诉用户「本轮步数不够请缩小范围」。工程上要同时记住三件事。handler 成功后调用方看到的是正常RunResult监控若只盯异常率会漏报。include_in_history默认可能把降级文案写入会话设False可避免污染下一轮上下文。已执行的写工具不会因为 handler 而回滚。P1 的三次charge在抛MaxTurnsExceeded之前已经进了副作用日志。因此 handler 属于对外文案与流程降级不属于恢复禁区的豁免条款。禁区表里的 D1/D2 仍然成立。验收清单所有Runner.run调用点有统一classify 结构化日志含run_data摘要。写工具具备幂等键超时重试测试断言副作用不翻倍。MaxTurnsExceeded不进入无脑重试队列。ModelBehaviorError/UserError禁止自动重跑CI 有裸 except 检查。启动期校验 API 密钥缺密钥进 P0 而非重试。CI 跑_w/agents-exception-smoke/smoke.pyP 系列 PASSF 系列保持可复现。当天 30 分钟落地5 分钟搜仓库里所有Runner.run列出 except 范围是否覆盖非 Agents 异常。10 分钟接入上文classify日志加上exc_type/recover/raw_n。5 分钟给支付/写库类工具补幂等键加一条「超时重试不翻倍」测试。5 分钟MaxTurns 与 BehaviorError 的告警从「自动重跑」改成「工单」。5 分钟把agents-exception-smoke.csv存进仓库升级 SDK 时复跑对照。配置对照四个问题定恢复策略问题是否失败路径上是否已执行写工具禁止整段重跑查幂等表才可考虑有限次退避异常是否为 Behavior / User修代码与工具表再看超时或 MaxTurns是否 MaxTurnsExceeded人工改预算或拆任务不要用同预算重跑碰运气是否族外基建错误P0 修密钥与网络不要丢进 Agents 重试队列这四问可以直接做成网关中间件的分支。谁跳过第一问谁就会复现 F1。踩坑把「再跑一遍」写进 on-call 手册的第一步F1/F2/F4 都会被手册合法化。只在网关层 catch Exception 并返回 200F3 的假阳性会直接进用户报表。看见 tool output 里有英文 error 仍展示「已完成」F5 的静默失败最常见于演示环境。用升max_turns掩盖未知工具或坏 JSON那是把 BehaviorError 熬成 MaxTurnsrun_data 更难看。假设error_handlers会撤销工具副作用SDK 文档写明它不重放、不回滚副作用。总结AgentsException族给出的是可观测的失败类型。它本身不附带「自动恢复许可证」。Runner.run成功走RunResult失败走带或不带run_data的异常缺密钥等基建错误还在族外。生产能不能扛住取决于分桶、幂等与告警超时后整段重跑、耗尽后原样重跑、吞掉 BehaviorError、缺密钥空转、把错误串回灌当成健康都会在账本或监控里留下可复现伤口。把 5 条失败写进禁区表升级 SDK 时复跑同一份 smoke。本文实跑版本为openai-agents 0.23.1字段名以你安装的版本为准若run_data或error_handlers语义有变先以官方 Running agents / Exceptions 文档与本目录 CSV 对照。写作与实验流程可用千笔-AIWritePaper 整理实验记录与禁区表站点见文首链接。P1 PASS 回合耗尽 MaxTurnsExceededrun_data - msgMax turns (3) exceeded run_dataTrue raw_responses3 new_items6 last_agentbudget side_effects3 P2 PASS 未知工具名触发 ModelBehaviorError - typeModelBehaviorError msgTool no_such_tool not found in agent tools classnon_retryable P3 PASS output_type 解析失败 ModelBehaviorError - typeModelBehaviorError msgInvalid JSON when parsing model output P4 PASS call_model_input_filter 误配 UserError - typeUserError msgcall_model_input_filter must return a ModelInputData instance P5 PASS 缺 OPENAI_API_KEY 落在 infra 层 - typeopenai.OpenAIError agents_excFalse classinfra_config_no_retry