OpenAI Agents SDK 模型与 Provider 边界：架构参考、能力归属与重试安全指南

OpenAI Agents SDK 模型与 Provider 边界架构参考、能力归属与重试安全指南【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python本指南面向需要修改模型解析、ModelSettings、Provider 适配器、Responses 与 Chat Completions 行为差异、请求转换、流式终止事件、传输复用或模型重试的开发者。它源于仓库 .agents/references/model-provider-boundaries.md 这份内部架构参考并结合src/agents/models/、src/agents/run_internal/等源码与测试加以印证。读完本文你将掌握模型与 Provider 的抽象边界如何划分、模型名与隐式默认设置的解析优先级、能力归属与校验策略、Provider 数据与终止语义、持久传输资源的所有权模型以及重试与回放安全的核心约束。核心边界运行循环只依赖Model接口在 openai-agents-python 中运行循环run loop依赖的是Model接口而不是任何一家 Provider 的请求或响应 Schema。这是整个模型层的第一原则无论底层是 OpenAI Responses API、Chat Completions还是第三方的 LiteLLM / AnyLLM 适配器核心执行逻辑看到的都是统一抽象。从源码 src/agents/models/interface.py 可以看到这个边界的四个支柱Model.get_response()返回归一化后的ModelResponse而不是 Provider 原始响应对象。方法签名接收system_instructions、inputstr | list[TResponseInputItem]、model_settings、tools、output_schema、handoffs、tracing以及previous_response_id、conversation_id、prompt等可选参数。Model.stream_response()以异步迭代器AsyncIterator[TResponseStreamEvent]产出归一化的流式事件同时保留公开 raw-event 消费者所需的 Provider 原始载荷。ModelProvider.get_model()负责把模型名解析为具体的Model实现并持有 Provider 级的缓存或连接。ModelProvider的 docstring 明确写道Model provider is responsible for looking up Models by name.Model.close()与ModelProvider.aclose()在实现确实持有持久传输资源时释放它们两者的默认实现都是 no-op。Provider 适配器adapter负责请求构造、Provider 特性校验、终止事件解释、用量usage转换以及翻译成 SDK item 形状。核心运行循环中不应出现 Provider 特有的分支除非那属于所有 SDK 共享的契约。也就是说适配器是 Provider 差异的收容所运行循环是 Provider 中立的主干。模型与设置解析显式覆盖与隐式默认解析优先级模型实例的最终归属由RunConfig.model与agent.model共同决定。核心逻辑位于 src/agents/run_internal/turn_preparation.py 的get_model()若run_config.model是Model实例直接使用该实例若run_config.model是字符串则通过配置的ModelProvider.get_model(name)解析否则若agent.model是Model实例直接使用兜底通过run_config.model_provider.get_model(agent.model)解析 agent 的模型名。也就是说显式的RunConfig.model覆盖 agent 模型模型实例直接用模型名才经过ModelProvider解析。隐式默认设置必须跟随解析后的模型名一个容易被忽视的细节是隐式默认设置implicit default settings必须跟随最终解析出的模型名包括当 run 级模型名替换了 agent 默认值时。get_model_settings()turn_preparation.py的实现体现了这一约束def get_model_settings(agent: Agent[Any], run_config: RunConfig) - ModelSettings: model_settings agent.model_settings if model_settings _implicit_model_settings_for_agent(agent): model_settings _model_settings_for_resolved_name(agent, run_config) return model_settings.resolve(run_config.model_settings)其含义是当 agent 的model_settings恰好等于基于 agent 自身模型名推导出的隐式默认时就改用基于run 最终解析模型名推导的默认设置再与run_config.model_settings合并。合并语义非None覆盖 结构化字段特殊处理ModelSettings.resolve(override)src/agents/model_settings.py按覆盖非None值的规则把 run 级设置叠加到 agent 设置之上但对两个结构化字段做了特殊处理extra_args字典合并而非替换——先继承自身已有的键再用 override 的键覆盖retry通过_merge_retry_settings做字段级合并其中backoff再通过_merge_backoff_settings单独合并initial_delay、max_delay、multiplier、jitter各自非None即覆盖。这解释了文档中Preserve the documented merge behavior for structured fields such asextra_argsand retry settings的要求——直接整体替换会破坏这些字段的叠加语义。追踪边界to_traceable_dict()不要把 Provider 请求附加参数如extra_query、extra_body、extra_headers、extra_args默认传入追踪。ModelSettings.to_traceable_dict()model_settings.py是哪些设置对追踪安全且有意义的边界它只序列化_TRACEABLE_MODEL_SETTING_FIELDS中列出的白名单字段包括temperature、top_p、tool_choice、parallel_tool_calls、max_tokens、reasoning、store、retry、context_management、prompt_cache_options、timeout等 20 余项而把 Provider 特有的请求附加项挡在追踪之外。能力归属不要假设一个适配器有所有 Model 都有文档明确警告不要因为某个特性在一个适配器中可用就推断每个Model实现都支持它。能力归属遵循按协议分区的原则Responses 专属特性服务端托管的响应链server-managed response chaining、会话感知的请求字段conversation_id、工具命名空间tool namespaces、延迟工具加载deferred tool loading、工具搜索tool search、响应 includeresponse includes、压缩compaction、Responses websocket 传输。Chat Completions通常需要客户端托管的回放client-managed replay以及把 Responses 兼容的 SDK item 转换到 Chat Completions 请求。对不支持的服务器状态或工具特性按适配器声明的校验模式拒绝或显式忽略。Realtime拥有自己的会话协议、事件模型和服务端追踪不得把 Realtime 行为路由到标准的 Responses / Chat Completions 假设中。第三方模型适配器可能只保留共享的Model契约新增 Provider 特有字段必须有显式的转换与回退策略。以 OpenAI Chat Completions 适配器 src/agents/models/openai_chatcompletions.py 为例strict_feature_validation控制不兼容特性的行为默认False时对prompt、会话状态、reasoning.mode/reasoning.context等 Responses 专属字段只记录一次 warning 并忽略设为True时则直接抛出UserError。这正是按适配器声明的验证模式拒绝或显式忽略的实现。校验位置应放在适配器边界——即已解析的模型 完整请求都已确定的地方。避免出现SDK 公共标志看起来被接受了实际却在发往 Provider 之前被静默丢弃的情况。Provider 校验与错误归属单一事实来源不要复制 Provider 侧的校验文档给出了一条反直觉但重要的准则不要在 SDK 中重复 Provider 侧的请求校验仅仅为了更早失败。理由很实际复制 Provider 的语法、长度限制、枚举成员等约束会随 Provider 契约演进而漂移可能拒绝其他 Provider 本可接受的值会把一个 Provider 中立的 SDK 类型意外变成 Provider 特有的契约。当 Provider 已经用可操作的错误拒绝了非法值时就保留这个单一事实来源single source of truth。什么情况下才加 SDK 侧校验只有以下情况值得在 SDK 侧加校验它在维护SDK 自有的不变量或防止Provider 校验无法处理的确定性风险。文档列举的例子包括有歧义的本地路由ambiguous local routing请求序列化前的冲突collisions before request serialization无效的持久化状态invalid persisted state不安全的本地副作用unsafe local side effectsProvider 错误无法定位到具体 SDK 输入。想要更早失败或想要不同的错误信息这种泛化偏好不构成加校验的理由。当本地校验确有必要且约束是 Provider 特有的时候必须把它放在所属适配器边界从权威的 Provider 契约推导不要应用到共享的Model接口、Provider 中立的工具类型或第三方适配器。测试应当区分SDK 自有的不变量与特意留给 Provider 校验的值两类场景。Provider 数据与终止语义保留 Provider 提供的原始数据当公开 SDK 契约暴露了 Provider 提供的字符串 ID、request ID、用量usage和不透明的 Provider 数据时归一化过程中必须保留它们。以preserve_raw_usage设置为例model_settings.py启用后若适配器仍持有未归一化的 Provider usage 载荷ModelResponse.raw_usage会保存一份在 SDK 归一化缺失字段之前捕获的 JSON 兼容快照。归一化 Provider 对象与映射载荷时**不能依赖真值判断truthiness**来处理合法的空值或零值。如果一个字段有意把0当作None必须在归一化代码、文档与测试中显式声明该字段的特有约定而不是套用一条通用的可选数字规则。流终止 ≠ 成功响应这是最容易踩坑的语义点传输流结束并不自动等于一次成功的模型响应。Responses 的failed与incomplete终止事件、显式 error 事件以及缺失终止载荷的情况都必须在 HTTP 与 websocket 两条路径上产生文档规定的失败行为。对应实现见 src/agents/models/_response_terminal.pyformat_response_terminal_failure()会把终止事件类型与status、error、incomplete_details组合成可操作的错误消息response_terminal_failure_error()与response_error_event_failure_error()都构造ModelBehaviorError并通过_mark_error_to_drain_stream_events标记该错误以排空流事件。同时语义等价的 HTTP / websocket、流式 / 非流式路径必须在最终的ModelResponse、错误、request ID 与 usage 上保持一致。传输资源所有权持久连接的循环绑定文档用相当大的篇幅规范持久连接尤其是 Responses websocket 模型的资源生命周期。核心约束如下持久 Responses websocket 模型是循环绑定的资源loop-bound。可复用的 websocket 模型实例应按运行事件循环 模型名缓存绝不在不同循环之间共享同一个连接或asyncio.Lock。使用弱循环所有权weak loop ownership避免未使用的缓存把已关闭的事件循环钉住。当活跃连接本身钉住了已关闭的循环时用同步 abort 状态清理来修剪而不是在已关闭循环上 await。Provider 缓存持久模型时aclose()必须关闭每一个唯一的缓存模型并清空缓存尽可能在仍在运行的 owner 循环上关闭不要在asyncio.to_thread()里驱动一个不活跃的外部循环。没有运行循环就使用的模型不能安全加入循环级 websocket 缓存应保留不复用的回退路径而不是把它挂到某个任意的全局循环上。连接复用在以下情况后终止协议错误、终止前的断连、使帧结构失效的取消、显式关闭。连接与循环级锁状态必须一起清理防止后续请求复用半关闭的传输状态。从源码看OpenAIResponsesWebSocketModel的实现src/agents/models/openai_responses.py引入了weakref与显式的aclose()/close()路径来落实这些约束与文档中weak loop ownershipsynchronous abort and state clearing的要求一一对应。重试与回放安全重试是模型层最容易产生隐藏 bug 的领域文档给出了三条硬性准则1. Provider 重试建议优先于通用状态码假设Provider 的重试建议可以描述可重试性、延迟与回放安全replay safetyrunner 不得用通用的状态码假设替换 Provider 特有的证据。对应机制是Model.get_retry_advice(request)interface.pyModel 可覆盖它以提供传输或 Provider 特有的提示如回放安全、retry-after 延迟或服务端显式重试指引。ModelRetryAdvicesrc/agents/retry.py携带suggested、retry_after、replay_safety、reason、normalized与response_started字段。2. 有状态 / 有副作用的请求不自动具备回放安全使用服务端托管会话状态的请求或可能已产生副作用的请求不是自动回放安全的。重试策略必须考虑Provider 是否可能已经接受了上一次尝试。这一点在 src/agents/run_internal/model_retry.py 的_evaluate_retry()中落实得非常细_normalize_retry_error()会合并 Provider 建议provider_advice与原始异常推导的归一化错误随后用三重独立否决来阻止不安全的回放请求级回放否决如 Programmatic Tool Calling 携带的本地副作用——只有 Provider 所有的批准才能解除有状态请求携带previous_response_id/conversation_id含auto_previous_response_id场景默认 fail-closed因为后续依赖服务端状态应用可通过approve_unsafe_replay显式批准 Provider 标记为不安全的失败Provider 标记的回放不安全——只有显式批准_approves_replay或approve_unsafe_replay才能重试。此外流式请求一旦发出了用户可见的输出事件_stream_event_blocks_retry判定为除response.created、response.in_progress之外的事件就绝对禁止重试_is_abort_like_error与_is_network_like_error对 abort 类与网络类错误做严格识别。runner 还会对携带conversation_locked错误的请求保留最多 3 次的兼容性重试指数退避可通过max_retries0显式关闭。3. 保留异常语义防止敏感载荷泄漏重试转换与错误处理器必须保留原始异常的语义并避免通过链式异常、日志、追踪或 Provider 错误对象泄漏敏感请求载荷。这与仓库整体的敏感信息脱敏策略见_error_tracing与 trace 配置保持一致。默认重试参数速查runner 管理的重试ModelRetrySettings.backoff在 model_retry.py 中定义了以下默认值参数默认值说明initial_delay0.25秒首次重试前的基础延迟max_delay2.0秒两次重试间的最大延迟上限multiplier2.0每次重试后的延迟乘数jitterTrue是否在0.875x ~ 1.125x范围内施加随机抖动兼容性重试次数3COMPATIBILITY_CONVERSATION_LOCKED_RETRIESconversation_locked错误保留的旧行为重试上限流式安全的终止事件白名单为response.created与response.in_progress其余事件一旦发出即阻断重试。变更评审清单文档在末尾提供了一份七项评审清单适合作为任何涉及模型层变更的 PR 检查表明确该特性由哪个适配器拥有不支持的适配器如何表现加校验前先判定它保护的是 SDK 自有的不变量还是只是重复了 Provider 已有的可操作错误run 配置覆盖 agent 时验证模型与隐式设置的解析结果适用时对比 HTTP / websocket、流式 / 非流式的终止行为归一化过程中保留 request ID、usage、Provider 数据与错误语义证明重试对该请求的状态归属与副作用是安全的涉及持久连接时测试传输复用、跨循环访问、关闭循环的修剪以及 Provider 关闭。延伸阅读源码与测试路径模型接口与 Provider 抽象src/agents/models/interface.py模型设置与合并语义、追踪白名单src/agents/model_settings.py模型与隐式设置解析src/agents/run_internal/turn_preparation.pyOpenAI Responses 适配器含 websocket 持久连接与weakref生命周期src/agents/models/openai_responses.pyOpenAI Chat Completions 适配器strict_feature_validation与特性忽略策略src/agents/models/openai_chatcompletions.py多 Provider 路由前缀映射、openai_prefix_mode、unknown_prefix_mode、aclose()聚合关闭src/agents/models/multi_provider.py响应终止事件与失败语义src/agents/models/_response_terminal.py重试策略、回放安全否决与退避默认值src/agents/run_internal/model_retry.py、src/agents/retry.py相关测试tests/models/ 与 tests/test_config.py【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考