profiles

Accepts either a runtime HarnessProfile or a declarative HarnessProfileConfig. Config objects are converted to runtime profiles at registration time so YAML/JSON-backed callers do not need a separate manual conversion step.

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. Excluded-tool sets union, middleware sequences merge by type, and general_purpose_subagent settings merge field-wise.

To extend an existing registration, call register_harness_profile again under the same key:

from deepagents import HarnessProfile, register_harness_profile

# Layer a system-prompt suffix on top of the previous registration.
register_harness_profile(
    "openai:gpt-5.4",
    HarnessProfile(system_prompt_suffix="Respond in under 100 words."),
)

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}),
)

These settings only affect the default subagent that create_deep_agent inserts when the caller does not explicitly provide a subagent named general-purpose.

A HarnessProfile describes prompt-assembly, tool visibility, middleware, and default-subagent adjustments applied by create_deep_agent once a chat model has been constructed. Profiles are registered via register_harness_profile under a provider key ("openai") or a full provider:model key ("openai:gpt-5.4").

This complements ProviderProfile, which controls the model-construction phase (e.g. init_chat_model kwargs, pre-init side effects). Concerns that shape how the model is built belong in ProviderProfile; concerns that shape how the agent runs belong here.

For YAML/JSON-backed profiles, use HarnessProfileConfig, which contains only the declarative subset and can be passed directly to register_harness_profile.

The extra_middleware field expects langchain.agents.middleware.types.AgentMiddleware instances or a factory returning a sequence of them.

A HarnessProfileConfig contains the file-friendly subset of harness settings: plain strings, bools, lists, and nested dicts that can be loaded from YAML or JSON. For in-code/runtime-only adjustments such as extra_middleware or class-form excluded_middleware, use HarnessProfile instead.

Config objects may be passed directly to register_harness_profile; the helper converts them to runtime HarnessProfile objects automatically.

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.