profiles

Accepts a runtime HarnessProfile or converts a declarative HarnessProfileConfig at registration time.

Register under a provider name to set defaults for its models, or under provider:model to customize one model. Model-specific settings inherit provider defaults, with explicit fields replacing or extending them.

For example, exclude a tool for a hypothetical provider's models, then customize the response length for one model:

from deepagents import HarnessProfile, register_harness_profile

register_harness_profile(
    "my_provider",
    HarnessProfile(
        excluded_tools=frozenset({"execute"}),
        system_prompt_suffix="Respond in under 500 words.",
    ),
)
register_harness_profile(
    "my_provider:my-model:tag",
    HarnessProfile(system_prompt_suffix="Respond in under 100 words."),
)

An agent using my_provider:my-model:tag excludes execute and receives the 100-word prompt suffix. Other models from my_provider exclude execute and receive the 500-word suffix.

Register profiles before calling create_deep_agent. Using the hypothetical provider above, you can pass a model string or construct the model yourself:

from langchain.chat_models import init_chat_model

from deepagents import create_deep_agent

# Deep Agents constructs the model from a string.
agent = create_deep_agent(model="my_provider:my-model:tag")

# Or construct a model object first, then pass it to Deep Agents.
model = init_chat_model("my-model:tag", model_provider="my_provider")
agent = create_deep_agent(model=model)

For the model object, Deep Agents looks up the harness profile using the provider and model identifier reported by that object. If it reports my_provider and my-model:tag, it matches the same registration above.

Re-registering merges with the existing profile: new values override conflicts and unspecified fields remain. Continuing the example, exclude one more tool:

register_harness_profile(
    "my_provider:my-model:tag",
    HarnessProfile(excluded_tools=frozenset({"grep"})),
)

An agent created afterward with this model excludes both execute and grep and still receives the 100-word prompt suffix.

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

Excluded-tool sets union, middleware sequences merge by type, and general_purpose_subagent settings merge field-wise.

See the Profiles guide for registration workflows and configuration files.

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.

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.