Deploy a Managed Deep Agent - Docs by LangChain

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. 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.
`skills/`	Contains optional skills the agent can use.
`.gitignore`	Excludes local environment files.

You can also add:

File or directory	Purpose
`subagents/`	Contains subagent definitions for delegated work.
`tools.json`	Configures the MCP-backed tools the agent can call. Required if the agent uses MCP tools.

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

{
  "name": "my-agent",
  "description": "A managed deep agent.",
  "model": "anthropic:claude-sonnet-4-6",
  "backend": {
    "type": "thread_scoped_sandbox"
  }
}

Edit AGENTS.md to define the agent’s behavior. Add skills or subagents if your agent needs extra procedures or delegated workers. If your agent calls MCP tools, register the MCP server once for the workspace, then add a tools.json that references it by URL before you deploy.

Choose a backend

Managed Deep Agents projects generated by the CLI use a LangSmith sandbox backend by default:

{
  "backend": {
    "type": "thread_scoped_sandbox"
  }
}

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
`thread_scoped_sandbox`	Default. Scope LangSmith sandbox resources to each thread.
`agent_scoped_sandbox`	Scope LangSmith sandbox resources to the agent.
`default`	Use no sandbox-specific backend behavior.

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": "anthropic:claude-sonnet-4-6",
  "backend": {
    "type": "thread_scoped_sandbox"
  }
}

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)
JavaScript (fetch)
cURL

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": "anthropic:claude-sonnet-4-6",
        "backend": {"type": "thread_scoped_sandbox"},
        "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}")

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: "anthropic:claude-sonnet-4-6",
    backend: { type: "thread_scoped_sandbox" },
    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 --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": "anthropic:claude-sonnet-4-6",
    "backend": {
      "type": "thread_scoped_sandbox"
    },
    "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.

Documentation Index

​CLI: deploy from project files

​Create a project

​Choose a backend

​Deploy the project

​Update a shared agent

​API: create or update an agent

CLI: deploy from project files

Create a project

Choose a backend

Deploy the project

Update a shared agent

API: create or update an agent