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. This keeps the helper safe to call unconditionally.

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).

Malformed specs (empty string, more than one :, or a : with an empty provider/model half) return None without consulting the registry. This prevents a spec like "openai:" from silently matching the provider-wide "openai" registration.

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.

Registrations are additive: if a profile is already registered under key (including a built-in profile loaded during lazy bootstrap), the new profile is merged on top rather than replacing it. The incoming profile's fields win on conflicts; unspecified fields inherit from the existing profile. pre_init callables chain (existing runs first), and init_kwargs_factory callables chain — both factories are invoked at every resolution (base first, then override) and their outputs merge with the override's values winning on shared keys.

To layer additional kwargs onto a built-in profile, register under the same provider key. To override a built-in default (e.g. disable the OpenAI Responses API), set the conflicting key explicitly:

from deepagents import ProviderProfile, register_provider_profile

# Adds temperature alongside the built-in `use_responses_api=True`.
register_provider_profile("openai", ProviderProfile(init_kwargs={"temperature": 0}))

# Explicitly disables Responses API for OpenAI. (This will break usage,
# this example is purely illustrative.)
register_provider_profile(
    "openai",
    ProviderProfile(init_kwargs={"use_responses_api": False}),
)