Beta APIs for configuring deep agent runtime behavior.
deepagents.profiles exposes beta APIs that may receive minor changes in
future releases. Refer to the versioning documentation
for more details.
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.
Validate a profile registry key.
Enforces the provider or provider:model shape used by the lookup
functions. Rejects empty strings, whitespace-only or whitespace-padded
halves, multiple colons, and empty halves.
Edits applied to the auto-added general-purpose subagent.
deepagents.profiles exposes beta APIs that may receive minor changes in
future releases. Refer to the versioning documentation
for more details.
These settings only affect the default subagent that create_deep_agent
inserts when the caller does not explicitly provide a subagent named
general-purpose.
Declarative harness-profile config for YAML/JSON-backed profiles.
deepagents.profiles exposes beta APIs that may receive minor changes in
future releases. Refer to the versioning documentation
for more details.
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.
excluded_middleware in config files currently only accepts plain
middleware-name strings matched against AgentMiddleware.name. A
future revision may add explicit class-path (module:Class) entries
for excluding middleware whose class isn't part of the public import
surface; until then, exclude such middleware via its .name (using
serialized_name for stable public aliases) or stay on the runtime
HarnessProfile and pass the class directly.
Config objects may be passed directly to register_harness_profile; the
helper converts them to runtime HarnessProfile objects automatically.
Runtime configuration for deep agent behavior.
deepagents.profiles exposes beta APIs that may receive minor changes in
future releases. Refer to the versioning documentation
for more details.
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.
Register a harness profile for a provider or specific model.
deepagents.profiles exposes beta APIs that may receive minor changes in
future releases. Refer to the versioning documentation
for more details.
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."),
)