feat: add subagent documentation to deploy page (#3615)

## Description
Adds comprehensive subagent documentation to the "Deploy with the CLI"
page based on the implementation in langchain-ai/deepagents#2786.
Subagents are auto-discovered from a `subagents/` directory and let the
main agent delegate specialized tasks to isolated child agents with
their own system prompts, skills, and MCP tools. By default, subagents
inherit model and tools from the main agent but not skills.

## Test Plan
- [ ] Test in preview deployment

_Opened collaboratively by Sydney Runkle and open-swe._

---------

Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
Co-authored-by: Sydney Runkle <54324534+sydney-runkle@users.noreply.github.com>
Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>

Author: 4 people

src/oss/deepagents/deploy.mdx

@@ -40,6 +40,7 @@ Deep Agents Deploy takes your agent configuration and deploys it as a [LangSmith
 | **`skills`** | [Agent Skills](https://agentskills.io/) for specialized knowledge and actions. Skills are synced into the sandbox so the agent can execute them at runtime. See [skills docs](/oss/deepagents/skills). |
 | **``user/``** | Per-user writable memory. If a `AGENTS.md` template is present in the `user` folder, the agents seeds the template per user (if the folder is empty the agents creates an empty `AGENTS.md`). Writable at runtime. Preloaded into the agent's context via the memory middleware. |
 | **`mcp.json`** | MCP tools (HTTP/SSE). See [MCP docs](/oss/langchain/mcp). |
+| **`subagents/`** | Specialized [subagents](/oss/deepagents/subagents) the main agent can delegate to. Each subdirectory contains its own `deepagents.toml`, `AGENTS.md`, and optionally a `skills` folder. See [subagents](#subagents). |
 | **`sandbox`** | Optional execution environment. Thread-scoped sandboxes are provisioned per thread and will be re-created if the server restarts. Use `scope = "assistant"` if you need sandbox state that persists across threads. See [sandbox providers](#sandbox-providers). |
 
 ## Install
@@ -107,6 +108,10 @@ my-agent/
 │   │   └── SKILL.md
 │   └── data-analysis/
 │       └── SKILL.md
+├── subagents/
+│   └── researcher/
+│       ├── deepagents.toml
+│       └── AGENTS.md
 └── user/
     └── AGENTS.md
 ```
@@ -116,6 +121,7 @@ my-agent/
 | `AGENTS.md` | [Memory](/oss/deepagents/memory) for the agent. Provides persistent context (project conventions, instructions, preferences) that is always loaded at startup. Read-only at runtime. | Yes |
 | `skills/` | Directory of [skill](/oss/deepagents/skills) definitions. Each subdirectory should contain a `SKILL.md` file. Read-only at runtime. | No |
 | `user/` | Per-user writable memory. If a `AGENTS.md` template is present in the `user` folder, the agents seeds the template per user (if the folder is empty the agents creates an empty `AGENTS.md`). Writable at runtime. Preloaded into the agent's context via the memory middleware. | No |
+| `subagents/` | [Subagents](#subagents) the main agent can delegate to. Each subdirectory must contain a `deepagents.toml`, `AGENTS.md`, and optionally a `skills` folder. Auto-discovered at bundle time. | No |
 | `mcp.json` | [MCP](https://modelcontextprotocol.io/) server configuration. Only `http` and `sse` transports are supported in deployed contexts. | No |
 | `.env` | Environment variables (API keys, secrets). Placed alongside `deepagents.toml` at the project root. | No |
 
@@ -153,12 +159,13 @@ model = "google_genai:gemini-3.1-pro-preview"
     The `name` field is the only required value in the entire configuration file. Everything else has defaults.
 </Note>
 
-Skills, user memories, MCP servers, and model dependencies are auto-detected from the project layout — you don't declare them in `deepagents.toml`:
+Skills, user memories, subagents, MCP servers, and model dependencies are auto-detected from the project layout:
 
 - **Skills**: the bundler recursively scans `skills/`, skipping hidden dotfiles, and bundles the rest.
 - **User memory**: if `user/` exists, a single `AGENTS.md` is bundled as per-user memory (from `user/AGENTS.md` if present, otherwise empty). At runtime, each user gets their own copy (seeded on first access, never overwritten). The agent can read from and write to this file.
+- **Subagents**: if `subagents/` exists, the bundler scans for valid subdirectories (each must contain `deepagents.toml` and `AGENTS.md`). The main agent receives a `task` tool to delegate work to each subagent by name. See [subagents](#subagents).
 - **MCP servers**: if `mcp.json` exists, it is included in the deployment and [`langchain-mcp-adapters`](https://pypi.org/project/langchain-mcp-adapters/) is added as a dependency. Only HTTP/SSE transports are supported (stdio is rejected at bundle time).
-- **Model dependencies**: the `provider:` prefix in the `model` field determines the required `langchain-*` package (e.g., `google_genai` -> `langchain-google-genai`).
+- **Model dependencies**: the `provider:` prefix in the `model` field determines the required `langchain-*` package (e.g., `google_genai` -> `langchain-google-genai`). This includes models specified in subagent configs.
 - **Sandbox dependencies**: the `[sandbox].provider` value maps to its partner package (e.g., `daytona` -> `langchain-daytona`).
 
 ### `[sandbox]`
@@ -256,6 +263,24 @@ template = "coding-agent"
 image = "python:3.12"
 ```
 
+A GTM strategy agent that delegates research to a subagent:
+
+```txt
+my-gtm-agent/
+├── deepagents.toml
+├── AGENTS.md
+├── skills/
+│   └── competitor-analysis/
+│       └── SKILL.md
+└── subagents/
+    └── market-researcher/
+        ├── deepagents.toml
+        ├── AGENTS.md
+        └── skills/
+            └── analyze-market/
+                └── SKILL.md
+```
+
 ## User Memory
 
 User memory gives each user their own writable `AGENTS.md` that persists across conversations. To enable it, create a `user/` directory at your project root:
@@ -283,17 +308,124 @@ At runtime, user memory is scoped per user via custom auth (`runtime.server_info
 | `/memories/AGENTS.md` | No | Shared (assistant-scoped) |
 | `/memories/skills/**` | No | Shared (assistant-scoped) |
 | `/memories/user/**` | Yes | Per-user (`user_id`-scoped) |
+| `/memories/subagents/<name>/**` | By subagent only | Per-subagent (isolated) |
 
 ### User identity
 
 The `user_id` is resolved from custom auth via `runtime.user.identity`. The platform injects the authenticated user's identity automatically — no need to pass it through `configurable`. If no authenticated user is present, user memory features are gracefully skipped for that invocation.
 
-## Gotchas
+## Subagents
+
+Subagents let the main agent delegate specialized tasks to isolated child agents. Each subagent has its own system prompt, optional skills, and optional MCP tools. The main agent receives a `task` tool that dispatches work to subagents by name.
+
+For background on why subagents are useful and how they work at the SDK level, see [Subagents](/oss/deepagents/subagents).
+
+### Directory structure
+
+Create a `subagents/` directory at your project root. Each subdirectory is a subagent:
+
+```txt
+my-agent/
+├── deepagents.toml
+├── AGENTS.md
+└── subagents/
+    ├── researcher/
+    │   ├── deepagents.toml       # name, description, optional model override
+    │   ├── AGENTS.md             # subagent system prompt
+    │   ├── skills/               # optional — subagent-specific skills
+    │   │   └── analyze-market/
+    │   │       └── SKILL.md
+    │   └── mcp.json              # optional — HTTP/SSE MCP tools
+    └── writer/
+        ├── deepagents.toml
+        └── AGENTS.md
+```
+
+Each subagent subdirectory **must** contain:
+
+| File | Purpose |
+| --- | --- |
+| `deepagents.toml` | Subagent config with `[agent].name` and `[agent].description` |
+| `AGENTS.md` | System prompt for the subagent |
+
+Each subagent subdirectory **may** contain:
+
+| File | Purpose |
+| --- | --- |
+| `skills/` | Subagent-specific skills (with `SKILL.md` files) |
+| `mcp.json` | MCP server configuration (HTTP/SSE only; stdio is rejected) |
+
+### Subagent configuration
+
+<ResponseField name="name" type="string" required>
+    Unique identifier for the subagent. Must be unique across all subagents.
+</ResponseField>
+
+<ResponseField name="description" type="string" required>
+    What this subagent does. The main agent uses this to decide when to delegate. Must be non-empty.
+</ResponseField>
+
+<ResponseField name="model" type="string">
+    Model override in `provider:model` format. Omit to inherit the main agent's model.
+</ResponseField>
+
+```toml subagents/researcher/deepagents.toml
+[agent]
+name = "researcher"
+description = "Researches market trends, competitors, and target audiences"
+model = "anthropic:claude-haiku-4-5-20251001"
+```
+
+### Inheritance
+
+Subagents inherit some properties from the main agent by default:
+
+| Property | Inherited | Notes |
+| --- | --- | --- |
+| Model | Yes | Override with `model` in the subagent's `deepagents.toml` |
+| Tools | Yes | Override by adding `mcp.json` to the subagent directory |
+| Skills | No | Declare explicitly in the subagent's own `skills/` directory |
+
+### Memory isolation
+
+Each subagent gets a dedicated, isolated memory namespace at `/memories/subagents/<name>/`. The subagent's `AGENTS.md` and skills are seeded into this namespace at deploy time.
+
+| Path | Main agent | Subagent |
+| --- | --- | --- |
+| `/memories/AGENTS.md` | Read | No access |
+| `/memories/skills/**` | Read | No access |
+| `/memories/user/**` | Read + Write | No access |
+| `/memories/subagents/<name>/**` | Read | Read + Write |
+
+### Example
+
+A go-to-market agent that delegates research to a specialized subagent:
+
+```toml deepagents.toml
+[agent]
+name = "gtm-strategist"
+model = "anthropic:claude-sonnet-4-6"
+```
+
+```toml subagents/researcher/deepagents.toml
+[agent]
+name = "researcher"
+description = "Researches market trends, competitors, and target audiences to inform GTM strategy"
+model = "anthropic:claude-haiku-4-5-20251001"
+```
+
+```markdown subagents/researcher/AGENTS.md
+# Market Researcher
+
+You are a market research specialist. Your job is to gather and synthesize
+market data to support go-to-market decisions.
+
+## Focus Areas
+- Market sizing: TAM, SAM, SOM estimates
+- Competitor analysis: product positioning, pricing, market share
+- Audience segmentation: demographics, psychographics, buying behavior
+```
 
-- **AGENTS.md and skills are read-only at runtime.** Edit source files and redeploy to update them. The per-user `AGENTS.md` at `/memories/user/AGENTS.md` is the exception — it is writable by the agent.
-- **Full rebuild on deploy:** `deepagents deploy` creates a new revision on every invocation. Use `deepagents dev` for local iteration.
-- **Sandbox lifecycle:** Thread-scoped sandboxes are provisioned per thread and will be re-created if the server restarts. Use `scope = "assistant"` if you need sandbox state that persists across threads.
-- **MCP: HTTP/SSE only.** Stdio transports are rejected at bundle time.
 ## Limitations
 
 - **MCP: HTTP/SSE only.** Stdio transports are rejected at bundle time.

src/oss/deepagents/subagents.mdx

@@ -84,6 +84,8 @@ For most use cases, define subagents as dictionaries matching the @[`SubAgent`]
 
 <Tip>
     **CLI users:** You can also define subagents as `AGENTS.md` files on disk instead of in code. The `name`, `description`, and `model` fields map to YAML frontmatter, and the markdown body becomes the `system_prompt`. See [Custom subagents](/oss/deepagents/cli/overview#subagents) for the file format.
+
+    **Deploy users:** Define subagents as directories under `subagents/` with their own `deepagents.toml` and `AGENTS.md`. The bundler auto-discovers them. See [Deploy subagents](/oss/deepagents/deploy#subagents) for the full configuration reference.
 </Tip>
 
 ### CompiledSubAgent