HarnessProfile

Per-tool description replacements keyed by tool name.

Applied only where Deep Agents has a stable description hook: built-in filesystem tools, the task tool, and user-supplied BaseTool or dict tools. Plain callable tools are left unchanged.

Once a profile is constructed, its overrides can be read but not rewritten — for example, profile.tool_description_overrides["ls"] = "new" raises TypeError. The registry stores its own defensive copy, so mutating the dict you passed into the constructor after the fact won't affect the registered profile either. To change a registered profile's overrides, re-register (which merges on top) or construct a new profile.

Tool names to remove from the tool set for this profile.

Applied via a tool-exclusion middleware after tool-injecting middleware has run, so it can remove both user-supplied tools and tools added by Deep Agents middleware from the visible tool set.

When profiles are merged, exclusions are additive rather than replacing each other. For example, if a provider profile excludes execute and an exact-model profile excludes grep, the resolved profile excludes both tools.

Exclusions are model-facing calibration resolved per model; they are not a security surface.

Middleware to strip from every stack this profile applies to.

Entries may be a middleware class (matched by exact type, not subclass — consistent with extra_middleware slot merging) or a string matching AgentMiddleware.name exactly. .name defaults to the class's __name__ but is overridable, so {FilesystemMiddleware} (class form) and {"FilesystemMiddleware"} (name form) behave identically for stock middleware.

Prefer class form when the class is importable: typos surface at import time rather than at agent construction. Reserve string form for YAML/JSON-loaded profiles and for middleware whose class isn't part of the public import surface (e.g. "SummarizationMiddleware" drops the private _DeepAgentsSummarizationMiddleware via its public alias).

The filter runs over the fully assembled stack, so exclusions remove middleware regardless of which layer added it — including instances passed via create_deep_agent(middleware=[...]). Merged profiles union their exclusion sets; mixed class/string sets are allowed. For config-file usage, HarnessProfileConfig stores the same exclusions using string names only.

Middleware appended to every runtime middleware stack.

Applied to the main agent, the auto-added general-purpose subagent, and declarative synchronous subagents created from SubAgent specs — i.e., the stacks that create_deep_agent assembles itself.

Appended after the SDK defaults and any caller-supplied middleware, and before profile tool exclusions, prompt caching, memory, and human-in-the-loop middleware. This lets profiles tune the final request surface after extra middleware has added any tools or prompt behavior.

Not applied to CompiledSubAgent runnables or AsyncSubAgent entries. A CompiledSubAgent is passed in pre-built (its runnable is already a compiled graph with its own middleware chain), so create_deep_agent has nothing to append to. An AsyncSubAgent runs out-of-process against a remote deployment and its middleware is configured on that remote graph, not here. In both cases, injecting local middleware would either fail silently or violate the caller's explicit configuration.

May be a static sequence or a zero-arg factory that returns one. Use a factory when middleware instances should not be shared across stacks. This field is runtime-only and intentionally absent from HarnessProfileConfig.

Edits for the auto-added general-purpose subagent.

Unset (default None) is equivalent to passing GeneralPurposeSubagentProfile() — the auto-added subagent runs with its stock description and prompt. Set enabled=False on a populated sub-profile to remove the default general-purpose subagent entirely. Pair that with no synchronous subagents via subagents= on create_deep_agent and the task tool is dropped too. Async subagents are unaffected.

Return a fresh list of extra_middleware, invoking factory if supplied.

Each call returns a new list so consumers may mutate freely.