> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy with the CLI

> Deploy a model-agnostic, open source agent to production with the Deep Agents CLI

`deepagents deploy` takes your agent configuration and files and deploys them together as a [LangSmith Deployment](/langsmith/deployment).

LangSmith Deployments are horizontally scalable servers with 30+ endpoints including MCP, A2A, Agent Protocol, human-in-the-loop, and memory APIs. Built on open standards:

* **Open source harness**: MIT licensed, available for [Python](https://github.com/langchain-ai/deepagents) and [TypeScript](https://github.com/langchain-ai/deepagentsjs)
* **[AGENTS.md](https://agents.md/)**: open standard for agent instructions
* **[Agent Skills](https://agentskills.io/)**: open standard for agent knowledge and actions
* **Any model, any sandbox**: no provider lock-in
* **Open protocols**: [MCP](https://modelcontextprotocol.io/docs/getting-started/intro), [A2A](https://a2a-protocol.org/latest/), [Agent Protocol](https://github.com/langchain-ai/agent-protocol)
* **Self-hostable**: LangSmith Deployments can be self-hosted so memory stays in your infrastructure

<Warning>
  Deep Agents Deploy is currently in beta and requires `deepagents-cli>=0.0.36`. APIs, configuration format, and behavior may change between releases. See the [releases page](https://github.com/langchain-ai/deepagents/releases) for detailed changelogs.
</Warning>

## Compare to Claude Managed Agents

|                   | Deep Agents Deploy                                                                                                                  | Claude Managed Agents      |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| Model support     | OpenAI, Anthropic, Google, Bedrock, Azure, Fireworks, Baseten, OpenRouter, [many more](/oss/python/integrations/providers/overview) | Anthropic only             |
| Harness           | Open source (MIT)                                                                                                                   | Proprietary, closed source |
| Sandbox           | LangSmith, Daytona, Modal, Runloop, or [custom](/oss/python/contributing/implement-langchain#sandboxes)                             | Built in                   |
| MCP support       | ✅                                                                                                                                   | ✅                          |
| Skill support     | ✅                                                                                                                                   | ✅                          |
| AGENTS.md support | ✅                                                                                                                                   | ❌                          |
| Agent endpoints   | MCP, A2A, Agent Protocol                                                                                                            | Proprietary                |
| Self hosting      | ✅                                                                                                                                   | ❌                          |

## Install

Install the CLI or run directly with `uvx`:

<CodeGroup>
  ```bash uv theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  uv tool install deepagents-cli
  ```

  ```bash uvx (no install) theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  uvx deepagents-cli deploy
  ```
</CodeGroup>

## Usage

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents init [name] [--force]                                             # scaffold a new project
deepagents dev  [--config deepagents.toml] [--port 2024] [--allow-blocking]  # bundle and run locally
deepagents deploy [--config deepagents.toml] [--dry-run]                     # bundle and deploy
```

By default, `deepagents deploy` looks for `deepagents.toml` in the current directory. Pass `--config` to use a different path:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents deploy --config path/to/deepagents.toml
```

`deepagents deploy` fully rebuils and creates a new revision on every invocation. Use `deepagents dev` for local iteration.

### `deepagents init`

Scaffold a new agent project:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents init my-agent
```

This creates the following files:

| File              | Purpose                                                                               |
| ----------------- | ------------------------------------------------------------------------------------- |
| `deepagents.toml` | Agent config — name, model, optional sandbox                                          |
| `AGENTS.md`       | System prompt loaded at session start                                                 |
| `.env`            | API key template (`GOOGLE_API_KEY`, `LANGSMITH_API_KEY`, etc.)                        |
| `mcp.json`        | MCP server configuration (empty by default)                                           |
| `skills/`         | Directory for [Agent Skills](https://agentskills.io/), with an example `review` skill |

After init, edit your project files and run `deepagents deploy`.

## Setup

The deploy command uses the following project layout. Place the following files alongside your `deepagents.toml` and they are automatically discovered and deployed:

```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
my-agent/
├── deepagents.toml
├── AGENTS.md
├── .env
├── mcp.json
├── skills/
│   ├── code-review/
│   │   └── SKILL.md
│   └── data-analysis/
│       └── SKILL.md
├── subagents/
│   └── researcher/
│       ├── deepagents.toml
│       └── AGENTS.md
└── user/
    └── AGENTS.md
```

| File                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`deepagents.toml`** | Required. Configures the agent's [identity](#configuration-file), [authentication](#auth), [sandbox environment](#sandbox), and the deployment of a prebuilt [frontend](#frontend) Reach chat UI.                                                                                                                                                                                                                                                                                                                                                                 |
| **`AGENTS.md`**       | Required. [Memory](/oss/python/deepagents/memory) for the agent. Provides persistent context (project conventions, instructions, preferences) that is always loaded at startup. Read-only at runtime.                                                                                                                                                                                                                                                                                                                                                             |
| **`skills/`**         | *Optional*. Directory of [skill](/oss/python/deepagents/skills) definitions that provide specialized workflows and domain knowledge. Each subdirectory should contain a `SKILL.md` file. Read-only at runtime. Dotfiles are skipped when uploading.                                                                                                                                                                                                                                                                                                               |
| **`user/`**           | *Optional*. Per-user writable memory. If an `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`). The agent can read from and write to this file. Preloaded into the agent's context via the memory middleware.                                                                                                                                                                                                                                          |
| **`mcp.json`**        | *Optional*. MCP tools (HTTP/SSE). 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. See [MCP (LangChain)](/oss/python/langchain/mcp) for more information. <Warning> `mcp.json` must only contain servers using `http` or `sse` transports. Servers using `stdio` transport are not supported in deployed environments because there is no local process to spawn. <br /><br /> Convert stdio servers to HTTP or SSE before deploying. </Warning> |
| **`subagents/`**      | *Optional*. Specialized [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.                                                                                                                                                                                                                                                                                                                                                |
| `.env`                | *Optional*. Environment variables (API keys, secrets). Placed alongside `deepagents.toml` at the project root. See [Environment variables](#environment-variables).                                                                                                                                                                                                                                                                                                                                                                                               |

## Configuration file

`deepagents.toml` configures the agent's identity and sandbox environment. Only the `[agent]` section is required. The `[sandbox]` section is optional and defaults to no sandbox.

| Field                     | Type   | Description                                                                                                 |
| ------------------------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| [`[agent]`](#agent)       | Object | Required. Core agent identity (name and model).                                                             |
| [`[sandbox]`](#sandbox)   | Object | *Optional*. Configure the isolated execution environment where the agent runs code. Defaults to no sandbox. |
| [`[auth]`](#auth)         | Object | *Optional*. Configure authentication on the deployed agent. Required when `[frontend].enabled = true`.      |
| [`[frontend]`](#frontend) | Object | *Optional*. Enable and configure the built-in chat UI frontend.                                             |

### `[agent]`

Configure the core agent identity:

```toml deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[agent]
name = "research-assistant"
description = "Researches market trends, competitors, and target audiences"
model = "google_genai:gemini-3.1-pro-preview"
```

| Field         | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | `string` | Required. Name for the deployed agent. Used as the assistant identifier in LangSmith.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `description` | `string` | *Optional*. Human-readable description of what the agent does.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `model`       | `string` | *Optional*. Model identifier in `provider:model` format. See [supported models](/oss/python/deepagents/models#supported-models). The `provider:` prefix in the `model` field determines the required `langchain-*` package (e.g., `google_genai` -> `langchain-google-genai`) which is automatically included in the deployment. This includes models specified in subagent configs. Defaults to a credential-based model if omitted (tries `openai:gpt-5.2`, then `anthropic:claude-sonnet-4-6`, then `google_genai:gemini-3.1-pro-preview`, then `google_vertexai:gemini-3.1-pro-preview`, then `nvidia:nvidia/nemotron-3-super-120b-a12b`). |

### `[sandbox]`

Configure the isolated execution environment where the agent runs code. Sandboxes provide a container with a filesystem and shell access, so untrusted code cannot affect the host. For supported providers and advanced sandbox configuration, see [sandboxes](/oss/python/deepagents/sandboxes).

```toml deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[sandbox]
provider = "langsmith"
template = "coding-agent"
image = "python:3.12"
```

| Field      | Type     | Description                                                                                                                                                                                                                                                                                                                                                                            |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider` | `string` | *Optional*. Sandbox provider. Supported values: `"none"`, `"daytona"`, `"modal"`, `"runloop"`, `"langsmith"` (private beta). The relevant partner package is automatically included in the deployment. See [sandbox integrations](/oss/python/integrations/sandboxes) for provider details. Defaults to `"none"`. When omitted or set to `provider = "none"`, the sandbox is disabled. |
| `template` | `string` | *Optional*. Provider-specific template name for the sandbox environment. Defaults to `"deepagents-deploy"`.                                                                                                                                                                                                                                                                            |
| `image`    | `string` | *Optional*. Base Docker image for the sandbox container. Defaults to `"python:3"`.                                                                                                                                                                                                                                                                                                     |
| `scope`    | `string` | *Optional*. Sandbox lifecycle scope. Defaults to `"thread"`. `"thread"` creates one sandbox per conversation. `"assistant"` shares a single sandbox across all conversations for the same assistant.                                                                                                                                                                                   |

**Scope behavior:**

* `"thread"` (default): Each conversation gets its own sandbox. Different threads get different sandboxes, but the same thread reuses its sandbox across turns. Use this when each conversation should start with a clean environment.
* `"assistant"`: All conversations share one sandbox. Files, installed packages, and other state persist across conversations. Use this when the agent maintains a long-lived workspace like a cloned repo.

### `[auth]`

Add an `[auth]` section to configure authentication on the deployed agent. `[auth]` is **required** when `[frontend].enabled = true`; otherwise it is optional (without it, LangSmith Deployment's default `x-api-key` requirement applies).

```toml deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[agent]
name = "my-agent"
model = "google-genai:gemini-3.1-pro-preview"

[auth]
provider = "supabase"   # supabase | clerk | anonymous
```

| Field      | Type     | Description                                                                        |
| ---------- | -------- | ---------------------------------------------------------------------------------- |
| `provider` | `string` | Required. Auth provider. Supported values: `"supabase"`, `"clerk"`, `"anonymous"`. |

Pick one of three providers:

* **Clerk** (`[auth] provider = "clerk"`) — per-user real authentication. Each user signs in; threads and memory are scoped per user.
* **Supabase** (`[auth] provider = "supabase"`) — per-user real authentication. Same per-user scoping as Clerk.
* **Anonymous** (`[auth] provider = "anonymous"`) — the bundler ships a permissive auth handler that overrides LangSmith Deployment's default `x-api-key` requirement so the frontend can reach `/threads`, which means anyone with the deploy URL can call the API. The frontend assigns each browser a UUID cookie and filters the thread picker by it (UX-only scoping, not security). The CLI requires an interactive `y/N` confirmation before pushing.

Depending on your provider, add the following credentials to your `.env` alongside your other credentials:

| Provider    | Required env vars                                  |
| ----------- | -------------------------------------------------- |
| `supabase`  | `SUPABASE_URL`, `SUPABASE_PUBLISHABLE_DEFAULT_KEY` |
| `clerk`     | `CLERK_SECRET_KEY`                                 |
| `anonymous` | None                                               |

**Runtime behavior:**

* Unauthenticated requests return `401`.
* On success, the authenticated user's identity is injected into `config.configurable.langgraph_auth_user_id`.
* All resources (threads, runs, store) are automatically scoped per user via `metadata.owner`.
* LangSmith Studio bypasses auth for local development.

For information on how to authenticate, see [Authentication](#authentication).

### `[frontend]`

<Note>
  Frontend deployment requires `deepagents-cli>=0.0.43`.
</Note>

Optionally enable `[frontend]` to ship a prebuilt React chat UI alongside your agent on the same deployment. The frontend is mounted at `/app` on your deployment URL; your LangGraph API stays at the root (`/threads`, `/runs`, `/assistants`). The frontend provides:

* Streaming chat with the agent
* Thread picker with auto-generated titles from the first user message
* Real-time todos, files, and subagent activity panels that reflect your deep agent's live graph state
* Light/dark theme toggle that follows OS preference on first load and persists after
* (Clerk / Supabase only) Sign-in / sign-up / sign-out flows — Clerk ships its full widget (social logins, password reset); Supabase ships email/password with a built-in password reset flow

Every frontend uses one of three authentication providers — Clerk, Supabase, or anonymous (see [`[auth]`](#auth)).

```toml deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[agent]
name = "my-agent"
model = "anthropic:claude-sonnet-4-6"

[auth]
provider = "supabase"   # or "clerk"

[frontend]
enabled = true
app_name = "My Agent"
subtitle = "Your AI research assistant"
prompts = [
  "Summarize this paper",
  "Find related work",
  "Draft an outline",
]
```

| Field      | Type       | Description                                                                                                                                                                  |
| ---------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`  | `boolean`  | *Optional*. If `true`, bundle the default chat UI into the deployment. Defaults to `false`.                                                                                  |
| `app_name` | `string`   | *Optional*. Display name shown in the UI header and browser tab. Defaults to `[agent].name`.                                                                                 |
| `subtitle` | `string`   | *Optional*. Subtitle shown under the app name in the header and on the empty-state hero. Use it to describe what the agent does. Defaults to `"Your deep agent, deployed."`. |
| `prompts`  | `string[]` | *Optional*. Suggestion chips shown on the empty-state when there are no messages. Defaults to a generic research-themed set; override to tailor the chips to your agent.     |

**Environment variables:**

The frontend reuses most of what `[auth]` already requires. Only Clerk needs one additional browser-facing key.

| Provider   | Additional var                                                                             |
| ---------- | ------------------------------------------------------------------------------------------ |
| `supabase` | None — reuses `SUPABASE_URL` and `SUPABASE_PUBLISHABLE_DEFAULT_KEY` from `[auth]`          |
| `clerk`    | `CLERK_PUBLISHABLE_KEY` (browser-facing publishable key; distinct from `CLERK_SECRET_KEY`) |

**Post-deploy setup:**

After deploying, add your deployment URL to your auth provider's dashboard so auth redirects land back in the app. This is a one-time step per deployment URL.

* **Clerk:** Dashboard → your application → **Domains** → add your deployment host (e.g. `clerk-abc.us.langgraph.app`). Clerk development instances auto-whitelist localhost; production deployment URLs need explicit whitelisting.
* **Supabase:** Dashboard → **Authentication** → **URL Configuration** → add `https://<your-deployment>/app/**` to **Redirect URLs**. Without this, password-reset and email-confirmation links won't route back to your app.

## Environment variables

Place a `.env` file alongside `deepagents.toml` with your API keys:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# Required — model provider keys
ANTHROPIC_API_KEY=sk-...
OPENAI_API_KEY=sk-...
# ...etc.

# Required for deploy and LangSmith sandbox
LANGSMITH_API_KEY=lsv2_...

# Optional — sandbox provider keys
DAYTONA_API_KEY=...
MODAL_TOKEN_ID=...
MODAL_TOKEN_SECRET=...
RUNLOOP_API_KEY=...

# Required if [auth] provider = "supabase"
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_PUBLISHABLE_DEFAULT_KEY=eyJhbGc...

# Required if [auth] provider = "clerk"
CLERK_SECRET_KEY=sk_test_...

# Required if [frontend].enabled = true AND [auth] provider = "clerk"
CLERK_PUBLISHABLE_KEY=pk_test_...
```

## Authentication

The runtime auth posture depends on `[auth]`:

* **`[auth] provider = "supabase"` or `"clerk"`** — per-user real authentication. Pass the user's auth-provider token in the `Authorization` header.
* **`[auth] provider = "anonymous"`** — the bundler ships a permissive auth handler. The API is open to anyone with the deploy URL. No header required. (Required when shipping `[frontend]` without real per-user auth.)
* **No `[auth]` section** — the deploy falls back to LangSmith Deployment's default `x-api-key` requirement. Pass your LangSmith API key in the `x-api-key` header. Only valid when `[frontend].enabled` is `false` or unset.

When `[auth]` is configured for `supabase` or `clerk`, pass the token from your auth provider in the `Authorization` header:

<Tabs>
  <Tab title="curl">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    curl -X POST https://your-deployment-url/threads \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"metadata": {}}'
    ```
  </Tab>

  <Tab title="Python (langgraph-sdk)">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    from langgraph_sdk import get_client

    client = get_client(
        url="https://your-deployment-url",
        headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"},
    )

    thread = await client.threads.create()
    ```
  </Tab>
</Tabs>

| Provider | Where to get the token                                            |
| -------- | ----------------------------------------------------------------- |
| Supabase | Supabase session `access_token` from `supabase.auth.getSession()` |
| Clerk    | Clerk session token from `getToken()`                             |

Each user's threads and memory are isolated automatically—User B cannot see User A's threads.

## Deployment endpoints

The deployed server exposes:

* [**MCP**](https://modelcontextprotocol.io/docs/getting-started/intro): call your agent as a tool from other agents
* [**A2A**](https://a2a-protocol.org/latest/): multi-agent orchestration via A2A protocol
* [**Agent Protocol**](https://github.com/langchain-ai/agent-protocol): standard API for building UIs
* [**Human-in-the-loop**](/oss/python/deepagents/human-in-the-loop): approval gates for sensitive actions
* [**Memory**](/oss/python/deepagents/memory): short-term and long-term memory access

## 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:

```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
user/
└── AGENTS.md          # optional — seeded as empty if not provided
```

If the `user/` directory exists (even if empty), every user gets their own `AGENTS.md` at `/memories/user/AGENTS.md`. If you provide `user/AGENTS.md`, its contents are used as the initial template; otherwise an empty file is seeded.

At runtime, user memory is scoped per user via custom auth (`runtime.server_info.user.identity`). The first time a user interacts with the agent, their namespace is seeded with the template. Subsequent interactions reuse the existing file — the agent's edits persist, and redeployments never overwrite user data.

### How it works

1. **Bundle time** — the bundler reads `user/AGENTS.md` (or uses an empty string) and includes it in the seed payload.
2. **Runtime (first access)** — when the agent sees a `user_id` for the first time, it writes the `AGENTS.md` template to the store under that user's namespace. Existing entries are never overwritten.
3. **Preloaded** — the user `AGENTS.md` is passed to the memory middleware, so the agent sees its contents in context at the start of every conversation.
4. **Writable** — the agent can update it using the `edit_file` tool. The shared `AGENTS.md` file and skills folder are read-only.

### Permissions

| Path                            | Writable         | Scope                       |
| ------------------------------- | ---------------- | --------------------------- |
| `/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.

## 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/python/deepagents/subagents).

### Directory structure

Create a `subagents/` directory at your project root. Each subdirectory is a subagent:

```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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

```toml subagents/researcher/deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[agent]
name = "researcher"
description = "Researches market trends, competitors, and target audiences"
model = "google_genai:gemini-3.1-pro-preview"
```

| Field         | Type     | Description                                                                                                |
| ------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `name`        | `string` | Required. Unique identifier for the subagent. Must be unique across all subagents.                         |
| `description` | `string` | Required. What this subagent does. The main agent uses this to decide when to delegate. Must be non-empty. |
| `model`       | `string` | *Optional*. Model override in `provider:model` format. Omit to inherit the main agent's model.             |

### 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 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[agent]
name = "gtm-strategist"
model = "google_genai:gemini-3.1-pro-preview"
```

```toml subagents/researcher/deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[agent]
name = "researcher"
description = "Researches market trends, competitors, and target audiences to inform GTM strategy"
model = "google_genai:gemini-3.1-pro-preview"
```

```markdown subagents/researcher/AGENTS.md theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 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
```

## Limitations

* **MCP: HTTP/SSE only.** Stdio transports are rejected at bundle time.
* **No custom Python tools.** Use MCP servers to expose custom tool logic.

## Examples

A content writing agent with per-user preferences that the agent can update:

```toml deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[agent]
name = "deepagents-deploy-content-writer"
model = "google_genai:gemini-3.1-pro-preview"
```

```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
my-content-writer/
├── deepagents.toml
├── AGENTS.md
├── skills/
│   ├── blog-post/SKILL.md
│   └── social-media/SKILL.md
└── user/
    └── AGENTS.md          # writable — agent learns user preferences
```

A coding agent with a LangSmith sandbox for running code:

```toml deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[agent]
name = "deepagents-deploy-coding-agent"
model = "google_genai:gemini-3.1-pro-preview"

[sandbox]
provider = "langsmith"
template = "coding-agent"
image = "python:3.12"
```

A GTM strategy agent that delegates research to a subagent:

```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
my-gtm-agent/
├── deepagents.toml
├── AGENTS.md
├── skills/
│   └── competitor-analysis/
│       └── SKILL.md
└── subagents/
    └── market-researcher/
        ├── deepagents.toml
        ├── AGENTS.md
        └── skills/
            └── analyze-market/
                └── SKILL.md
```

A lightweight internal-demo agent with the bundled UI in anonymous mode (no signup, no infrastructure):

```toml deepagents.toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[agent]
name = "internal-demo"
model = "anthropic:claude-sonnet-4-6"

[auth]
provider = "anonymous"   # API open to anyone with the URL — confirm at deploy time

[frontend]
enabled = true
```

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/deploy.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>