OpenAI Agents API 常见报错：原因与解法速查

OpenAI Agents API 的报错大多集中在四类：没配 API Key、跑超 max_turns、模型输出不符合预期、安全护栏（guardrail）触发。官方 Agents SDK 在异常模块里明确定义了这批错误，本文按「现象、原因、解法」逐条给出排查路径，全部以官方文档为准。

先对齐一个名词：日常说的 OpenAI Agents API，落地写代码时对应的是官方 Agents SDK（Python 包 openai-agents，底层走 Responses API）。下面所有异常名都来自 SDK 的官方异常定义页，可以直接对号入座。

第一步：确认 Key 和环境没问题

最常见的报错根本不是代码问题，而是环境变量。SDK 默认从 OPENAI_API_KEY 环境变量读 Key，而且是在首次调用前就要求就位（官方配置文档说明：Key 在第一次创建客户端时才解析，务必在首次模型调用前设置好）。

解法两条：

1. 终端里 export OPENAI_API_KEY='sk-...' 之后再运行程序。
2. 或在代码里用 set_default_openai_key('sk-...') 显式指定。

如果走的是 OpenAI 兼容的第三方端点，还需要设 OPENAI_BASE_URL。另外有一个官方文档明确写出的坑：给 OpenAIProvider 同时传 openai_client 和 api_key、base_url 这类参数，SDK 会直接抛 UserError，而不是静默忽略。两者只能二选一。

还没接触过 Agent 开发的话，先看什么是 AI Agent补齐概念，再照着Agent 工作流入门跑通第一个最小示例。

高频异常逐条排查

把官方异常定义整理成速查表：

其中 MaxTurnsExceeded 出现频率最高。官方运行文档写明：Runner 的循环在超过传入的 max_turns 时抛出这个异常。工具调用一多，模型在一轮任务里反复请求工具，默认上限很容易被打满，调试复杂任务时优先查这里。

官方口径

报错排查建议以这三个页面为准，建议收藏：

1. SDK 异常定义页：agents.exceptions 模块的全部异常类。
2. Running agents 文档：max_turns 与 agent 循环机制的官方说明。
3. Configuration 文档：Key、base_url 与客户端配置规则。

另外，如果看到的是 429 限流错误，那是账号级速率限制触发，和 SDK 异常是两回事，等限流窗口过去或降低并发即可，原理参考HTTP 429 是什么。

怎么预防下次再报错

1. 程序启动时就设好 OPENAI_API_KEY，别等运行中才补。
2. 长任务显式设置 max_turns，并在异常处理里利用官方提供的 RunErrorDetails，它能打印失败前的完整运行上下文，定位快得多。
3. 工具调用加超时配置，避免 MCP 工具挂死拖垮整个 run。

一句话带走：报错先分三类，环境问题查 Key 和 base_url，循环问题查 max_turns，模型与工具问题查 refusal 和超时，三类对应三条不同的排查路径。