Skip to main content
Harness profiles let you package configuration that Deep Agents applies whenever a given provider or specific model is selected: system-prompt tweaks, tool description overrides, excluded tools or middleware, extra middleware, and general-purpose subagent edits. They are the main way to tune how the harness behaves for a particular model without changing your createDeepAgent call site. Use HarnessProfileOptions to build profiles; use parseHarnessProfileConfig when loading or saving YAML/JSON files. Deep Agents ships built-in harness profiles for OpenAI and Anthropic (Claude) models.
Provider profiles (for controlling model-construction kwargs) and the plugin registration system are Python-only features. The TypeScript SDK supports harness profiles only.

​
Harness profiles

A harness profile describes prompt-assembly, tool-visibility, middleware, and default-subagent adjustments that createDeepAgent applies after the chat model has been constructed: 
import { registerHarnessProfile } from "deepagents";

registerHarnessProfile("openai:gpt-5.5", {
  systemPromptSuffix: "Respond in under 100 words.",
  excludedTools: ["execute"],
  excludedMiddleware: ["SummarizationMiddleware"],
  generalPurposeSubagent: { enabled: false },
});
​
baseSystemPrompt
string
Replace the base Deep Agents system prompt (CUSTOM in Prompt assembly).
​
systemPromptSuffix
string
Append text to the assembled base prompt (SUFFIX in Prompt assembly); applied to the main agent, declarative subagents, and the auto-added general-purpose subagent.
​
toolDescriptionOverrides
Record<string, string>
Override individual tool descriptions, keyed by tool name.
​
excludedTools
string[]
Remove specific harness-level tools from the tool set. Matched by tool name, applied as a post-injection filter so it catches both user-provided and middleware-provided tools.
​
excludedMiddleware
string[]
Strip specific middleware from the assembled stack. Matched against each middleware’s .name property. Cannot include required scaffolding names (FilesystemMiddleware, SubAgentMiddleware).
​
extraMiddleware
AgentMiddleware[] | (() => AgentMiddleware[])
Additional middleware appended to the stack after user middleware. Can be a static array or a zero-arg factory that returns fresh instances per agent construction.
​
generalPurposeSubagent
GeneralPurposeSubagentConfig
Disable, rename, or re-prompt the general-purpose subagent (enabled, description, systemPrompt).
Caller-supplied systemPrompt always sits at the front of the assembled prompt, and systemPromptSuffix always sits at the end—regardless of which model is selected. The same overlay rules apply to subagents: each subagent re-runs profile resolution against its own model. See Prompt assembly for the full per-case breakdown (main agent, subagents, and the general-purpose subagent).
Listing FilesystemMiddleware or SubAgentMiddleware in excludedMiddleware throws at construction time — they are required scaffolding. To hide their tools from the model without removing the middleware, use excludedTools instead.
When you pass a preconfigured chat model instance instead of a provider:model string, the harness synthesizes the canonical provider:identifier key from the instance and looks it up in this order:
  1. Exact provider:identifier match
  2. Identifier-only (only when the identifier already contains :)
  3. Provider-only fallback

​
Registration keys

Both profile types use the same key format:
  • Provider-level — a bare provider name like "openai" applies to every model from that provider.
  • Model-level — a fully qualified provider:model key like "openai:gpt-5.5" applies only to that specific model.
When both a provider-level and a model-level profile exist, they are merged at resolution time. Unset model-level fields inherit from the provider-level profile; explicit model-level values override them. Re-registering under an existing key merges the new profile on top of the prior one—it does not replace it. See Merge semantics for the per-field rules.
There is no wildcard key that matches every provider. To apply the same overrides everywhere—say, dropping TodoListMiddleware regardless of which model is selected—register the profile under each provider key you use. Profiles are intended for adjustments that depend on the model being selected. Global adjustments that should apply regardless of model should be made on the createDeepAgent call site.

​
Merge semantics

FieldMerge behavior
baseSystemPrompt, systemPromptSuffixNew value wins when set; otherwise inherits
toolDescriptionOverridesMappings merge per key; new value wins on a shared key
excludedTools, excludedMiddlewareSet union
extraMiddlewareMerged by name: new instance replaces existing at its position, novel entries append
generalPurposeSubagentMerged field-wise (unset fields inherit)

​
Provider profiles

Provider profiles (for controlling model-construction kwargs like temperature) are a Python-only feature and are not available in the TypeScript SDK.

​
Load profiles from config files

For YAML/JSON-backed workflows, use parseHarnessProfileConfig. It validates and builds a HarnessProfile from a plain object with camelCase keys. Runtime-only state — extraMiddleware instances — cannot be represented in JSON/YAML and must be set programmatically. 
# profile.yaml
baseSystemPrompt: You are helpful.
systemPromptSuffix: Respond briefly.
excludedTools:
  - execute
  - grep
excludedMiddleware:
  - SummarizationMiddleware
generalPurposeSubagent:
  enabled: false

import { readFileSync } from "fs";
import YAML from "yaml";
import { parseHarnessProfileConfig, registerHarnessProfile } from "deepagents";

const raw = YAML.parse(readFileSync("profile.yaml", "utf-8"));
registerHarnessProfile("openai", parseHarnessProfileConfig(raw));
To serialize a profile back to JSON/YAML, use serializeProfile: 
import { serializeProfile } from "deepagents";

const data = serializeProfile(profile); // JSON-compatible object
Profiles with non-empty extraMiddleware cannot be serialized — serializeProfile throws if middleware instances are present.

​
Ship a profile as a plugin

The plugin registration system (via package entry points) is a Python-only feature. In TypeScript, call registerHarnessProfile directly at application startup or in your package’s initialization code.
  • Harness — overview of harness capabilities
  • Models — configure model providers and parameters
  • Customization — full createDeepAgent configuration surface
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.