OpenAI Agents SDK 遇到 MaxTurnsExceeded 怎么排查【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python用 openai-agents-python 的Runner.run/Runner.run_sync/Runner.run_streamed跑 Agent 时如果运行没有正常结束而是抛出MaxTurnsExceeded含义很直接Agent 的循环轮次即 LLM 调用次数超过了你传入的max_turns限制Agent 没能在规定轮次内完成任务。官方文档在 docs/running_agents.md 的 Exceptions 一节确认了这个异常的触发条件运行超过传给Runner方法的max_turns时抛出。下面的排查和处理路径都基于该文档、docs/release.md 的版本记录与 docs/guardrails.md 中的说明。先弄清“一轮”是怎么算的理解轮次计数才能判断为什么轮数会一直涨。docs/running_agents.md中 The agent loop 一节描述了Runner的循环逻辑用当前输入调用当前 Agent 的 LLM对 LLM 输出做分类被判定为final output循环结束返回结果。判定规则是产生了期望类型的文本输出且没有 tool calls请求了handoff切换当前 Agent 与输入重跑循环产生了tool calls执行工具、把结果追加到输入重跑循环超过传入的max_turns时抛出MaxTurnsExceeded。由此可以得出第一条排查判断如果模型不断发起 tool call 或 handoff、始终不产出符合 final output 判定条件的文本轮次就会一直累加直到触发异常。默认值方面源码 src/agents/result.py 中为max_turns: int | None 10即不显式传参时按 10 轮计。异常消息本身也带轮次信息源码 src/agents/run.py 中构造的是MaxTurnsExceeded(fMax turns ({max_turns}) exceeded)所以类似Max turns (10) exceeded的消息可以直接告诉你触发时生效的上限值。检查异常上的 run_data 细节MaxTurnsExceeded继承自AgentsException见 src/agents/exceptions.py基类带有run_data字段用来承载失败时与本次运行相关的细节。文档中明确写到该机制的地方是 docs/guardrails.md其他由 runner 管理的失败例如MaxTurnsExceeded会把已完成的工具 guardrail 结果保留在run_data.tool_input_guardrail_results和run_data.tool_output_guardrail_results列表中对run_streamed的场景stream_events()抛出异常后streamed result 同样暴露这些累积的 guardrail 结果列表注意当异常在 runner 管理的执行路径之外抛出时run_data可能是None。也就是说如果你的 Agent 配了工具级 guardrail捕获异常后可以通过exc.run_data查看停止前各轮已经完成的 guardrail 执行结果用来判断运行停在哪个阶段。处理方案提限、禁用限制或优雅降级按文档给出的手段有三种按侵入性从低到高1. 调大max_turns或设为None禁用限制如果任务本身就合理需要更多轮次多工具、多 handoff把max_turns调大即可。注意 docs/release.md 中 0.16.0 的记录Runner.run、Runner.run_sync和Runner.run_streamed从该版本起才接受max_turnsNone来禁用轮次限制。如果你使用低于 0.16.0 的版本只能传更大的整数。2. 注册max_turns错误处理器返回受控输出docs/running_agents.md的 Error handlers 一节说明所有Runner入口点都接受error_handlers参数以错误种类为键的字典支持的键是max_turns、model_refusal和invalid_final_output。用max_turns可以在超限后返回一个受控的最终输出而不是让运行以异常结束from agents import ( Agent, RunErrorHandlerInput, RunErrorHandlerResult, Runner, ) agent Agent(nameAssistant, instructionsBe concise.) def on_max_turns(_data: RunErrorHandlerInput[None]) - RunErrorHandlerResult: return RunErrorHandlerResult( final_outputI couldnt finish within the turn limit. Please narrow the request., include_in_historyFalse, ) result Runner.run_sync( agent, Analyze this long transcript, max_turns3, error_handlers{max_turns: on_max_max_turns} if False else {max_turns: on_max_turns}, ) print(result.final_output)上面示例即文档中的写法error_handlers{max_turns: on_max_turns}final_output的具体文案请按自己的业务改。RunErrorHandlerResult.include_in_history默认是True对 max-turns 处理器这会把合成的兜底输出追加到会话历史并写入已配置的 session。如果只想把兜底结果返回给调用方、不进历史和 session就显式设include_in_historyFalse。3. 确认根因不是模型拒绝导致的空转排查轮次耗尽时还有一个值得核对的版本相关变化docs/release.md 中 0.15.0 记录模型拒绝现在会显式抛ModelRefusalError而不再被视为空文本输出对 structured outputs之前拒绝会导致运行循环一直重试到MaxTurnsExceeded。所以如果你的 Agent 用的是结构化output_type且在 0.15.0 之前观察到拒绝时反复重试直到MaxTurnsExceeded的现象升级到该版本或更高后这类情况会以ModelRefusalError出现可用error_handlers{model_refusal: ...}处理升级后仍遇到MaxTurnsExceeded说明轮次超限是独立的循环问题回到前面两种处理。嵌套 Agent 运行的轮次是独立的如果你的架构是 sandbox agent 被Agent.as_tool(...)包成工具参考 docs/sandbox/guide.md 和 docs/tools.md注意文档中的说明嵌套运行有自己的 turn loop、max_turns、审批和通常独立的 sandboxRunConfig从外层编排器看这些工作都藏在一次工具调用后面嵌套轮次不会增加外层运行的 turn 计数。agent.as_tool本身也支持传入max_turns等运行参数。这条对排查的意义是外层运行抛MaxTurnsExceeded时可以排除内层嵌套运行消耗了外层轮次这一种猜测问题出在外层循环自身外层模型持续发 tool call / handoff 而不产出 final output。验证修复是否生效用错误处理器时重新运行确认不再抛异常result.final_output是你处理器返回的兜底输出文档示例即通过print(result.final_output)展示。调大或禁用max_turns后重新运行同一输入确认运行正常返回结果而不触发异常。需要说明的是max_turnsNone只表示禁用轮次上限release notes 的表述文档并不承诺任务一定成功循环行为本身仍由模型输出决定。如果你依赖 guardrail 结果定位停止阶段捕获异常后检查exc.run_data中对应的 guardrail 结果列表确认其内容与停止前的轮次吻合遇到run_data为None时先确认异常是否发生在 runner 管理的执行路径之外。相关文档docs/running_agents.mdAgent 循环、max_turns、error_handlers与异常总览docs/release.mdmax_turnsNone0.16.0与ModelRefusalError0.15.0的版本记录docs/guardrails.md失败时run_data中保留的 guardrail 结果docs/sandbox/guide.mdAgent.as_tool嵌套运行的独立max_turns【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考