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.

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

For a shorter end-to-end path, see the quickstart. For all commands and project file rules, see the CLI reference.

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:

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:

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

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.

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"
}

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:

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

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": "default"
  }
}

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"
    }
  ]
}

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:

{
  "backend": {
    "type": "default"
  }
}

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

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

Deploy the project

Deploy the local project:

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:

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:

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

Then deploy:

deepagents deploy

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

deepagents deploy --yes

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

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:

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:

X-Api-Key: <LANGSMITH_API_KEY>

Install an HTTP client for Python examples:

uv pip install httpx

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

Python (httpx)

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}")

JavaScript (fetch)

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}`)

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.",
    "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."
  }'

Use the agent management routes for lifecycle automation:

Task	Route
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}

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.