Managed Deep Agents quickstart

LangChain hosts Managed Deep Agents, so you can deploy your first agent and stream a response quickly without setting up infrastructure. This quickstart uses the CLI to deploy and the REST API to run. For the full deploy workflow and all backend options, see Deploy an agent.

Managed Deep Agents is in private preview, available on LangSmith Cloud in the US region only. If you do not have access yet, join the waitlist to request it before you start.

Prerequisites

Before you start, make sure you have:

Managed Deep Agents private preview access.
A LangSmith API key for a workspace with private preview access.
deepagents-cli>=0.2.0.

Deploy your agent with the CLI

Install the CLI

Install deepagents-cli with uv (preferred) or pip:

uv tool install "deepagents-cli>=0.2.0"

To upgrade an existing uv install, run uv tool upgrade deepagents-cli.

Set your API key

Set a LangSmith API key for a workspace with private preview access:

export LANGSMITH_API_KEY="<LANGSMITH_API_KEY>"

Create a project

Generate the project files:

deepagents init my-agent
cd my-agent

The command creates agent.json, AGENTS.md, .gitignore, an empty tools.json, an example skill, and an example subagent.

Edit the agent

Edit AGENTS.md to define the agent’s behavior.The generated agent.json uses the readable local CLI format:

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

The generated project uses the default backend so it can deploy without sandbox-specific configuration. Switch to thread_scoped_sandbox or agent_scoped_sandbox when the agent needs a LangSmith sandbox for code execution, filesystem work, or long-running tasks. For options, see Choose a backend.If the agent calls MCP tools, connect tools, run deepagents mcp-servers tools <id|name|url>, then paste the generated tool entries into tools.json.

Deploy the agent

Deploy the project:

deepagents deploy

On success, the CLI prints the agent name, agent ID, short revision, agent URL, and a post-deploy 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, ...}, ...}

Save the agent_id for the run step. To confirm the agent deployed, list the agents in your workspace:

deepagents agents list

If deepagents init, deploy, agents, or mcp-servers are missing or behave unexpectedly, confirm the installed version is 0.2.0 or later with deepagents --version. An older deepagents can shadow the current release on your PATH.

Run the agent with the API

Run a Managed Deep Agent with the REST API. The steps below use cURL. For Python and JavaScript examples, see Run an agent.

Set request defaults

Reuse the LANGSMITH_API_KEY from earlier, or set it again if you opened a new shell, then set the remaining 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"
export AGENT_ID="<agent_id>"

If a request returns 401 or 403, confirm your API key belongs to a workspace with private preview access.

Create a thread

curl --request POST \
  --url "$DEEPAGENTS_BASE_URL/threads" \
  --header "X-Api-Key: $LANGSMITH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "agent_id": "'"$AGENT_ID"'",
    "options": {
      "test_run": false,
      "skip_memory_write_protection": false
    }
  }'

The options object is optional and shown here with its defaults. test_run marks the thread as a test run that is filtered out of usage and analytics. skip_memory_write_protection controls whether the runtime pauses for human approval before the agent writes to long-term memory. For the full field reference, see the API reference.Set the returned thread ID:

export THREAD_ID="<thread_id>"

Stream a run

curl --request POST \
  --url "$DEEPAGENTS_BASE_URL/threads/$THREAD_ID/runs/stream" \
  --header "X-Api-Key: $LANGSMITH_API_KEY" \
  --header 'Accept: text/event-stream' \
  --header 'Content-Type: application/json' \
  --data '{
    "agent_id": "'"$AGENT_ID"'",
    "messages": [
      {
        "role": "user",
        "content": "Research recent approaches to agent memory and summarize the main tradeoffs."
      }
    ],
    "stream_mode": ["values", "updates", "messages-tuple"],
    "stream_subgraphs": true,
    "user_timezone": "America/Los_Angeles"
  }'

The endpoint streams Server-Sent Events (text/event-stream). With the stream_mode shown, you receive incremental updates and messages-tuple events as the agent works, then a final values event that contains the run’s full state, including the agent’s response. user_timezone is optional: set it to the caller’s IANA timezone so the agent reasons about dates in local time. It defaults to the timezone configured on the agent, or UTC.

Next steps

Connect tools

Add MCP-backed tools before deploying an agent that needs external capabilities.

Deploy an agent

Learn the full CLI and REST API deploy workflow.

CLI reference

Review all commands, flags, project files, and validation rules.

API reference

Review generated endpoint reference pages and common REST commands.

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

Edit this page on GitHub or file an issue.

​Prerequisites

​Deploy your agent with the CLI

​Run the agent with the API

​Next steps

Connect tools

Deploy an agent

CLI reference

API reference

Prerequisites

Deploy your agent with the CLI

Run the agent with the API

Next steps