> ## 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 a Managed Deep Agent

> Create or update a Managed Deep Agent with the CLI or REST API.

Deploying a Managed Deep Agent creates or updates the hosted agent resource and syncs the managed file tree that contains instructions, skills, subagents, and tool configuration. Use the CLI for normal project-based workflows. Use the REST API when you need a custom client, automation that cannot shell out to the CLI, or direct control over request payloads.

<Note>
  Managed Deep Agents is in **private preview**, available on [LangSmith Cloud](/langsmith/cloud) in the US region only. [Join the waitlist](https://www.langchain.com/langsmith-managed-deep-agents-waitlist) to request access.
</Note>

For a shorter end-to-end path, see the [quickstart](/langsmith/managed-deep-agents-quickstart). For all commands and project file rules, see the [CLI reference](/langsmith/managed-deep-agents-cli).

## CLI: deploy from project files

The CLI scaffolds a local project, validates files, checks referenced MCP servers, and deploys the project to Managed Deep Agents.

### Create a project

Create a Managed Deep Agents project:

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

The command scaffolds:

| File or directory       | Purpose                                                                            |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `agent.json`            | Configures the managed agent name, model, backend, and optional target `agent_id`. |
| `AGENTS.md`             | Defines the agent instructions.                                                    |
| `tools.json`            | Starts empty. Add MCP-backed tools after registering an MCP server.                |
| `skills/example-skill/` | Contains an example skill you can edit, replace, or delete.                        |
| `subagents/researcher/` | Contains an example subagent you can edit, replace, or delete.                     |
| `.gitignore`            | Excludes local environment files.                                                  |

You can also add:

| File or directory   | Purpose                                                      |
| ------------------- | ------------------------------------------------------------ |
| `skills/<name>/`    | Contains additional skills the agent can use.                |
| `subagents/<name>/` | Contains additional subagent definitions for delegated work. |

The generated `agent.json` uses the readable local CLI shape:

```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "name": "my-agent",
  "description": "A managed deep agent.",
  "model": "openai:gpt-5.5",
  "backend": {
    "type": "default"
  }
}
```

Edit `AGENTS.md` to define the agent's behavior. The full project layout that deploy syncs to the managed file tree is:

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
my-agent/
  agent.json                       # Agent metadata, model, and backend
  AGENTS.md                        # Main agent instructions (system prompt)
  tools.json                       # Optional: MCP-backed tools
  skills/<name>/SKILL.md           # Optional: reusable procedures
  subagents/<name>/agent.json      # Optional: delegated worker metadata
  subagents/<name>/AGENTS.md       # Optional: delegated worker instructions
  subagents/<name>/tools.json      # Optional: subagent-scoped MCP tools
```

`deepagents init` scaffolds an empty `tools.json`, one example skill, and one example subagent so the first deploy succeeds without first registering an MCP server. Edit or remove the examples to fit your agent. Deploy reads every file in the project and syncs the tree to the Context Hub agent repo. For the complete field reference, see the [CLI reference](/langsmith/managed-deep-agents-cli#project-file-reference).

### Add MCP tools

To let the agent call MCP tools, [register the MCP server](/langsmith/managed-deep-agents-mcp) once for the workspace, then add tool entries to the project `tools.json`. Tool entries reference a registered server by URL.

After you register a server, list its tools and print a paste-ready `tools.json` snippet:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents mcp-servers tools <id|name|url>
```

The `deepagents mcp-servers add` command also tries to list tools after registration. Pass `--no-tools` when you want to skip that discovery step.

```json tools.json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "tools": [
    {
      "name": "example_tool",
      "mcp_server_url": "https://example.com/mcp",
      "mcp_server_name": "my-tools",
      "display_name": "example_tool"
    }
  ],
  "interrupt_config": {
    "https://example.com/mcp::example_tool": true
  }
}
```

Each tool requires `name` and `mcp_server_url`. The `mcp_server_name` and `display_name` fields are optional. Use the optional `interrupt_config` object to require human approval before a tool runs. Key each entry by `"{mcp_server_url}::{tool_name}"` and set it to `true`.

Deploy validates referenced MCP server URLs before sending a request. If a server URL is not registered, deploy fails with a hint to add it. For server setup and OAuth, see [Connect tools](/langsmith/managed-deep-agents-mcp).

### Add subagents

Subagents are delegated workers the main agent can call for focused tasks. Add a `subagents/` directory to the project root, then create one directory per subagent. Each subagent directory requires an `agent.json` and an `AGENTS.md`, and can include its own `tools.json` and `skills/`. The subagent name comes from its directory name.

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
my-agent/
  agent.json
  AGENTS.md
  subagents/
    researcher/
      agent.json
      AGENTS.md
      tools.json                   # Optional: subagent-scoped MCP tools
      skills/                      # Optional: subagent-local skills
```

The subagent `agent.json` supports an optional `description` and `model`:

```json subagents/researcher/agent.json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "description": "Researches a topic and returns concise findings with citations.",
  "model": "openai:gpt-5.5"
}
```

The legacy `model_id` key still works in local subagent files, but use `model` for new projects. The REST API subagent schema still uses `model_id`.

Write the subagent instructions in `subagents/researcher/AGENTS.md`:

```mdx subagents/researcher/AGENTS.md theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# Researcher

Search for sources, take notes, and return concise findings with citations.
```

To give a subagent its own MCP tools, add `subagents/researcher/tools.json` with the same shape as the project-level `tools.json`. Subagent names are checked case-insensitively for duplicates.

### Review the complete project

Tools and subagents are not configured inside `agent.json`. `agent.json` holds only agent metadata, model, and backend. Tools live in `tools.json`, and subagents live in the `subagents/` directory. A project that uses all three looks like this:

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
research-assistant/
  agent.json
  AGENTS.md
  tools.json
  subagents/
    researcher/
      agent.json
      AGENTS.md
      tools.json
```

`agent.json` stays focused on agent metadata, model, and backend:

```json agent.json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "name": "research-assistant",
  "description": "Research assistant that searches the web and delegates deep research.",
  "model": "openai:gpt-5.5",
  "backend": {
    "type": "default"
  }
}
```

`AGENTS.md` defines the main agent instructions:

```mdx AGENTS.md theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# Research assistant

You are a research assistant. Use the available tools to search for sources, and
delegate deep research to the `researcher` subagent. Return concise answers with
citations.
```

`tools.json` references the workspace MCP server the main agent calls:

```json tools.json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "tools": [
    {
      "name": "web_search",
      "mcp_server_url": "https://example.com/mcp",
      "mcp_server_name": "my-tools"
    }
  ]
}
```

`subagents/researcher/agent.json` sets the subagent metadata and model:

```json subagents/researcher/agent.json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "description": "Researches a topic and returns concise findings with citations.",
  "model": "openai:gpt-5.5"
}
```

`subagents/researcher/AGENTS.md` defines the subagent instructions:

```mdx subagents/researcher/AGENTS.md theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# Researcher

Search for sources, take notes, and return concise findings with citations.
```

`subagents/researcher/tools.json` gives the subagent its own MCP tools:

```json subagents/researcher/tools.json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "tools": [
    {
      "name": "web_search",
      "mcp_server_url": "https://example.com/mcp",
      "mcp_server_name": "my-tools"
    }
  ]
}
```

Run `deepagents deploy --dry-run` to inspect the assembled agent payload and managed file tree before you deploy.

### Choose a backend

Managed Deep Agents projects generated by the CLI use the `default` backend:

```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "backend": {
    "type": "default"
  }
}
```

Use a [LangSmith sandbox](/langsmith/sandboxes) backend when the agent needs an isolated environment for code execution, filesystem work, or long-running tasks. LangSmith manages the underlying sandbox lifecycle while the agent keeps its thread or agent scope.

| Backend type            | Use for                                           |
| ----------------------- | ------------------------------------------------- |
| `default`               | Use no sandbox-specific backend behavior.         |
| `thread_scoped_sandbox` | Scope LangSmith sandbox resources to each thread. |
| `agent_scoped_sandbox`  | Scope LangSmith sandbox resources to the agent.   |

Sandbox backends can include optional sandbox settings:

```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "backend": {
    "type": "thread_scoped_sandbox",
    "sandbox": {
      "policy_ids": ["policy-id"],
      "idle_ttl_seconds": 900,
      "delete_after_stop_seconds": 300
    }
  }
}
```

`backend.sandbox` is valid only when `backend.type` is `thread_scoped_sandbox` or `agent_scoped_sandbox`. For standalone sandbox features such as snapshots, service URLs, permissions, CLI commands, and SDK usage, see the [LangSmith sandboxes overview](/langsmith/sandboxes).

### Deploy the project

Deploy the local project:

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

The first deploy creates a Managed Deep Agent through `/v1/deepagents/agents`. Later deploys update the same remote agent by using user-local deploy state, not hidden state committed to the repository.

On success, the CLI prints the agent name, ID, short revision, the agent URL, and a post-deploy MCP health check:

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Deployed: my-agent
  agent_id: e2de7a35-9dda-462b-b982-9e57051993bc
  revision: 13ac11f1
  https://smith.langchain.com/o/-/agents/e2de7a35-9dda-462b-b982-9e57051993bc
  health:   {'agent_id': '...', 'mcp_check': {'ok': True, 'servers': [{'url': 'https://example.com/mcp', 'ok': True}]}, ...}
```

A `mcp_check.ok` value of `True` confirms the agent can reach the MCP servers its tools reference. Each deploy creates a new agent revision, even when no managed files changed, because deploy always sends a metadata update. The managed file tree itself only changes when its contents do.

Creating a Managed Deep Agent creates:

* A Managed Deep Agent resource.
* A separate LangSmith tracing project for the agent.
* A Context Hub agent repo that stores the managed file tree.

It does not create a LangSmith Deployment.

### Update a shared agent

For shared repositories or intentional updates to an existing Managed Deep Agent, declare the target visibly in `agent.json`:

```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "name": "my-agent",
  "agent_id": "agent-uuid",
  "model": "openai:gpt-5.5",
  "backend": {
    "type": "default"
  }
}
```

Then deploy:

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

On first use, the CLI asks you to confirm before updating that remote agent. To skip this, pass `--yes`:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents deploy --yes
```

Use `--dry-run` to inspect the agent payload and managed file tree before deploy:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents deploy --dry-run
```

## API: create or update an agent

Create and update payloads can use the same top-level `model` field that `deepagents init` writes to `agent.json`. Use the same `backend` object for sandbox configuration.

Set request defaults:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export LANGSMITH_API_KEY="<LANGSMITH_API_KEY>"
export LANGSMITH_API_URL="https://api.smith.langchain.com"
export DEEPAGENTS_BASE_URL="$LANGSMITH_API_URL/v1/deepagents"
```

Requests require the `X-Api-Key` header:

```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
X-Api-Key: <LANGSMITH_API_KEY>
```

Install an HTTP client for Python examples:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
uv pip install httpx
```

Create the agent with `POST /v1/deepagents/agents`:

<Tabs>
  <Tab title="Python (httpx)">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    import os

    import httpx

    BASE_URL = os.environ["DEEPAGENTS_BASE_URL"]
    HEADERS = {"X-Api-Key": os.environ["LANGSMITH_API_KEY"]}

    response = httpx.post(
        f"{BASE_URL}/agents",
        headers=HEADERS,
        json={
            "name": "research-assistant",
            "description": "Research assistant that can search the web and summarize sources.",
            "model": "openai:gpt-5.5",
            "backend": {"type": "default"},
            "instructions": (
                "You are a careful research assistant. Search for sources, "
                "keep notes, and return concise answers with citations."
            ),
        },
    )
    response.raise_for_status()
    agent_id = response.json()["id"]
    print(f"Agent ID: {agent_id}")
    ```
  </Tab>

  <Tab title="JavaScript (fetch)">
    ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    const BASE_URL = process.env.DEEPAGENTS_BASE_URL!
    const HEADERS = {
      "X-Api-Key": process.env.LANGSMITH_API_KEY!,
      "Content-Type": "application/json",
    }

    const response = await fetch(`${BASE_URL}/agents`, {
      method: "POST",
      headers: HEADERS,
      body: JSON.stringify({
        name: "research-assistant",
        description: "Research assistant that can search the web and summarize sources.",
        model: "openai:gpt-5.5",
        backend: { type: "default" },
        instructions:
          "You are a careful research assistant. Search for sources, keep notes, and return concise answers with citations.",
      }),
    })
    if (!response.ok) throw new Error(await response.text())
    const { id: agentId } = await response.json()
    console.log(`Agent ID: ${agentId}`)
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    curl --request POST \
      --url "$DEEPAGENTS_BASE_URL/agents" \
      --header "X-Api-Key: $LANGSMITH_API_KEY" \
      --header 'Content-Type: application/json' \
      --data '{
        "name": "research-assistant",
        "description": "Research assistant that can search the web and summarize sources.",
        "model": "openai:gpt-5.5",
        "backend": {
          "type": "default"
        },
        "instructions": "You are a careful research assistant. Search for sources, keep notes, and return concise answers with citations."
      }'
    ```
  </Tab>
</Tabs>

Use the agent management routes for lifecycle automation:

| Task            | Route                                                                                               |
| --------------- | --------------------------------------------------------------------------------------------------- |
| List agents     | [`GET /v1/deepagents/agents`](/langsmith/managed-deep-agents-api/agents/list-agents)                |
| Get an agent    | [`GET /v1/deepagents/agents/{agent_id}`](/langsmith/managed-deep-agents-api/agents/get-agent)       |
| Update an agent | [`PATCH /v1/deepagents/agents/{agent_id}`](/langsmith/managed-deep-agents-api/agents/update-agent)  |
| Delete an agent | [`DELETE /v1/deepagents/agents/{agent_id}`](/langsmith/managed-deep-agents-api/agents/delete-agent) |

After you create or deploy an agent, [run it](/langsmith/managed-deep-agents-invoke) by creating a thread and streaming a run.

***

<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/langsmith/managed-deep-agents-deploy.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>