From 636ca68cd84c026f6f9c1553e53fd92abcf6b59d Mon Sep 17 00:00:00 2001 From: Docs Bot Date: Thu, 18 Jun 2026 20:36:07 +0000 Subject: [PATCH 1/3] Fix JS deep agents profiles page showing Python code blocks Wrap all Python-specific content in :::python conditional blocks and add a :::js note explaining harness profiles are a Python-only feature of Deep Agents. --- src/oss/deepagents/profiles.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/oss/deepagents/profiles.mdx b/src/oss/deepagents/profiles.mdx index 08466c7ff3..f8a4d3b5b0 100644 --- a/src/oss/deepagents/profiles.mdx +++ b/src/oss/deepagents/profiles.mdx @@ -4,6 +4,13 @@ description: Package per-provider and per-model defaults that Deep Agents applie tag: "Beta" --- +:::js + + Harness profiles are currently a Python-only feature of Deep Agents. They are not yet available in the TypeScript SDK. To tune model behavior in TypeScript, pass `systemPrompt` or `middleware` directly to `createDeepAgent`. + +::: + +:::python **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 `create_deep_agent` call site. Use `HarnessProfile` when building profiles in Python; use `HarnessProfileConfig` when [loading or saving YAML/JSON files](#load-profiles-from-config-files). Deep Agents ships built-in harness profiles for OpenAI and Anthropic (Claude) models. **Provider profiles** are a narrower companion API for *model-construction* kwargs, which don't affect the harness. Most callers don't need them; reach for one when you want `init_chat_model` defaults, credential checks, or runtime-derived kwargs as defaults with your provider choice (for example, when packaging a provider integration). @@ -217,3 +224,4 @@ def register_provider() -> None: - [Harness](/oss/deepagents/harness) — overview of harness capabilities - [Models](/oss/deepagents/models) — configure model providers and parameters - [Customization](/oss/deepagents/customization) — full `create_deep_agent` configuration surface +::: From 9f3310b4c36e1f57c64716bc91b774ada98638b8 Mon Sep 17 00:00:00 2001 From: Docs Bot Date: Thu, 18 Jun 2026 22:34:06 +0000 Subject: [PATCH 2/3] Fix profiles page: add TS harness profile examples, clarify Python-only features Harness profiles ARE available in the TypeScript SDK via registerHarnessProfile. Previous commit incorrectly said they were Python-only. Changes: - Add :::js sections with TypeScript code examples (registerHarnessProfile, HarnessProfileOptions, parseHarnessProfileConfig, serializeProfile) - Add :::js ResponseField entries with camelCase TS field names - Wrap Python-specific content (HarnessProfile class, import forms, provider profiles, entry-point plugin system) in :::python blocks - Note in :::js that provider profiles and plugin registration are Python-only - Update shared prose (Notes, merge semantics table) to reference both Python/TS APIs --- src/oss/deepagents/profiles.mdx | 150 ++++++++++++++++++++++++++++---- 1 file changed, 135 insertions(+), 15 deletions(-) diff --git a/src/oss/deepagents/profiles.mdx b/src/oss/deepagents/profiles.mdx index f8a4d3b5b0..41aac3d5cc 100644 --- a/src/oss/deepagents/profiles.mdx +++ b/src/oss/deepagents/profiles.mdx @@ -4,19 +4,23 @@ description: Package per-provider and per-model defaults that Deep Agents applie tag: "Beta" --- -:::js - - Harness profiles are currently a Python-only feature of Deep Agents. They are not yet available in the TypeScript SDK. To tune model behavior in TypeScript, pass `systemPrompt` or `middleware` directly to `createDeepAgent`. - -::: - :::python **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 `create_deep_agent` call site. Use `HarnessProfile` when building profiles in Python; use `HarnessProfileConfig` when [loading or saving YAML/JSON files](#load-profiles-from-config-files). Deep Agents ships built-in harness profiles for OpenAI and Anthropic (Claude) models. **Provider profiles** are a narrower companion API for *model-construction* kwargs, which don't affect the harness. Most callers don't need them; reach for one when you want `init_chat_model` defaults, credential checks, or runtime-derived kwargs as defaults with your provider choice (for example, when packaging a provider integration). +::: + +:::js +**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](#load-profiles-from-config-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 +:::python A `HarnessProfile` describes prompt-assembly, tool-visibility, middleware, and default-subagent adjustments that `create_deep_agent` applies after the chat model has been constructed: ```python @@ -36,7 +40,24 @@ register_harness_profile( ), ) ``` +::: + +:::js +A harness profile describes prompt-assembly, tool-visibility, middleware, and default-subagent adjustments that `createDeepAgent` applies after the chat model has been constructed: + +```typescript +import { registerHarnessProfile } from "deepagents"; +registerHarnessProfile("openai:gpt-5.5", { + systemPromptSuffix: "Respond in under 100 words.", + excludedTools: ["execute"], + excludedMiddleware: ["SummarizationMiddleware"], + generalPurposeSubagent: { enabled: false }, +}); +``` +::: + +:::python Replace the base Deep Agents system prompt (`CUSTOM` in [Prompt assembly](/oss/deepagents/customization#prompt-assembly)). @@ -64,11 +85,43 @@ register_harness_profile( Disable, rename, or re-prompt the general-purpose subagent. When this field's `system_prompt` is set alongside `base_system_prompt`, the general-purpose-specific subagent prompt wins—see [General-purpose subagent prompt](/oss/deepagents/customization#general-purpose-subagent-prompt). +::: + +:::js + + Replace the base Deep Agents system prompt (`CUSTOM` in [Prompt assembly](/oss/deepagents/customization#prompt-assembly)). + + + + Append text to the assembled base prompt (`SUFFIX` in [Prompt assembly](/oss/deepagents/customization#prompt-assembly)); applied to the main agent, declarative subagents, and the auto-added general-purpose subagent. + + + + Override individual tool descriptions, keyed by tool name. + + + + 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. + + + + Strip specific middleware from the assembled stack. Matched against each middleware's `.name` property. Cannot include required scaffolding names (`FilesystemMiddleware`, `SubAgentMiddleware`). + + + + 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. + + + + Disable, rename, or re-prompt the general-purpose subagent (`enabled`, `description`, `systemPrompt`). + +::: - Caller-supplied `system_prompt=` always sits at the front of the assembled prompt, and `system_prompt_suffix` 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](/oss/deepagents/customization#prompt-assembly) for the full per-case breakdown (main agent, subagents, and the general-purpose subagent). + Caller-supplied `system_prompt=` (Python) / `systemPrompt` (TypeScript) always sits at the front of the assembled prompt, and `system_prompt_suffix` / `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](/oss/deepagents/customization#prompt-assembly) for the full per-case breakdown (main agent, subagents, and the general-purpose subagent). +:::python To run an agent without the `task` tool, see [Running without subagents](/oss/deepagents/subagents#running-without-subagents) — set `general_purpose_subagent=GeneralPurposeSubagentProfile(enabled=False)` and pass no synchronous subagents via `subagents=`. `SubAgentMiddleware` (and the `task` tool) is only attached when at least one synchronous subagent exists, so this configuration leaves it out cleanly. Async subagents are unaffected. @@ -79,6 +132,13 @@ Entries in `excluded_middleware` accept two forms: - A middleware *class* (matched by exact type), or a plain string that matches `AgentMiddleware.name`. Use plain strings for built-ins and public aliases such as `"SummarizationMiddleware"`. - An `module:Class` import ref (for example, `"my_pkg.middleware:TelemetryMiddleware"`) to target an exact middleware class from a config file. Import refs resolve lazily, so use them only for trusted local configuration — loading one imports Python code. +::: + +:::js + + 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. + +::: - 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 `create_deep_agent` call site. + 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 `create_deep_agent` (Python) / `createDeepAgent` (TypeScript) call site. ## Merge semantics | Field | Merge behavior | | --- | --- | -| `base_system_prompt`, `system_prompt_suffix` | New value wins when set; otherwise inherits | -| `tool_description_overrides` | Mappings merge per key; new value wins on a shared key | -| `excluded_tools`, `excluded_middleware` | Set union | -| `extra_middleware` | Merged by concrete class: new instance replaces existing at its position, novel classes append | -| `general_purpose_subagent` | Merged field-wise (unset fields inherit) | +| `base_system_prompt` / `baseSystemPrompt`, `system_prompt_suffix` / `systemPromptSuffix` | New value wins when set; otherwise inherits | +| `tool_description_overrides` / `toolDescriptionOverrides` | Mappings merge per key; new value wins on a shared key | +| `excluded_tools` / `excludedTools`, `excluded_middleware` / `excludedMiddleware` | Set union | +| `extra_middleware` / `extraMiddleware` | Merged by name: new instance replaces existing at its position, novel entries append | +| `general_purpose_subagent` / `generalPurposeSubagent` | Merged field-wise (unset fields inherit) | + +:::python | `init_kwargs` (provider) | Dicts merge key-wise; new value wins on a shared key | | `pre_init` (provider) | Callables chain: existing runs first, then the new one | | `init_kwargs_factory` (provider) | Factories chain with their outputs merged every `resolve_model` call | +::: ## Provider profiles +:::python A `ProviderProfile` declares how Deep Agents should construct a chat model for a given provider or specific model spec. It applies only when you provide a `provider:model` string when creating the deep agent, not when you pass a preconfigured model with @[`init_chat_model`]: ```python @@ -143,13 +207,25 @@ register_provider_profile( Kwargs derived from runtime state (for example, headers pulled from environment variables). +::: + +:::js +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 +:::python For YAML/JSON-backed workflows, use `HarnessProfileConfig`. It mirrors the declarative subset of `HarnessProfile` (prompt text, tool-description overrides, excluded tools and middleware, general-purpose subagent edits) and owns `to_dict` / `from_dict`. Runtime-only state — middleware instances, factories, and class-form `excluded_middleware` entries — stays on `HarnessProfile`. `register_harness_profile` accepts either type, so config-backed callers don't need a manual conversion step: +::: + +:::js +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. +::: +:::python ```yaml # openai.yaml base_system_prompt: You are helpful. @@ -163,7 +239,24 @@ excluded_middleware: general_purpose_subagent: enabled: false ``` +::: +:::js +```yaml +# profile.yaml +baseSystemPrompt: You are helpful. +systemPromptSuffix: Respond briefly. +excludedTools: + - execute + - grep +excludedMiddleware: + - SummarizationMiddleware +generalPurposeSubagent: + enabled: false +``` +::: + +:::python ```python import yaml from deepagents import HarnessProfileConfig, register_harness_profile @@ -179,9 +272,32 @@ To go the other direction, `HarnessProfileConfig.from_harness_profile(...)` expo - Class-form `excluded_middleware` entries serialize as a public alias (when the class exposes one via `serialized_name: ClassVar[str]`) or as a `module:Class` import ref. - Non-empty `extra_middleware` and middleware classes declared in `__main__` or inside a function scope cannot be serialized — export raises `ValueError`. +::: + +:::js +```typescript +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`: + +```typescript +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 +:::python Distributable profiles can register themselves via `importlib.metadata` entry points instead of requiring callers to run `register_*_profile` by hand. Load order is **built-ins first, then entry-point plugins, then any direct `register_*_profile` calls in user code**; all three paths funnel through the same additive registration, so later registrations layer on top of earlier ones under the same key. Declare an entry point in the distribution's own `pyproject.toml` under the appropriate group: @@ -218,10 +334,14 @@ def register_provider() -> None: ProviderProfile(init_kwargs={"temperature": 0}), ) ``` +::: + +:::js +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. +::: ## Related - [Harness](/oss/deepagents/harness) — overview of harness capabilities - [Models](/oss/deepagents/models) — configure model providers and parameters -- [Customization](/oss/deepagents/customization) — full `create_deep_agent` configuration surface -::: +- [Customization](/oss/deepagents/customization) — full `create_deep_agent` / `createDeepAgent` configuration surface From e6f46c2014d90eac5cae7622b7e6264c2d44edc3 Mon Sep 17 00:00:00 2001 From: Docs Bot Date: Thu, 18 Jun 2026 22:38:41 +0000 Subject: [PATCH 3/3] Split combined Python/TS prose into :::python/:::js code fences - Split Note about system_prompt=/systemPrompt into separate :::python/:::js blocks - Split Note about create_deep_agent/createDeepAgent into separate :::python/:::js blocks - Split merge semantics table into separate :::python/:::js tables with language-specific field names - Split Related customization link into separate :::python/:::js entries --- src/oss/deepagents/profiles.mdx | 50 +++++++++++++++++++++++++++------ 1 file changed, 42 insertions(+), 8 deletions(-) diff --git a/src/oss/deepagents/profiles.mdx b/src/oss/deepagents/profiles.mdx index 41aac3d5cc..5e4e894f87 100644 --- a/src/oss/deepagents/profiles.mdx +++ b/src/oss/deepagents/profiles.mdx @@ -117,9 +117,17 @@ registerHarnessProfile("openai:gpt-5.5", { ::: +:::python - Caller-supplied `system_prompt=` (Python) / `systemPrompt` (TypeScript) always sits at the front of the assembled prompt, and `system_prompt_suffix` / `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](/oss/deepagents/customization#prompt-assembly) for the full per-case breakdown (main agent, subagents, and the general-purpose subagent). + Caller-supplied `system_prompt=` always sits at the front of the assembled prompt, and `system_prompt_suffix` 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](/oss/deepagents/customization#prompt-assembly) for the full per-case breakdown (main agent, subagents, and the general-purpose subagent). +::: + +:::js + + 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](/oss/deepagents/customization#prompt-assembly) for the full per-case breakdown (main agent, subagents, and the general-purpose subagent). + +::: :::python @@ -162,19 +170,39 @@ When both a provider-level and a model-level profile exist, they are merged at r Re-registering under an existing key merges the new profile on top of the prior one—it does not replace it. See [Merge semantics](#merge-semantics) for the per-field rules. +:::python + + 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 `create_deep_agent` call site. + +::: + +:::js - 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 `create_deep_agent` (Python) / `createDeepAgent` (TypeScript) call site. + 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 +:::python | Field | Merge behavior | | --- | --- | -| `base_system_prompt` / `baseSystemPrompt`, `system_prompt_suffix` / `systemPromptSuffix` | New value wins when set; otherwise inherits | -| `tool_description_overrides` / `toolDescriptionOverrides` | Mappings merge per key; new value wins on a shared key | -| `excluded_tools` / `excludedTools`, `excluded_middleware` / `excludedMiddleware` | Set union | -| `extra_middleware` / `extraMiddleware` | Merged by name: new instance replaces existing at its position, novel entries append | -| `general_purpose_subagent` / `generalPurposeSubagent` | Merged field-wise (unset fields inherit) | +| `base_system_prompt`, `system_prompt_suffix` | New value wins when set; otherwise inherits | +| `tool_description_overrides` | Mappings merge per key; new value wins on a shared key | +| `excluded_tools`, `excluded_middleware` | Set union | +| `extra_middleware` | Merged by name: new instance replaces existing at its position, novel entries append | +| `general_purpose_subagent` | Merged field-wise (unset fields inherit) | +::: + +:::js +| Field | Merge behavior | +| --- | --- | +| `baseSystemPrompt`, `systemPromptSuffix` | New value wins when set; otherwise inherits | +| `toolDescriptionOverrides` | Mappings merge per key; new value wins on a shared key | +| `excludedTools`, `excludedMiddleware` | Set union | +| `extraMiddleware` | Merged by name: new instance replaces existing at its position, novel entries append | +| `generalPurposeSubagent` | Merged field-wise (unset fields inherit) | +::: :::python | `init_kwargs` (provider) | Dicts merge key-wise; new value wins on a shared key | @@ -344,4 +372,10 @@ The plugin registration system (via package entry points) is a Python-only featu - [Harness](/oss/deepagents/harness) — overview of harness capabilities - [Models](/oss/deepagents/models) — configure model providers and parameters -- [Customization](/oss/deepagents/customization) — full `create_deep_agent` / `createDeepAgent` configuration surface +:::python +- [Customization](/oss/deepagents/customization) — full `create_deep_agent` configuration surface +::: + +:::js +- [Customization](/oss/deepagents/customization) — full `createDeepAgent` configuration surface +:::