provider

Compose init_chat_model kwargs from the registered profile for spec.

This is the recommended entry point for honoring ProviderProfile registrations when building a chat model — it composes lookup, pre_init invocation, and kwargs merging into a single call. get_provider_profile only returns the registered object; pair it with this helper (or call this helper directly) any time you intend to actually instantiate a model. Used by resolve_model and intended for any harness that layers config-file values on top of SDK defaults.

Looks up the profile via get_provider_profile, runs its pre_init hook (unless suppressed), and returns a fresh dict combining init_kwargs, init_kwargs_factory() output, and kwargs. Caller-supplied kwargs take highest precedence — profile defaults sit beneath them — so user-provided values from config files or explicit overrides are never silently replaced.

When no profile is registered for spec, returns a copy of kwargs unchanged and logs the miss at DEBUG.

Look up the ProviderProfile for a model spec.

Resolution order:

1. Exact match on spec.
2. Provider prefix (everything before the first :), when spec contains a colon and both halves are non-empty.
3. None when neither matches.

When both an exact-model profile and a provider-level profile exist, they are merged via _merge_provider_profiles with the exact-model entry overriding the provider-level entry on conflicts.

When only the provider-level profile matches, a debug breadcrumb is emitted so registrations layered on an exact key can be traced when they don't apply (e.g. typo'd specs falling through to the provider default).

Declarative configuration for constructing a chat model.

A ProviderProfile describes provider- or model-specific kwargs, pre-initialization side effects, and runtime-derived kwargs that should be applied when resolve_model turns a string spec (e.g. "openai:gpt-5.4") into a BaseChatModel. Profiles are registered via register_provider_profile under a provider key ("openai") or a full provider:model key ("openai:gpt-5.4").

Profiles handle model-construction concerns only — things that shape how init_chat_model assembles the client instance. Typical examples: constructor kwargs like use_responses_api, temperature, max_tokens, or base_url; provider-specific headers such as OpenRouter app attribution; pre-construction checks like minimum-version enforcement; and env-var-aware defaults.

Runtime and harness behavior — system-prompt assembly, tool description overrides, excluded tools, extra middleware, general-purpose subagent configuration — belongs in HarnessProfile, the separate harness profile system consumed by create_deep_agent, not here.

Beta APIs for configuring model-construction behavior.

Provider profiles declare how Deep Agents should construct a chat model for a given provider or specific model spec. The registry is consumed by resolve_model and is the extension point for controlling init_chat_model kwargs, running pre-initialization side effects, and deriving kwargs from runtime state (e.g. environment variables).

Register a ProviderProfile for a provider or specific model.

Register under a provider name to set defaults for its models, or under provider:model to customize one model. Model-specific settings override conflicting provider defaults and inherit the remaining settings.

For example, set defaults for a hypothetical provider, then lower the temperature for one model:

from deepagents import ProviderProfile, register_provider_profile

register_provider_profile(
    "my_provider",
    ProviderProfile(init_kwargs={"temperature": 0.7, "timeout": 30}),
)
register_provider_profile(
    "my_provider:my-model:tag",
    ProviderProfile(init_kwargs={"temperature": 0}),
)

When Deep Agents constructs my_provider:my-model:tag, the profile supplies temperature=0 and timeout=30. Other models from my_provider receive temperature=0.7 and timeout=30. The model identifier is my-model:tag; only the first colon separates it from the provider.

Register profiles before constructing the agent. Passing a model instance to create_deep_agent leaves its construction settings unchanged; see register_harness_profile for examples of both forms.

Re-registering merges with the existing profile: new values override conflicts and unspecified fields remain. Continuing the example, give this model a longer timeout:

register_provider_profile(
    "my_provider:my-model:tag",
    ProviderProfile(init_kwargs={"timeout": 60}),
)

Future construction of this model uses temperature=0 and timeout=60; other models still use the provider's defaults.

Deep Agents also ships built-in profiles: model-construction defaults registered automatically for selected providers. Registering under one of those keys customizes the shipped settings using the same merge rules.

pre_init callables run existing first, then new. Both init_kwargs_factory callables run in that order too, with the new factory's output winning on shared keys.

See the Profiles guide for registration workflows and configuration files.