harness

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.

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.

Harness profiles declare how create_deep_agent should shape the agent's runtime behavior for a given provider or specific model spec. They tune prompt assembly, tool visibility, middleware, and default subagent behavior after the chat model has been constructed — orthogonal to ProviderProfile, which controls the model-construction phase.

Users may register profiles via register_harness_profile. Deep Agents ships built-in harness profiles for several frontier model specs. They may be layered on top of via additive merge semantics.