From 92628fb39420486b9853301330cad69a02ec4368 Mon Sep 17 00:00:00 2001 From: Nishitha M <32355027+imnishitha@users.noreply.github.com> Date: Thu, 23 Jul 2026 18:01:32 +0000 Subject: [PATCH 1/8] docs: revert SystemPromptConfig docs for deepagents PR revert Co-authored-by: open-swe[bot] --- pipeline/preprocessors/link_map.py | 1 - .../deepagents/customization-overview.py | 6 +- src/oss/deepagents/customization.mdx | 57 ++++++++++++------- src/oss/deepagents/profiles.mdx | 4 +- src/oss/deepagents/subagents.mdx | 2 +- src/oss/python/releases/changelog.mdx | 1 - .../customization-prompt-assembly-py.mdx | 42 +++++++------- 7 files changed, 65 insertions(+), 48 deletions(-) diff --git a/pipeline/preprocessors/link_map.py b/pipeline/preprocessors/link_map.py index 0e44a4ba69..a984e8054f 100644 --- a/pipeline/preprocessors/link_map.py +++ b/pipeline/preprocessors/link_map.py @@ -35,7 +35,6 @@ class LinkMap(TypedDict): # Deep Agents "create_deep_agent": "deepagents/graph/create_deep_agent", "DeepAgentState": "deepagents/graph/DeepAgentState", - "SystemPromptConfig": "deepagents/graph/SystemPromptConfig", "SubAgent": "deepagents/middleware/subagents/SubAgent", "CompiledSubAgent": "deepagents/middleware/subagents/CompiledSubAgent", "SubAgentMiddleware": "deepagents/middleware/subagents/SubAgentMiddleware", diff --git a/src/code-samples/deepagents/customization-overview.py b/src/code-samples/deepagents/customization-overview.py index cc8b997643..13a64ddc67 100644 --- a/src/code-samples/deepagents/customization-overview.py +++ b/src/code-samples/deepagents/customization-overview.py @@ -35,11 +35,11 @@ def fetch_url(url: str) -> str: model="anthropic:claude-sonnet-4-6", system_prompt="You are a customer-support agent for ACME Corp.", ) -# Final = USER + BASE + SUFFIX +# Built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, +# and no profile sets `base_system_prompt` here, so: +# Final = USER + SUFFIX # = "You are a customer-support agent for ACME Corp." # + "\n\n" -# + BASE_AGENT_PROMPT -# + "\n\n" # + # :snippet-end: diff --git a/src/oss/deepagents/customization.mdx b/src/oss/deepagents/customization.mdx index e3a3ad07ca..1368b19604 100644 --- a/src/oss/deepagents/customization.mdx +++ b/src/oss/deepagents/customization.mdx @@ -31,7 +31,6 @@ import CustomizationToolsPy from '/snippets/code-samples/customization-tools-py. import CustomizationToolsJs from '/snippets/code-samples/customization-tools-js.mdx'; import CustomizationSystemPromptPy from '/snippets/code-samples/customization-system-prompt-py.mdx'; import CustomizationSystemPromptJs from '/snippets/code-samples/customization-system-prompt-js.mdx'; - import CustomizationMiddlewarePy from '/snippets/code-samples/customization-middleware-py.mdx'; import CustomizationMiddlewareJs from '/snippets/code-samples/customization-middleware-js.mdx'; import CustomizationMiddlewareDoPy from '/snippets/code-samples/customization-middleware-do-py.mdx'; @@ -53,6 +52,7 @@ import CustomizationOverviewPy from '/snippets/code-samples/customization-overvi import CustomizationOverviewJs from '/snippets/code-samples/customization-overview-js.mdx'; import CustomizationMcpPy from '/snippets/code-samples/customization-mcp-py.mdx'; import CustomizationMcpJs from '/snippets/code-samples/customization-mcp-js.mdx'; +import CustomizationPromptAssemblyPy from '/snippets/code-samples/customization-prompt-assembly-py.mdx'; import CustomizationGpSubagentProfilePy from '/snippets/code-samples/customization-gp-subagent-profile-py.mdx'; Build the harness around your goal. `create_deep_agent` gives you a production-ready foundation: connect it to your data, shape its behavior, and add the capabilities your use case needs. @@ -177,7 +177,13 @@ For detailed configuration options including stdio servers, OAuth authentication ## System prompt -Deep Agents ship with a built-in base system prompt that teaches the agent how to use the harness scaffolding (planning, filesystem tools, subagents). Pass `system_prompt=` to prepend your own instructions before that base prompt: +:::python +Deep Agents does not add an authored base system prompt by default: `create_deep_agent` starts from an empty base, so a deep agent ships with no persona or task guidance out of the box. Pass `system_prompt=` to add your own instructions, or pass `system_prompt=BASE_AGENT_PROMPT` to restore the SDK's built-in persona and task-guidance prompt, or set it on a [profile](/oss/deepagents/profiles#harness-profiles) as `base_system_prompt`: +::: + +:::js +Deep Agents ship with a built-in system prompt. A deep agent's value comes from the orchestration layer the SDK provides on top of the model—planning, virtual-filesystem tools, and subagents—and the model needs to know those exist and when to reach for them. The built-in prompt teaches the agent how to use that scaffolding so you don't have to re-derive it for every project; tweak it through a [profile](/oss/deepagents/profiles#harness-profiles) or your own `systemPrompt` rather than copying it verbatim. +::: :::python @@ -189,31 +195,44 @@ Deep Agents ship with a built-in base system prompt that teaches the agent how t When middleware adds special tools, like the filesystem tools, it appends its own guidance to the system prompt at runtime. +### Prompt assembly + :::python - -`SystemPromptConfig` requires `deepagents>=0.7.0a6`. - +Deep Agents builds the system prompt from up to three named parts so that caller-supplied instructions and any model-specific [profile](/oss/deepagents/profiles) overrides can coexist with predictable precedence. Without this layering, a profile suffix tuned for Claude (for example) could overwrite or be overwritten by your `system_prompt=` argument depending on call order; the named slots make the ordering explicit and stable. -For full control over prompt assembly, pass a @[`SystemPromptConfig`] dict with `prefix`, `base`, and `suffix` keys: +The three named parts (each may be absent): -- **`prefix`**: text placed before the base prompt (same as passing a bare string). -- **`base`**: replaces the built-in base prompt. Omit the key to keep the built-in base, or set it to `None` to drop the base entirely. -- **`suffix`**: text placed after the base prompt. +| Name | Source | Notes | +| -------- | ------------------------------------------------- | ------------------------------------------------- | +| `USER` | `system_prompt=` argument to `create_deep_agent` | `str` or `SystemMessage`; omitted when unset. | +| `BASE` | [`HarnessProfile.base_system_prompt`](/oss/deepagents/profiles#harness-profiles) | Empty unless a matching profile sets it. Pass `system_prompt=BASE_AGENT_PROMPT` to restore the SDK's authored prompt without a profile. | +| `SUFFIX` | [`HarnessProfile.system_prompt_suffix`](/oss/deepagents/profiles#harness-profiles) | Appended last when a matching profile sets it. | -Parts are assembled in order: `prefix` -> `base` -> `suffix` -> any model-specific [profile](/oss/deepagents/profiles) suffix. Each part accepts a `str` or a `SystemMessage` (to preserve `cache_control` markers for Anthropic prompt caching). +The order is always **`USER` -> `BASE` -> `SUFFIX`**, joined by blank lines (`\n\n`). Two invariants follow: -```python -# Overwrite the default base prompt: -create_deep_agent(..., system_prompt={"base": "..."}) +1. **`USER` is always at the front.** The caller's text precedes any profile content, so persona/instructions take precedence regardless of which model is selected. +2. **`SUFFIX` is always at the end.** Profile suffixes sit closest to the conversation history, where model-tuning guidance lands most reliably. -# No system prompt except from middleware: -create_deep_agent(..., system_prompt={"base": None}) +Assembled shapes (✓ = field is set, - = field is unset): -# Sandwich the default base prompt: -create_deep_agent(..., system_prompt={"prefix": "...", "suffix": "..."}) -``` +| `system_prompt=` | profile `base_system_prompt` (`BASE`) | profile `system_prompt_suffix` (`SUFFIX`) | Final assembled system prompt | +| ---------------- | :------------------------------------: | :----------------------------------------: | ------------------------------ | +| `None` | - | - | *(empty)* | +| `None` | - | ✓ | `SUFFIX` | +| `None` | ✓ | - | `BASE` | +| `None` | ✓ | ✓ | `BASE` + `SUFFIX` | +| `str` | - | - | `USER` | +| `str` | - | ✓ | `USER` + `SUFFIX` | +| `str` | ✓ | - | `USER` + `BASE` | +| `str` | ✓ | ✓ | `USER` + `BASE` + `SUFFIX` | + +Worked example—built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, so a typical call lands in the `str` + `-` + `✓` row: -For model-specific system prompt customization, such as replacing the base prompt or appending a suffix for a particular provider, use a [harness profile](/oss/deepagents/profiles#harness-profiles). + + + + Passing a `SystemMessage` (rather than a string) triggers a different concatenation path: the assembled `BASE` and `SUFFIX` are appended as an additional text content block onto the message's existing `content_blocks`. The same logical ordering applies (caller blocks first), and any `cache_control` markers on the caller's blocks are preserved—useful for placing explicit Anthropic prompt-cache breakpoints. + ::: diff --git a/src/oss/deepagents/profiles.mdx b/src/oss/deepagents/profiles.mdx index 2204e79e35..ae3cc29335 100644 --- a/src/oss/deepagents/profiles.mdx +++ b/src/oss/deepagents/profiles.mdx @@ -42,11 +42,11 @@ A harness profile describes prompt-assembly, tool-visibility, middleware, and de :::python - Replace the base Deep Agents system prompt (the `base` key in [System prompt](/oss/deepagents/customization#system-prompt)). + Replace the base Deep Agents system prompt (`BASE` in [Prompt assembly](/oss/deepagents/customization#prompt-assembly)). - Append text after the caller's `suffix`, placed last in the assembled system prompt. Applied to the main agent, declarative subagents, and the auto-added general-purpose subagent. + 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. diff --git a/src/oss/deepagents/subagents.mdx b/src/oss/deepagents/subagents.mdx index ba405b7808..649b72a667 100644 --- a/src/oss/deepagents/subagents.mdx +++ b/src/oss/deepagents/subagents.mdx @@ -414,7 +414,7 @@ For full details on schema types and strategies (tool calling vs. provider-nativ In addition to any user-defined subagents, every deep agent has access to a `general-purpose` subagent at all times. This subagent: -- Uses its own [default system prompt with profile overlays applied](/oss/deepagents/customization#system-prompt) +- Uses its own [default system prompt with profile overlays applied](/oss/deepagents/customization#prompt-assembly) - Has access to all the same tools - Uses the same model (unless overridden) - Inherits skills from the main agent (when skills are configured) diff --git a/src/oss/python/releases/changelog.mdx b/src/oss/python/releases/changelog.mdx index 3cc50b55ac..2348d4a3f8 100644 --- a/src/oss/python/releases/changelog.mdx +++ b/src/oss/python/releases/changelog.mdx @@ -17,7 +17,6 @@ rss: true - **`write_file` now overwrites existing files**: `write_file` used to error if the target file already existed. It now overwrites it — use `edit_file` for targeted changes to an existing file. - **[Override a default middleware instance](/oss/deepagents/customization#override-a-default-middleware-instance)**: A `middleware=` (or subagent `middleware`) instance whose `.name` matches a default now replaces that default in place, instead of erroring on duplicate middleware. - **[Restrict filesystem tools](/oss/deepagents/overview#virtual-filesystem-access)**: `FilesystemMiddleware` now accepts a `tools` allowlist to expose only a subset of the built-in filesystem tools to the model, building on the middleware-override behavior above. - - **[Structured system prompt configuration](/oss/deepagents/customization#system-prompt)**: The `system_prompt` parameter now accepts a `SystemPromptConfig` dict with `prefix`, `base`, and `suffix` keys, enabling callers to replace or remove the built-in base prompt and add text before or after it. diff --git a/src/snippets/code-samples/customization-prompt-assembly-py.mdx b/src/snippets/code-samples/customization-prompt-assembly-py.mdx index 92e95bce33..40fedc1ae2 100644 --- a/src/snippets/code-samples/customization-prompt-assembly-py.mdx +++ b/src/snippets/code-samples/customization-prompt-assembly-py.mdx @@ -6,11 +6,11 @@ model="google_genai:gemini-3.5-flash", system_prompt="You are a customer-support agent for ACME Corp.", ) - # Final = USER + BASE + SUFFIX + # Built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, + # and no profile sets `base_system_prompt` here, so: + # Final = USER + SUFFIX # = "You are a customer-support agent for ACME Corp." # + "\n\n" - # + BASE_AGENT_PROMPT - # + "\n\n" # + ``` @@ -21,11 +21,11 @@ model="openai:gpt-5.5", system_prompt="You are a customer-support agent for ACME Corp.", ) - # Final = USER + BASE + SUFFIX + # Built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, + # and no profile sets `base_system_prompt` here, so: + # Final = USER + SUFFIX # = "You are a customer-support agent for ACME Corp." # + "\n\n" - # + BASE_AGENT_PROMPT - # + "\n\n" # + ``` @@ -36,11 +36,11 @@ model="anthropic:claude-sonnet-4-6", system_prompt="You are a customer-support agent for ACME Corp.", ) - # Final = USER + BASE + SUFFIX + # Built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, + # and no profile sets `base_system_prompt` here, so: + # Final = USER + SUFFIX # = "You are a customer-support agent for ACME Corp." # + "\n\n" - # + BASE_AGENT_PROMPT - # + "\n\n" # + ``` @@ -51,11 +51,11 @@ model="openrouter:z-ai/glm-5.2", system_prompt="You are a customer-support agent for ACME Corp.", ) - # Final = USER + BASE + SUFFIX + # Built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, + # and no profile sets `base_system_prompt` here, so: + # Final = USER + SUFFIX # = "You are a customer-support agent for ACME Corp." # + "\n\n" - # + BASE_AGENT_PROMPT - # + "\n\n" # + ``` @@ -66,11 +66,11 @@ model="fireworks:accounts/fireworks/models/glm-5p2", system_prompt="You are a customer-support agent for ACME Corp.", ) - # Final = USER + BASE + SUFFIX + # Built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, + # and no profile sets `base_system_prompt` here, so: + # Final = USER + SUFFIX # = "You are a customer-support agent for ACME Corp." # + "\n\n" - # + BASE_AGENT_PROMPT - # + "\n\n" # + ``` @@ -81,11 +81,11 @@ model="baseten:zai-org/GLM-5.2", system_prompt="You are a customer-support agent for ACME Corp.", ) - # Final = USER + BASE + SUFFIX + # Built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, + # and no profile sets `base_system_prompt` here, so: + # Final = USER + SUFFIX # = "You are a customer-support agent for ACME Corp." # + "\n\n" - # + BASE_AGENT_PROMPT - # + "\n\n" # + ``` @@ -96,11 +96,11 @@ model="ollama:north-mini-code-1.0", system_prompt="You are a customer-support agent for ACME Corp.", ) - # Final = USER + BASE + SUFFIX + # Built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, + # and no profile sets `base_system_prompt` here, so: + # Final = USER + SUFFIX # = "You are a customer-support agent for ACME Corp." # + "\n\n" - # + BASE_AGENT_PROMPT - # + "\n\n" # + ``` From 4bab4d2699a4e2cac88b52f69d9e2c90ec88231f Mon Sep 17 00:00:00 2001 From: Nishitha M <32355027+imnishitha@users.noreply.github.com> Date: Mon, 27 Jul 2026 14:40:02 +0000 Subject: [PATCH 2/8] docs: address review feedback, keep #4876 simplification Co-authored-by: open-swe[bot] --- .../deepagents/customization-overview.py | 6 +-- src/oss/deepagents/customization.mdx | 48 ++----------------- src/oss/deepagents/profiles.mdx | 4 +- src/oss/deepagents/subagents.mdx | 2 +- .../customization-prompt-assembly-py.mdx | 42 ++++++++-------- 5 files changed, 30 insertions(+), 72 deletions(-) diff --git a/src/code-samples/deepagents/customization-overview.py b/src/code-samples/deepagents/customization-overview.py index 13a64ddc67..cc8b997643 100644 --- a/src/code-samples/deepagents/customization-overview.py +++ b/src/code-samples/deepagents/customization-overview.py @@ -35,11 +35,11 @@ def fetch_url(url: str) -> str: model="anthropic:claude-sonnet-4-6", system_prompt="You are a customer-support agent for ACME Corp.", ) -# Built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, -# and no profile sets `base_system_prompt` here, so: -# Final = USER + SUFFIX +# Final = USER + BASE + SUFFIX # = "You are a customer-support agent for ACME Corp." # + "\n\n" +# + BASE_AGENT_PROMPT +# + "\n\n" # + # :snippet-end: diff --git a/src/oss/deepagents/customization.mdx b/src/oss/deepagents/customization.mdx index f7f65ec50b..4b3d83b29a 100644 --- a/src/oss/deepagents/customization.mdx +++ b/src/oss/deepagents/customization.mdx @@ -31,6 +31,7 @@ import CustomizationToolsPy from '/snippets/code-samples/customization-tools-py. import CustomizationToolsJs from '/snippets/code-samples/customization-tools-js.mdx'; import CustomizationSystemPromptPy from '/snippets/code-samples/customization-system-prompt-py.mdx'; import CustomizationSystemPromptJs from '/snippets/code-samples/customization-system-prompt-js.mdx'; + import CustomizationMiddlewarePy from '/snippets/code-samples/customization-middleware-py.mdx'; import CustomizationMiddlewareJs from '/snippets/code-samples/customization-middleware-js.mdx'; import CustomizationMiddlewareDoPy from '/snippets/code-samples/customization-middleware-do-py.mdx'; @@ -52,7 +53,6 @@ import CustomizationOverviewPy from '/snippets/code-samples/customization-overvi import CustomizationOverviewJs from '/snippets/code-samples/customization-overview-js.mdx'; import CustomizationMcpPy from '/snippets/code-samples/customization-mcp-py.mdx'; import CustomizationMcpJs from '/snippets/code-samples/customization-mcp-js.mdx'; -import CustomizationPromptAssemblyPy from '/snippets/code-samples/customization-prompt-assembly-py.mdx'; import CustomizationGpSubagentProfilePy from '/snippets/code-samples/customization-gp-subagent-profile-py.mdx'; Build the harness around your goal. `create_deep_agent` gives you a production-ready foundation: connect it to your data, shape its behavior, and add the capabilities your use case needs. @@ -177,13 +177,7 @@ For detailed configuration options including stdio servers, OAuth authentication ## System prompt -:::python -Deep Agents does not add an authored base system prompt by default: `create_deep_agent` starts from an empty base, so a deep agent ships with no persona or task guidance out of the box. Pass `system_prompt=` to add your own instructions, or pass `system_prompt=BASE_AGENT_PROMPT` to restore the SDK's built-in persona and task-guidance prompt, or set it on a [profile](/oss/deepagents/profiles#harness-profiles) as `base_system_prompt`: -::: - -:::js -Deep Agents ship with a built-in system prompt. A deep agent's value comes from the orchestration layer the SDK provides on top of the model—planning, virtual-filesystem tools, and subagents—and the model needs to know those exist and when to reach for them. The built-in prompt teaches the agent how to use that scaffolding so you don't have to re-derive it for every project; tweak it through a [profile](/oss/deepagents/profiles#harness-profiles) or your own `systemPrompt` rather than copying it verbatim. -::: +Deep Agents ship with a built-in base system prompt that teaches the agent how to use the harness scaffolding (planning, filesystem tools, subagents). Pass `system_prompt=` to prepend your own instructions before that base prompt: :::python @@ -199,44 +193,8 @@ Besides a string, the main agent also accepts a @[`SystemMessage`] with structur When middleware adds special tools, like the filesystem tools, it appends its own guidance to the system prompt at runtime. -### Prompt assembly - :::python -Deep Agents builds the system prompt from up to three named parts so that caller-supplied instructions and any model-specific [profile](/oss/deepagents/profiles) overrides can coexist with predictable precedence. Without this layering, a profile suffix tuned for Claude (for example) could overwrite or be overwritten by your `system_prompt=` argument depending on call order; the named slots make the ordering explicit and stable. - -The three named parts (each may be absent): - -| Name | Source | Notes | -| -------- | ------------------------------------------------- | ------------------------------------------------- | -| `USER` | `system_prompt=` argument to `create_deep_agent` | `str` or `SystemMessage`; omitted when unset. | -| `BASE` | [`HarnessProfile.base_system_prompt`](/oss/deepagents/profiles#harness-profiles) | Empty unless a matching profile sets it. Pass `system_prompt=BASE_AGENT_PROMPT` to restore the SDK's authored prompt without a profile. | -| `SUFFIX` | [`HarnessProfile.system_prompt_suffix`](/oss/deepagents/profiles#harness-profiles) | Appended last when a matching profile sets it. | - -The order is always **`USER` -> `BASE` -> `SUFFIX`**, joined by blank lines (`\n\n`). Two invariants follow: - -1. **`USER` is always at the front.** The caller's text precedes any profile content, so persona/instructions take precedence regardless of which model is selected. -2. **`SUFFIX` is always at the end.** Profile suffixes sit closest to the conversation history, where model-tuning guidance lands most reliably. - -Assembled shapes (✓ = field is set, - = field is unset): - -| `system_prompt=` | profile `base_system_prompt` (`BASE`) | profile `system_prompt_suffix` (`SUFFIX`) | Final assembled system prompt | -| ---------------- | :------------------------------------: | :----------------------------------------: | ------------------------------ | -| `None` | - | - | *(empty)* | -| `None` | - | ✓ | `SUFFIX` | -| `None` | ✓ | - | `BASE` | -| `None` | ✓ | ✓ | `BASE` + `SUFFIX` | -| `str` | - | - | `USER` | -| `str` | - | ✓ | `USER` + `SUFFIX` | -| `str` | ✓ | - | `USER` + `BASE` | -| `str` | ✓ | ✓ | `USER` + `BASE` + `SUFFIX` | - -Worked example—built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, so a typical call lands in the `str` + `-` + `✓` row: - - - - - Passing a `SystemMessage` (rather than a string) triggers a different concatenation path: the assembled `BASE` and `SUFFIX` are appended as an additional text content block onto the message's existing `content_blocks`. The same logical ordering applies (caller blocks first), and any `cache_control` markers on the caller's blocks are preserved—useful for placing explicit Anthropic prompt-cache breakpoints. - +For model-specific system prompt customization, such as replacing the base prompt or appending a suffix for a particular provider, use a [harness profile](/oss/deepagents/profiles#harness-profiles): set `base_system_prompt` to replace the built-in base, or `system_prompt_suffix` to append text after it. ::: diff --git a/src/oss/deepagents/profiles.mdx b/src/oss/deepagents/profiles.mdx index ae3cc29335..2204e79e35 100644 --- a/src/oss/deepagents/profiles.mdx +++ b/src/oss/deepagents/profiles.mdx @@ -42,11 +42,11 @@ A harness profile describes prompt-assembly, tool-visibility, middleware, and de :::python - Replace the base Deep Agents system prompt (`BASE` in [Prompt assembly](/oss/deepagents/customization#prompt-assembly)). + Replace the base Deep Agents system prompt (the `base` key in [System prompt](/oss/deepagents/customization#system-prompt)). - 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. + Append text after the caller's `suffix`, placed last in the assembled system prompt. Applied to the main agent, declarative subagents, and the auto-added general-purpose subagent. diff --git a/src/oss/deepagents/subagents.mdx b/src/oss/deepagents/subagents.mdx index 3d66adb205..b246c1ca23 100644 --- a/src/oss/deepagents/subagents.mdx +++ b/src/oss/deepagents/subagents.mdx @@ -409,7 +409,7 @@ For full details on schema types and strategies (tool calling vs. provider-nativ In addition to any user-defined subagents, every deep agent has access to a `general-purpose` subagent at all times. This subagent: -- Uses its own [default system prompt with profile overlays applied](/oss/deepagents/customization#prompt-assembly) +- Uses its own [default system prompt with profile overlays applied](/oss/deepagents/customization#system-prompt) - Has access to all the same tools - Uses the same model (unless overridden) - Inherits skills from the main agent (when skills are configured) diff --git a/src/snippets/code-samples/customization-prompt-assembly-py.mdx b/src/snippets/code-samples/customization-prompt-assembly-py.mdx index 40fedc1ae2..92e95bce33 100644 --- a/src/snippets/code-samples/customization-prompt-assembly-py.mdx +++ b/src/snippets/code-samples/customization-prompt-assembly-py.mdx @@ -6,11 +6,11 @@ model="google_genai:gemini-3.5-flash", system_prompt="You are a customer-support agent for ACME Corp.", ) - # Built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, - # and no profile sets `base_system_prompt` here, so: - # Final = USER + SUFFIX + # Final = USER + BASE + SUFFIX # = "You are a customer-support agent for ACME Corp." # + "\n\n" + # + BASE_AGENT_PROMPT + # + "\n\n" # + ``` @@ -21,11 +21,11 @@ model="openai:gpt-5.5", system_prompt="You are a customer-support agent for ACME Corp.", ) - # Built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, - # and no profile sets `base_system_prompt` here, so: - # Final = USER + SUFFIX + # Final = USER + BASE + SUFFIX # = "You are a customer-support agent for ACME Corp." # + "\n\n" + # + BASE_AGENT_PROMPT + # + "\n\n" # + ``` @@ -36,11 +36,11 @@ model="anthropic:claude-sonnet-4-6", system_prompt="You are a customer-support agent for ACME Corp.", ) - # Built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, - # and no profile sets `base_system_prompt` here, so: - # Final = USER + SUFFIX + # Final = USER + BASE + SUFFIX # = "You are a customer-support agent for ACME Corp." # + "\n\n" + # + BASE_AGENT_PROMPT + # + "\n\n" # + ``` @@ -51,11 +51,11 @@ model="openrouter:z-ai/glm-5.2", system_prompt="You are a customer-support agent for ACME Corp.", ) - # Built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, - # and no profile sets `base_system_prompt` here, so: - # Final = USER + SUFFIX + # Final = USER + BASE + SUFFIX # = "You are a customer-support agent for ACME Corp." # + "\n\n" + # + BASE_AGENT_PROMPT + # + "\n\n" # + ``` @@ -66,11 +66,11 @@ model="fireworks:accounts/fireworks/models/glm-5p2", system_prompt="You are a customer-support agent for ACME Corp.", ) - # Built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, - # and no profile sets `base_system_prompt` here, so: - # Final = USER + SUFFIX + # Final = USER + BASE + SUFFIX # = "You are a customer-support agent for ACME Corp." # + "\n\n" + # + BASE_AGENT_PROMPT + # + "\n\n" # + ``` @@ -81,11 +81,11 @@ model="baseten:zai-org/GLM-5.2", system_prompt="You are a customer-support agent for ACME Corp.", ) - # Built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, - # and no profile sets `base_system_prompt` here, so: - # Final = USER + SUFFIX + # Final = USER + BASE + SUFFIX # = "You are a customer-support agent for ACME Corp." # + "\n\n" + # + BASE_AGENT_PROMPT + # + "\n\n" # + ``` @@ -96,11 +96,11 @@ model="ollama:north-mini-code-1.0", system_prompt="You are a customer-support agent for ACME Corp.", ) - # Built-in profiles (Anthropic, OpenAI) ship only a `system_prompt_suffix`, - # and no profile sets `base_system_prompt` here, so: - # Final = USER + SUFFIX + # Final = USER + BASE + SUFFIX # = "You are a customer-support agent for ACME Corp." # + "\n\n" + # + BASE_AGENT_PROMPT + # + "\n\n" # + ``` From ebbf576a7f14158c20b841a6ee19bbd4252e3237 Mon Sep 17 00:00:00 2001 From: Nishitha M <32355027+imnishitha@users.noreply.github.com> Date: Mon, 27 Jul 2026 14:51:44 +0000 Subject: [PATCH 3/8] docs: drop harness-profile mention from system prompt section Co-authored-by: open-swe[bot] --- src/oss/deepagents/customization.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/oss/deepagents/customization.mdx b/src/oss/deepagents/customization.mdx index 4b3d83b29a..a8e24ad10f 100644 --- a/src/oss/deepagents/customization.mdx +++ b/src/oss/deepagents/customization.mdx @@ -193,10 +193,6 @@ Besides a string, the main agent also accepts a @[`SystemMessage`] with structur When middleware adds special tools, like the filesystem tools, it appends its own guidance to the system prompt at runtime. -:::python -For model-specific system prompt customization, such as replacing the base prompt or appending a suffix for a particular provider, use a [harness profile](/oss/deepagents/profiles#harness-profiles): set `base_system_prompt` to replace the built-in base, or `system_prompt_suffix` to append text after it. -::: - Declarative [subagents](/oss/deepagents/subagents) resolve profile overlays against their own model, then apply the resolved profile's `base_system_prompt` / `system_prompt_suffix` to the subagent's authored `system_prompt`. A profile that ships only a `system_prompt_suffix` (the common case for built-in Anthropic / OpenAI profiles) appends to the authored prompt. A profile that sets `base_system_prompt` replaces it outright. From fbd5f92046b0b4f2658b7af960a063f54a3f6ff8 Mon Sep 17 00:00:00 2001 From: Nishitha M <32355027+imnishitha@users.noreply.github.com> Date: Mon, 27 Jul 2026 17:00:14 +0000 Subject: [PATCH 4/8] docs: drop changelog diff and fix stale system-prompt intro Co-authored-by: open-swe[bot] --- src/oss/deepagents/customization.mdx | 2 +- src/oss/python/releases/changelog.mdx | 7 ------- 2 files changed, 1 insertion(+), 8 deletions(-) diff --git a/src/oss/deepagents/customization.mdx b/src/oss/deepagents/customization.mdx index a8e24ad10f..b018440ff6 100644 --- a/src/oss/deepagents/customization.mdx +++ b/src/oss/deepagents/customization.mdx @@ -177,7 +177,7 @@ For detailed configuration options including stdio servers, OAuth authentication ## System prompt -Deep Agents ship with a built-in base system prompt that teaches the agent how to use the harness scaffolding (planning, filesystem tools, subagents). Pass `system_prompt=` to prepend your own instructions before that base prompt: +Pass `system_prompt=` to give the agent your own instructions: :::python diff --git a/src/oss/python/releases/changelog.mdx b/src/oss/python/releases/changelog.mdx index 9971e76c01..8abb4b0127 100644 --- a/src/oss/python/releases/changelog.mdx +++ b/src/oss/python/releases/changelog.mdx @@ -31,14 +31,7 @@ rss: true - **Planning todos are opt-in**: `create_deep_agent` no longer includes `ToDoListMiddleware` by default, so the `write_todos` tool, `todos` state channel, and todo-planning prompt are absent unless restored with `middleware=[ToDoListMiddleware()]`. (The OpenAI Codex harness profile still opts in automatically.) ([#4929](https://github.com/langchain-ai/deepagents/pull/4929)) - **Backend compatibility shims removed**: Pass concrete `BackendProtocol` instances instead of factories, configure `StoreBackend` with an explicit `namespace`, and use the current `ls` / `glob` / `grep` / `ReadResult` APIs. Removed symbols include `BackendFactory`, `BACKEND_TYPES`, `FileFormat`, and `Unset`. New files store string `FileData.content`; older `list[str]` content stays readable and converts on next write. ([#4541](https://github.com/langchain-ai/deepagents/pull/4541)) - **Output format changes**: Empty `ls` / `glob` output is now `No files found` instead of `[]`, and `read_file` no longer renders a fixed-width `cat -n`-style gutter — update any parsers of raw tool output. ([#4561](https://github.com/langchain-ai/deepagents/pull/4561)) - - - ## `deepagents` v0.7.0a6 - - **New [`delete`](/oss/deepagents/tools#built-in-harness-tools) filesystem tool**: Delete a file, or recursively delete a directory and its contents. Backends that don't support deletion have the tool automatically hidden from the model. - - **`write_file` now overwrites existing files**: `write_file` used to error if the target file already existed. It now overwrites it — use `edit_file` for targeted changes to an existing file. - - **[Override a default middleware instance](/oss/deepagents/customization#override-a-default-middleware-instance)**: A `middleware=` (or subagent `middleware`) instance whose `.name` matches a default now replaces that default in place, instead of erroring on duplicate middleware. - - **[Restrict filesystem tools](/oss/deepagents/overview#virtual-filesystem-access)**: `FilesystemMiddleware` now accepts a `tools` allowlist to expose only a subset of the built-in filesystem tools to the model, building on the middleware-override behavior above. ## `deepagents` v0.6.0 From 2b7581143bbe3fbc71e184bd5fe81938c833711d Mon Sep 17 00:00:00 2001 From: Nishitha M <32355027+imnishitha@users.noreply.github.com> Date: Mon, 27 Jul 2026 17:37:26 +0000 Subject: [PATCH 5/8] docs: drop remaining base-prompt mention from SystemMessage note Co-authored-by: open-swe[bot] --- src/oss/deepagents/customization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oss/deepagents/customization.mdx b/src/oss/deepagents/customization.mdx index b018440ff6..9127ed1cbd 100644 --- a/src/oss/deepagents/customization.mdx +++ b/src/oss/deepagents/customization.mdx @@ -188,7 +188,7 @@ Pass `system_prompt=` to give the agent your own instructions: ::: -Besides a string, the main agent also accepts a @[`SystemMessage`] with structured [content blocks](/oss/langchain/messages#standard-content-blocks); Deep Agents preserve those blocks and append the built-in base prompt ([subagent](/oss/deepagents/subagents) dictionary specs remain strings). +Besides a string, the main agent also accepts a @[`SystemMessage`] with structured [content blocks](/oss/langchain/messages#standard-content-blocks); Deep Agents preserve those blocks ([subagent](/oss/deepagents/subagents) dictionary specs remain strings). When middleware adds special tools, like the filesystem tools, it appends its own guidance to the system prompt at runtime. From 6a513ad886ac7b5e5cb75caed3175d41d613c1b5 Mon Sep 17 00:00:00 2001 From: Nishitha M <32355027+imnishitha@users.noreply.github.com> Date: Mon, 27 Jul 2026 18:40:41 +0000 Subject: [PATCH 6/8] docs: resync Python create_deep_agent signature (drop SystemPromptConfig) Co-authored-by: open-swe[bot] --- src/snippets/create-deep-agent-config-options-py.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/snippets/create-deep-agent-config-options-py.mdx b/src/snippets/create-deep-agent-config-options-py.mdx index d71a7de6ea..68fc805543 100644 --- a/src/snippets/create-deep-agent-config-options-py.mdx +++ b/src/snippets/create-deep-agent-config-options-py.mdx @@ -3,7 +3,7 @@ create_deep_agent( model: str | BaseChatModel | None = None, tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None, *, - system_prompt: str | SystemMessage | SystemPromptConfig | None = None, + system_prompt: str | SystemMessage | None = None, middleware: Sequence[AgentMiddleware] = (), subagents: Sequence[SubAgent | CompiledSubAgent | AsyncSubAgent] | None = None, skills: list[str] | None = None, From ae0fb92799223206947e31930bf056c7cd46df66 Mon Sep 17 00:00:00 2001 From: Nishitha M <32355027+imnishitha@users.noreply.github.com> Date: Mon, 27 Jul 2026 18:59:21 +0000 Subject: [PATCH 7/8] docs: drop deprecated SystemPromptConfig from JS signature snippet Co-authored-by: open-swe[bot] --- src/snippets/create-deep-agent-config-options-js.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/snippets/create-deep-agent-config-options-js.mdx b/src/snippets/create-deep-agent-config-options-js.mdx index 64e4f7e528..0e70e583e3 100644 --- a/src/snippets/create-deep-agent-config-options-js.mdx +++ b/src/snippets/create-deep-agent-config-options-js.mdx @@ -15,7 +15,7 @@ const agent = createDeepAgent({ store?: BaseStore, streamTransformers?: TStreamTransformers, subagents?: TSubagents, - systemPrompt?: string | SystemMessage> | SystemPromptConfig, + systemPrompt?: string | SystemMessage>, tools?: TTools | StructuredTool[] }); ``` From 453dd4a3fef0966c4df1227b628b5cb6385e9dd2 Mon Sep 17 00:00:00 2001 From: Nishitha Madhu Date: Tue, 28 Jul 2026 14:14:10 -0400 Subject: [PATCH 8/8] review comment --- src/oss/deepagents/customization.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/oss/deepagents/customization.mdx b/src/oss/deepagents/customization.mdx index 9127ed1cbd..9dd312ccde 100644 --- a/src/oss/deepagents/customization.mdx +++ b/src/oss/deepagents/customization.mdx @@ -191,7 +191,6 @@ Pass `system_prompt=` to give the agent your own instructions: Besides a string, the main agent also accepts a @[`SystemMessage`] with structured [content blocks](/oss/langchain/messages#standard-content-blocks); Deep Agents preserve those blocks ([subagent](/oss/deepagents/subagents) dictionary specs remain strings). -When middleware adds special tools, like the filesystem tools, it appends its own guidance to the system prompt at runtime.