Deploy a Managed Deep Agent

Create or update a Managed Deep Agent with the CLI, SDK, 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. A deploy does not create a LangSmith Deployment. For more information on what a deploy does create, refer to Created resources.

Choose the interface that fits your task:

• CLI for most setups.
• SDKs for Python or TypeScript automation.
• REST API when you need direct control over request payloads.

Managed Deep Agents is in private beta, available on LangSmith Cloud in the US region only. Join the waitlist to request access.

This page covers the full deploy workflow: project files, MCP tools, subagents, backends, shared-agent updates, and the REST API. For a faster, guided setup, see the quickstart.

Prerequisites

Before you deploy, make sure you have:

• Managed Deep Agents private beta access.
• A LangSmith API key for a workspace with private beta access, exported as LANGSMITH_API_KEY.
• A client for your interface: deepagents-cli for the CLI, the managed-deepagents (Python) or @langchain/managed-deepagents (TypeScript) SDK for SDK workflows, or an HTTP client such as curl for the REST API. For install commands and version requirements, see Install a client in the quickstart.

Deploy from project files with the CLI

The CLI creates a local project, validates files, checks referenced MCP servers, and deploys the project to Managed Deep Agents. For all commands and project file rules, see the CLI reference.

Create a project

Create a Managed Deep Agents project:

deepagents init my-agent
cd my-agent

The command generates:

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 or remove.
subagents/researcher/	Contains an example subagent you can edit or remove.
.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 format:

agent.json

{
  "name": "my-agent",
  "description": "A managed deep agent.",
  "model": "openai:gpt-5.5",
  "backend": {
    "type": "state"
  }
}

Model identifiers use the {provider}:{model_id} form. For the providers and models you can use, see Supported models.

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

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 generates an empty tools.json, one example skill, and one example subagent so the initial deploy succeeds before you register 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.

Add MCP tools

To let the agent call MCP tools, register the MCP server 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:

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.

tools.json

{
  "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.

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.

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:

subagents/researcher/agent.json

{
  "description": "Researches a topic and returns concise findings with citations.",
  "model": "openai:gpt-5.5"
}

Use model for new projects. For compatibility, the legacy model_id key still works in local subagent files, and the REST API subagent schema still uses model_id.

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

subagents/researcher/AGENTS.md

# 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 live outside agent.json: tools in tools.json, subagents in the subagents/ directory. A project that uses all three looks like this:

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:

agent.json

{
  "name": "research-assistant",
  "description": "Research assistant that searches the web and delegates deep research.",
  "model": "openai:gpt-5.5",
  "backend": {
    "type": "state"
  }
}

AGENTS.md defines the main agent instructions:

AGENTS.md

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

tools.json

{
  "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:

subagents/researcher/agent.json

{
  "description": "Researches a topic and returns concise findings with citations.",
  "model": "openai:gpt-5.5"
}

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

subagents/researcher/AGENTS.md

# Researcher

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

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

subagents/researcher/tools.json

{
  "tools": [
    {
      "name": "web_search",
      "mcp_server_url": "https://example.com/mcp",
      "mcp_server_name": "my-tools"
    }
  ]
}

Choose a backend

Managed Deep Agents projects generated by the CLI use the state backend in agent.json:

agent.json

{
  "backend": {
    "type": "state"
  }
}

Use a LangSmith sandbox 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
state	Use no sandbox-specific backend behavior.
sandbox with sandbox_config.scope: "thread"	Scope LangSmith sandbox resources to each thread.
sandbox with sandbox_config.scope: "agent"	Scope LangSmith sandbox resources to the agent.

Add optional sandbox settings under backend in agent.json:

agent.json

{
  "backend": {
    "type": "sandbox",
    "sandbox_config": {
      "scope": "thread",
      "policy_ids": ["policy-id"],
      "idle_ttl_seconds": 900,
      "delete_after_stop_seconds": 300
    }
  }
}

backend.sandbox_config is valid only when backend.type is sandbox. For standalone sandbox features such as snapshots, service URLs, permissions, CLI commands, and SDK usage, see the LangSmith sandboxes overview.

Deploy the project

Deploy the local project:

deepagents deploy

To preview the assembled payload and managed file tree before deploying, run deepagents deploy --dry-run.

The first deploy creates a Managed Deep Agent through /v1/deepagents/agents. Later deploys update the same remote agent using local deploy state.

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

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}]}, ...}

The health output above is abbreviated; it includes the full mcp_check result for every referenced server. 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.

Update a shared agent

For shared repositories or intentional updates to an existing Managed Deep Agent, set the target agent’s agent_id in agent.json:

agent.json

{
  "name": "my-agent",
  "agent_id": "agent-uuid",
  "model": "openai:gpt-5.5",
  "backend": {
    "type": "state"
  }
}

Then deploy:

deepagents deploy

Deploying with agent_id set updates an existing shared agent in place.

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

deepagents deploy --yes

Troubleshoot a deploy

Symptom	Cause and fix
Deploy fails with an unregistered MCP server URL	A tool in tools.json references a server that is not registered for the workspace. Register the server, then deploy again.
mcp_check.ok is False in the deploy output	The agent cannot reach one or more referenced MCP servers. Find the failing URL under servers, confirm the server is running and reachable, then deploy again.
Deploy prompts to confirm an update you did not expect	agent.json declares an agent_id that targets an existing remote agent. Confirm the target before continuing, or remove agent_id to create a new agent.
Deploy fails with 401 or 403	The LANGSMITH_API_KEY is missing, invalid, or belongs to a workspace without private beta access. Check the key and confirm the workspace has access.

Create or update an agent with the SDK or API

Map project files to the SDK or API field

The create and update payloads accept the same project structure the CLI syncs. Each typed field maps to a managed file:

SDK or API field	Managed file
name description model(SDK) runtime.model.model_id(API) backend	agent.json
instructions	AGENTS.md
tools	tools.json
subagents[]	subagents/<name>/AGENTS.md and optional subagents/<name>/tools.json
skills[]	skills/<name>/SKILL.md and supporting files
files	Any path not covered by a typed field

Setting both a typed field and a files entry for the same path returns 422 (for example, instructions and files["AGENTS.md"]). Use one or the other for a given file. For the full request schema, see the update agent reference.

On update, omitted fields are left unchanged. Nested structured fields such as tools, subagents, skills, and extras are replaced in full when you include them.

Authenticate and configure requests

For SDK usage, install and configure the Managed Deep Agents SDKs. For direct REST API calls, set request defaults:

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"

API requests require the X-Api-Key header:

X-Api-Key: <LANGSMITH_API_KEY>

The Python SDK reads LANGSMITH_API_KEY from the environment. The TypeScript SDK takes an explicit apiKey.

Create an agent

Create the agent with the same instructions, tools, skills, and subagents the CLI keeps in project files:

The REST API nests the model under runtime.model.model_id. The SDK and CLI use a top-level model field.

Python SDK

from managed_deepagents import Client

with Client() as client:
    agent = client.agents.create(
        name="research-assistant",
        description="Research assistant that can search the web and summarize sources.",
        model="openai:gpt-5.5",
        backend={"type": "state"},
        instructions=(
            "You are a careful research assistant. Search for sources, "
            "keep notes, and return concise answers with citations."
        ),
        tools={
            "tools": [
                {
                    "name": "read_url_content",
                    "mcp_server_url": "https://example.com/mcp",
                    "mcp_server_name": "my-tools",
                }
            ],
            "interrupt_config": {
                "https://example.com/mcp::read_url_content": True,
            },
        },
        skills=[
            {
                "name": "summarize",
                "description": "Summarize long source documents.",
                "instructions": (
                    "# Summarize\n\n"
                    "Extract the main claims, supporting evidence, and open questions."
                ),
            }
        ],
        subagents=[
            {
                "name": "source-checker",
                "description": "Verify facts and source quality.",
                "model_id": "openai:gpt-5.5",
                "instructions": (
                    "Check whether cited sources support the draft answer. "
                    "Return a concise risk assessment."
                ),
            }
        ],
        include_files=True,
    )

agent_id = agent["id"]
print(f"Agent ID: {agent_id}")

The call returns the created agent. Pass include_files=True to also return the managed file tree.

TypeScript SDK

import { Client } from "@langchain/managed-deepagents";

const client = new Client();

const agent = await client.agents.create(
  {
    name: "research-assistant",
    description: "Research assistant that can search the web and summarize sources.",
    model: "openai:gpt-5.5",
    backend: { type: "state" },
    instructions:
      "You are a careful research assistant. Search for sources, keep notes, and return concise answers with citations.",
    tools: {
      tools: [
        {
          name: "read_url_content",
          mcp_server_url: "https://example.com/mcp",
          mcp_server_name: "my-tools",
        },
      ],
      interrupt_config: {
        "https://example.com/mcp::read_url_content": true,
      },
    },
    skills: [
      {
        name: "summarize",
        description: "Summarize long source documents.",
        instructions:
          "# Summarize\n\nExtract the main claims, supporting evidence, and open questions.",
      },
    ],
    subagents: [
      {
        name: "source-checker",
        description: "Verify facts and source quality.",
        model_id: "openai:gpt-5.5",
        instructions:
          "Check whether cited sources support the draft answer. Return a concise risk assessment.",
      },
    ],
  },
  { includeFiles: true },
);

console.log(`Agent ID: ${agent.id}`);

The call returns the created agent. Pass { includeFiles: true } to also return the managed file tree.

cURL

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.",
    "runtime": {
      "model": {
        "model_id": "openai:gpt-5.5"
      }
    },
    "backend": {
      "type": "state"
    },
    "instructions": "You are a careful research assistant. Search for sources, keep notes, and return concise answers with citations.",
    "tools": {
      "tools": [
        {
          "name": "read_url_content",
          "mcp_server_url": "https://example.com/mcp",
          "mcp_server_name": "my-tools"
        }
      ],
      "interrupt_config": {
        "https://example.com/mcp::read_url_content": true
      }
    },
    "skills": [
      {
        "name": "summarize",
        "description": "Summarize long source documents.",
        "instructions": "# Summarize\n\nExtract the main claims, supporting evidence, and open questions."
      }
    ],
    "subagents": [
      {
        "name": "source-checker",
        "description": "Verify facts and source quality.",
        "model_id": "openai:gpt-5.5",
        "instructions": "Check whether cited sources support the draft answer. Return a concise risk assessment."
      }
    ]
  }'

Update an existing agent

When you update an agent, include only the fields you want to change. Replace <agent_id> with the ID returned when you created the agent:

Python SDK

from managed_deepagents import Client

agent_id = "<agent_id>"

with Client() as client:
    agent = client.agents.update(
        agent_id,
        description="Research assistant with stricter citation rules.",
        instructions=(
            "You are a careful research assistant. Search for sources, "
            "keep notes, and cite every factual claim."
        ),
        tools={
            "tools": [
                {
                    "name": "read_url_content",
                    "mcp_server_url": "https://example.com/mcp",
                    "mcp_server_name": "my-tools",
                }
            ],
            "interrupt_config": {
                "https://example.com/mcp::read_url_content": True,
            },
        },
        include_files=True,
    )

print(agent.get("revision"))

TypeScript SDK

import { Client } from "@langchain/managed-deepagents";

const client = new Client();

const agentId = "<agent_id>";

const agent = await client.agents.update(
  agentId,
  {
    description: "Research assistant with stricter citation rules.",
    instructions:
      "You are a careful research assistant. Search for sources, keep notes, and cite every factual claim.",
    tools: {
      tools: [
        {
          name: "read_url_content",
          mcp_server_url: "https://example.com/mcp",
          mcp_server_name: "my-tools",
        },
      ],
      interrupt_config: {
        "https://example.com/mcp::read_url_content": true,
      },
    },
  },
  { includeFiles: true },
);

console.log(agent.revision);

cURL

curl --request PATCH \
  --url "$DEEPAGENTS_BASE_URL/agents/<agent_id>?include_files=true" \
  --header "X-Api-Key: $LANGSMITH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "Research assistant with stricter citation rules.",
    "instructions": "You are a careful research assistant. Search for sources, keep notes, and cite every factual claim.",
    "tools": {
      "tools": [
        {
          "name": "read_url_content",
          "mcp_server_url": "https://example.com/mcp",
          "mcp_server_name": "my-tools"
        }
      ],
      "interrupt_config": {
        "https://example.com/mcp::read_url_content": true
      }
    }
  }'

To remove raw managed files during an update, send deleted_paths, an array of relative file paths (for example, ["docs/old-notes.md"]). To remove a structured section such as all skills or subagents, send the field with an empty list.

Add raw managed files

Use top-level files for content that does not map cleanly to instructions, tools, skills, or subagents:

Python SDK

from managed_deepagents import Client

with Client() as client:
    agent = client.agents.update(
        "<agent_id>",
        files={
            "docs/research-style.md": "Prefer primary sources and note uncertainty.",
            "data/glossary.md": {"content": "# Glossary\n\nDefine domain terms here."},
        },
        include_files=True,
    )

TypeScript SDK

import { Client } from "@langchain/managed-deepagents";

const client = new Client();

const agent = await client.agents.update(
  "<agent_id>",
  {
    files: {
      "docs/research-style.md": "Prefer primary sources and note uncertainty.",
      "data/glossary.md": { content: "# Glossary\n\nDefine domain terms here." },
    },
  },
  { includeFiles: true },
);

cURL

curl --request PATCH \
  --url "$DEEPAGENTS_BASE_URL/agents/<agent_id>?include_files=true" \
  --header "X-Api-Key: $LANGSMITH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "files": {
      "docs/research-style.md": {
        "content": "Prefer primary sources and note uncertainty."
      },
      "data/glossary.md": {
        "content": "# Glossary\n\nDefine domain terms here."
      }
    }
  }'

Check agent health

After create or update, check the agent’s backend and tool health with the SDK or API:

Python SDK

from managed_deepagents import Client

with Client() as client:
    health = client.agents.health("<agent_id>")

print(health)

TypeScript SDK

import { Client } from "@langchain/managed-deepagents";

const client = new Client();

const health = await client.agents.health("<agent_id>");

// JSON.stringify (not console.log(health)) so nested objects print in full:
// console.log uses util.inspect with depth 2, which collapses deeper values to
// "[Object]" — e.g. the entries inside mcp_check.servers.
console.log(JSON.stringify(health, null, 2));

cURL

curl --url "$DEEPAGENTS_BASE_URL/agents/<agent_id>/health" \
  --header "X-Api-Key: $LANGSMITH_API_KEY"

The result uses the same mcp_check shape shown in the deploy output.

Manage the agent lifecycle with the API

Use the agent management routes for lifecycle automation:

Task	Route
Create an agent	POST /v1/deepagents/agents
List agents	GET /v1/deepagents/agents
Get an agent	GET /v1/deepagents/agents/{agent_id}
Update an agent	PATCH /v1/deepagents/agents/{agent_id}
Delete an agent	DELETE /v1/deepagents/agents/{agent_id}

Next steps

After you create or deploy an agent, run it by creating a thread and streaming a run.

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.