openai-agents-python 模型设置完全指南：ModelSettings 参数详解、合并规则与底层实现

openai-agents-python 模型设置完全指南：ModelSettings 参数详解、合并规则与底层实现

【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python

导读

ModelSettings是 openai-agents-python 框架中统一管理 LLM 调用参数的入口对象，它覆盖 temperature、top_p、工具选择、截断策略、提示词缓存、重试策略与超时等全部可选配置。本文以 ModelSettings 参考文档 为骨架，结合 源码实现、序列化测试 与 模型配置指南，系统讲解每个字段的语义、resolve()合并机制、与RunConfig的覆盖关系，以及底层请求映射原理，帮助你精确控制每一次模型调用。

一、ModelSettings 是什么

在 openai-agents-python 中，Agent通过model指定模型，通过model_settings指定调用参数。ModelSettings是定义在 src/agents/model_settings.py 中的一个 pydantic dataclass，文档注释明确说明：

Settings to use when calling an LLM. This class holds optional model configuration parameters (e.g. temperature, top_p, penalties, truncation, etc.).

它被 SDK 导出在agents顶层命名空间（见 src/agents/init.py 中的ModelSettings、ModelRetrySettings、retry_policies导出）。需要注意文档中反复强调的一个事实：并非所有模型/提供商都支持全部参数，具体字段是否生效取决于你使用的模型与 API（Responses API 或 Chat Completions API）。

最小的使用方式：

from agents import Agent, ModelSettings english_agent = Agent( name="English agent", instructions="You only speak English", model="gpt-4.1", model_settings=ModelSettings(temperature=0.1), )

二、字段全景解析

ModelSettings的全部字段均以None为默认值，None表示"不设置、交给模型提供商默认行为"。下面按功能分组逐一说明，字段名、类型与语义均以 源码 和 模型指南 为准。

2.1 采样与生成控制

2.2 工具调用控制

2.3 上下文、存储与截断

2.4 提示词缓存（GPT-5.6 显式缓存）

配合显式缓存断点的用法：

from agents import Runner result = await Runner.run( research_agent, [ { "role": "user", "content": [ { "type": "input_text", "text": "Reusable background material...", "prompt_cache_breakpoint": {"mode": "explicit"}, }, { "type": "input_text", "text": "Analyze the latest question.", }, ], } ], )

官方提示：prompt_cache_retention面向使用传统保留控制的早期模型家族，不要把同一个请求字段同时通过ModelSettings直接字段与extra_args重复设置。

2.5 推理（Reasoning）与输出细节

2.6 请求级扩展

序列化测试 test_serialization.py 中的test_all_fields_serialization展示了一次设置全部 26 个字段的完整示例，可作为参数书写的权威参考。

2.7 超时与重试（2.8、2.9 详见下文专节）

三、超时：ModelSettings.timeout

模型指南 与 源码字段注释 对timeout的定义完全一致：

• 以秒为单位的正数，同时约束流式与非流式调用；
• 覆盖一次完整的模型调用尝试（含传输等待），通过常规 asyncio 取消机制协作式生效；
• 不约束整个 agent run、函数工具执行或重试退避时长。

from agents import Agent, ModelSettings agent = Agent( name="Assistant", model_settings=ModelSettings(timeout=30.0), )

超时后 SDK 会取消该次尝试并等待清理完成，然后抛出ModelTimeoutError（可参见 运行指南 中的异常说明）。若启用了 runner 托管重试，超时失败会以context.normalized.is_timeout=True交给重试策略判断，例如retry_policies.network_error()就能命中该分类；每次被允许的重试都会获得一个全新的按尝试计时的超时窗口。

四、Runner 托管重试：ModelSettings.retry

重试在 openai-agents-python 中是运行时、选择加入的机制：除非你在ModelSettings(retry=...)中配置ModelRetrySettings且策略决定重试，否则 SDK 不会重试一般模型请求。

ModelRetrySettings定义在 src/agents/retry.py，有三个字段：

一个完整的重试配置示例：

from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies agent = Agent( name="Assistant", model="gpt-5.6-sol", model_settings=ModelSettings( retry=ModelRetrySettings( max_retries=4, backoff={ "initial_delay": 0.5, "max_delay": 5.0, "multiplier": 2.0, "jitter": True, }, policy=retry_policies.any( retry_policies.provider_suggested(), retry_policies.retry_after(), retry_policies.network_error(), retry_policies.http_status([408, 409, 429, 500, 502, 503, 504]), ), ) ), )

4.1 重试策略上下文 RetryPolicyContext

策略回调接收一个RetryPolicyContext（见 src/agents/retry.py），包含：

• attempt与max_retries：支持基于尝试次数的决策；
• stream：区分流式与非流式分支；
• error：原始异常，供深度检查；
• normalized：归一化错误事实，如status_code、retry_after、error_code、is_network_error、is_timeout、is_abort；
• provider_advice：底层模型适配器给出的重试建议（如suggested、retry_after、reason）；
• response_started、replay_safety（取值"safe"/"unsafe"/"unknown"）、stateful_request（请求是否携带previous_response_id或conversation_id）：在策略运行前就已固化的重放安全事实。

策略可返回True/False做简单决策，也可返回RetryDecision以覆盖延迟、附加诊断 reason，或显式批准一次范围受限的不安全重放（approve_unsafe_replay=True）。普通RetryDecision(retry=True)永远不能绕过重放保护。

4.2 内置策略助手 retry_policies

SDK 在retry_policies上导出了即用型策略（实现在 src/agents/retry.py 的_RetryPolicies类中）：

组合策略时，provider_suggested()是最安全的第一构建块：它能保留提供商在可区分时给出的否决（veto）与重放安全批准。

4.3 安全边界

以下失败永不重试（模型指南）：

• 中止类错误（abort errors）；
• 流式运行中输出已经开始、重放已不安全的失败；
• 带独立本地副作用重放否决的请求（包括 Programmatic Tool Calling 请求），除非提供商已单独标记为重放安全。

提供商标记为不安全（"unsafe"）的失败默认也被阻止。对于非流式且无独立本地副作用否决的请求，应用可以通过RetryDecision(retry=True, approve_unsafe_replay=True)接受提供商侧的重放风险，但应先用context.response_started、context.replay_safety、context.stateful_request核实，且该批准不能授权流式重试或本地副作用。

使用previous_response_id/conversation_id的有状态后续请求在重放安全未知时失败关闭（fail closed）：仅靠network_error()或http_status([500])这类非提供商谓词不足以触发重试，需要提供商的重放安全批准（典型是retry_policies.provider_suggested()），或按上述方式显式批准提供商标记为非流式不安全的重放。

序列化测试 test_retry_policy_is_excluded_from_json_dict 验证了policy回调不会进入to_json_dict()，只会保留max_retries与backoff。

五、默认模型设置：GPT-5 与通用模型

src/agents/models/default_models.py 中get_default_model_settings(model)会根据模型名返回不同的默认ModelSettings：

• 对 GPT-5 系列模型（默认模型为gpt-5.6-luna，可用环境变量OPENAI_DEFAULT_MODEL覆盖），按型号前缀映射默认reasoning.effort（如gpt-5为"low"、gpt-5.6-sol为"none"、gpt-5.2-pro为"medium"等），并统一设置verbosity="low"；
• 对尚未确认 effort 取值范围的 GPT-5 变体，仅保留verbosity="low"而省略reasoning.effort；
• 对非 GPT-5 模型返回空的ModelSettings()，即全部交给提供商默认。

Agent在未显式传model_settings时会通过field(default_factory=get_default_model_settings)使用上述默认（见 src/agents/agent.py）。这也解释了 模型指南 中"用gpt-5.6-sol时 SDK 自动应用默认 ModelSettings，想调整推理强度就传入自己的ModelSettings(reasoning=Reasoning(effort="high"), verbosity="low")"的建议。需要说明：GPT-5 的reasoning.effort取值以模型文档为准，内置默认选择"none"/"low"等是基于成本敏感与高频 agent 工作流的取舍。

六、字典配置与严格校验

SDK 的配置边界普遍接受"类型化对象或同字段字典"两种写法（见 docs/config.md）：

from agents import Agent agent = Agent( name="Assistant", model="gpt-5.6-sol", model_settings={ "reasoning": {"effort": "high"}, "verbosity": "low", }, )

字典会被归一化为ModelSettings对象。归一化过程（_coerce_model_settings，见 src/agents/model_settings.py）具有严格校验：未知字段直接抛出TypeError，帮助你在早期发现拼写错误。测试 test_model_settings_dictionary_override_rejects_unknown_fields 验证了ModelSettings().resolve({"temperatur": 0.5})会报Unknown model settings: temperatur。此外_validate_first_party_model_settings还会对tool_choice、retry、retry.backoff、context_management、prompt_cache_options等 SDK 自有结构化设置做嵌套字段级拼写校验，同时保留 OpenAI 模型扩展的透传。

七、合并机制：resolve() 与 Runner/Agent 覆盖

ModelSettings.resolve(override)（见 src/agents/model_settings.py）用于把 override 中所有非None值叠加到当前实例之上，返回一个新对象。语义要点：

• 普通字段：override 非None即覆盖；None表示"不修改"，保持继承值；
• extra_args：字典合并而非整体替换——override 的键覆盖同名键，其余键保留（测试 test_extra_args_resolve 验证了三个键的合并结果）；
• retry：深度合并。max_retries可单独覆盖而继承 runner 的policy；backoff支持按字段合并（测试 test_retry_resolve_deep_merges_backoff 验证了initial_delay、max_delay继承自 base，multiplier、jitter来自 override）。

在运行期，src/agents/run.py 通过current_agent.model_settings.resolve(run_config.model_settings)合并 Agent 级与 Runner 级设置（例如读取合并后的store值来决定会话持久化行为）。因此 运行指南 建议：RunConfig.model_settings可覆盖 Agent 级设置，例如统一设置全局temperature或top_p。

八、底层请求映射：从 ModelSettings 到 API 调用

在 OpenAI Responses 路径上，src/agents/models/openai_responses.py 会把ModelSettings逐字段映射为请求参数：

• temperature、top_p、truncation、max_tokens（映射为max_output_tokens）、store、prompt_cache_retention、prompt_cache_options、reasoning直接映射（值为None时通过_non_null_or_omit转为省略，而非显式发送 null）；
• parallel_tool_calls、tool_choice映射到工具调用相关参数；
• response_include与top_logprobs会被合并进 include 集合；
• verbosity被写入response_format；
• extra_query、extra_body、extra_args透传到底层请求。

这也解释了为什么 Responses API 上parallel_tool_calls、truncation、store、context_management、prompt_cache_retention、prompt_cache_options、response_include、top_logprobs、retry等字段都有直接字段，不需要再通过extra_args传递。

九、序列化与可追踪性

ModelSettings提供两种序列化方法：

• to_json_dict()：完整序列化为 JSON 兼容字典（基于TypeAdapter(ModelSettings).dump_python(mode="json")），policy回调、嵌套 dataclass 等都会被正确处理；
• to_traceable_dict()：仅保留_TRACEABLE_MODEL_SETTING_FIELDS中列出的 19 个字段（temperature、top_p、reasoning、retry、context_management、prompt_cache_options、timeout等），剔除extra_headers、extra_query、extra_body、extra_args等可能携带密钥的请求级扩展，专用于 tracing 上报。

测试 test_traceable_serialization_omits_request_extras 明确验证：Authorization头、api-key、secret等不会出现在 traceable 输出中。Pydantic 往返（to_json/validate_json）在 test_pydantic_serialization 中也有覆盖，嵌套 dict 输入（如retry.backoff）会被自动强制转换为 dataclass。

十、最佳实践小结

1. 先查模型文档：不同模型/提供商对参数支持不同，ModelSettings只负责把字段传下去；
2. 用字典还是对象：简单场景可直接传字典并享受未知字段拼写校验；复杂场景（需要reasoning扩展字段或retry.policy回调）建议用类型化对象；
3. 善用resolve()层级覆盖：Agent 级放个性化参数，RunConfig.model_settings放全局默认，retry与extra_args是深度合并的例外；
4. 不要把同一字段同时写进直接字段和extra_args（如prompt_cache_retention、service_tier）；
5. 重试必须显式 opt-in，且组合策略以provider_suggested()打底以保留重放安全否决；
6. 关注store=False与include_usage的副作用：前者影响基于 response ID 的后续流程，后者是部分流式后端拿到 usage 指标的前提。

完整可运行的示例还可参考仓库中的 examples/basic/retry.py 与 examples/basic/retry_litellm.py，以及 docs/models/index.md 中的进阶配置章节。

【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python