ModelSettings is a Pydantic dataclass in the SDK holding all optional LLM call parameters—temperature, tool choice, timeouts, retry policies, and provider-specific options like prompt caching—though not all models or providers support every field. A subset of these settings (including temperature, timeouts, retry policies, and caching options) are traced via _TRACEABLE_MODEL_SETTING_FIELDS, while resolve() lets you overlay runtime overrides on base settings and merge nested retry and extra_args policies.
ModelSettings in src/agents/model_settings.py is a Pydantic dataclass holding all optional LLM call parameters; not all models or providers support every field.[1] The _TRACEABLE_MODEL_SETTING_FIELDS tuple in src/agents/model_settings.py lists the subset of ModelSettings fields recorded in traces, including temperature, top_p, frequency_penalty, presence_penalty, tool_choice, parallel_tool_calls, truncation, max_tokens, reasoning, verbosity, metadata, store, prompt_cache_retention, include_usage, response_include, top_logprobs, retry, context_management, prompt_cache_options, and timeout.[1]
ModelSettings.parallel_tool_calls defaults to None, deferring to the provider default (typically enabled for most OpenAI models). Set to False to restrict the model to at most one tool call per turn.[1] ModelSettings.store defaults to None; for the Responses API it is automatically enabled when unset, while for the Chat Completions API it is enabled for OpenAI and omitted for other providers so their own default applies.[1] ModelSettings.preserve_raw_usage enables capturing a JSON-compatible snapshot of the raw provider usage payload before SDK normalization, stored as ModelResponse.raw_usage. This setting does not request usage from the provider; use include_usage separately when a streaming provider requires it.[1] ModelSettings.timeout is enforced via asyncio cancellation and bounds the complete model attempt (including transport waits), but does not cover the full run, tool calls, or retry backoff periods.[1] ModelSettings.context_management accepts a list of ContextManagement entries for OpenAI Responses API requests; for example, [{"type": "compaction", "compact_threshold": 200000}] enables server-side compaction when the context token count crosses the threshold.[1] ModelSettings.prompt_cache_options configures OpenAI prompt caching; use {"mode": "explicit", "ttl": "30m"} with content-part cache breakpoints to control which prompt prefixes are eligible for caching.[1] ModelSettings.top_logprobs automatically adds "message.output_text.logprobs" to the response include list when set.[1] ModelSettings.extra_args passes arbitrary keyword arguments directly to the underlying model provider's API call; not all models support all parameters.[1]
ToolChoice in src/agents/model_settings.py is a type alias supporting "auto", "required", "none", an arbitrary string, an MCPToolChoice dataclass, or None.[1] MCPToolChoice in src/agents/model_settings.py is a plain dataclass with server_label and name fields used to target a specific MCP tool by server identity and tool name.[1]
The Omit type in src/agents/model_settings.py wraps OpenAI's _Omit sentinel and is Pydantic-validated: None is coerced to _Omit() in both JSON and Python modes, and it serializes back to None.[1]
ModelSettings.resolve() produces a new ModelSettings by overlaying non-None values from an override — which may be a ModelSettings instance or a plain dict — on top of the current instance.[1] When both the base and override have extra_args, ModelSettings.resolve() merges those dictionaries rather than replacing them, combining keys from both sides.[1] When both the base and override contain retry, ModelSettings.resolve() merges the two ModelRetrySettings objects field-by-field rather than replacing wholesale, preserving base retry policy components under a partial override.
Compose retry policies using retry_policies.any() to combine provider-suggested, retry-after, network-error, and HTTP-status policies
apply_policies = 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]),
)
Configure ModelRetrySettings with composite retry policies (provider-suggested, retry-after, network error, HTTP status) and attach them via RunConfig and Agent.model_settings
retry = ModelRetrySettings(
max_retries=4,
backoff={
"initial_delay": 0.5,
"max_delay": 5.0,
"multiplier": 2.0,
"jitter": True,
},
policy=policy,
)
run_config = RunConfig(model_settings=ModelSettings(retry=retry))
agent = Agent(
name="Assistant",
instructions="You are a concise assistant. Answer in 3 short bullet points at most.",
model_settings=ModelSettings(retry=retry),
)
result = await Runner.run(
agent,
"Explain exponential backoff for API retries in plain English.",
run_config=run_config,
)
Sources