> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed Deep Agents quickstart

> Deploy a first Managed Deep Agent with the CLI and run it with the REST API.

Use this quickstart to deploy a first Managed Deep Agent with the CLI, then run it with the REST API.

<Note>
  Managed Deep Agents is in private preview. [Join the waitlist](https://www.langchain.com/langsmith-managed-deep-agents-waitlist) to request access.
</Note>

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

<Note>
  The Managed Deep Agents deploy flow requires `deepagents-cli>=0.2.0`.
</Note>

## CLI: deploy a first agent

<Steps>
  <Step title="Install the CLI">
    Install or upgrade the CLI with `uv`:

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    uv tool install "deepagents-cli>=0.2.0"
    ```

    If you already installed the tool, upgrade it:

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    uv tool upgrade deepagents-cli
    ```

    As a fallback, install the CLI with `pip`:

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    pip install -U "deepagents-cli>=0.2.0"
    ```
  </Step>

  <Step title="Set your API key">
    Set a LangSmith API key for a workspace with private preview access:

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    export LANGSMITH_API_KEY="<LANGSMITH_API_KEY>"
    ```
  </Step>

  <Step title="Create a project">
    Scaffold a project:

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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.
  </Step>

  <Step title="Edit the agent">
    Edit `AGENTS.md` to define the agent's behavior.

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

    ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "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](/langsmith/sandboxes) for code execution, filesystem work, or long-running tasks. For options, see [Choose a backend](/langsmith/managed-deep-agents-deploy#choose-a-backend).

    If the agent calls MCP tools, [connect tools](/langsmith/managed-deep-agents-mcp), run `deepagents mcp-servers tools <id|name|url>`, then paste the generated tool entries into `tools.json`.
  </Step>

  <Step title="Deploy the agent">
    Deploy the project:

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    deepagents deploy
    ```

    On success, the CLI prints the agent name, agent ID, short revision, agent URL, and deploy health check. Save the `agent_id` for the run step.
  </Step>
</Steps>

<Note>
  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`.
</Note>

## API: run the agent

Running a Managed Deep Agent is currently available through the REST API. Set request defaults:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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>"
```

Create a thread:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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
    }
  }'
```

Set the returned thread ID:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export THREAD_ID="<thread_id>"
```

Stream a run:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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"
  }'
```

For Python and JavaScript examples, see [Run an agent](/langsmith/managed-deep-agents-invoke).

## Next steps

<CardGroup cols={2}>
  <Card title="Connect tools" icon="plug" href="/langsmith/managed-deep-agents-mcp">
    Add MCP-backed tools before deploying an agent that needs external capabilities.
  </Card>

  <Card title="Deploy an agent" icon="upload" href="/langsmith/managed-deep-agents-deploy">
    Learn the full CLI and REST API deploy workflow.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/langsmith/managed-deep-agents-cli">
    Review all commands, flags, project files, and validation rules.
  </Card>

  <Card title="API reference" icon="api" href="/langsmith/managed-deep-agents-api">
    Review generated endpoint reference pages and common REST commands.
  </Card>
</CardGroup>

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/managed-deep-agents-quickstart.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>