Deploy a Managed Deep Agent

Create or update a Managed Deep Agent with the CLI.

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.

Use the CLI for Managed Deep Agents deploy workflows.

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 deploy workflow: project files, MCP tools, subagents, backends, shared-agent updates, and troubleshooting. 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.
• The deepagents-cli package. For install commands and version requirements, see Install the CLI 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
  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.

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.

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

Next steps

After you deploy an agent, open the printed agent URL in LangSmith to inspect managed files, revisions, traces, and runtime behavior. To add MCP tools, see Connect tools.

---

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

Edit this page on GitHub or file an issue.