> ## 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 your first Managed Deep Agent with the CLI and run it with the REST API.

LangChain hosts [Managed Deep Agents](/langsmith/managed-deep-agents-overview), 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](/langsmith/managed-deep-agents-deploy).

<Note>
  Managed Deep Agents is in **private preview**, available on [LangSmith Cloud](/langsmith/cloud) in the US region only. [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](https://www.langchain.com/langsmith-managed-deep-agents-waitlist).
* A [LangSmith API key](/langsmith/create-account-api-key) for a workspace with private preview access.
* `deepagents-cli>=0.2.0`.

## Deploy your agent with the CLI

<Steps>
  <Step title="Install the CLI">
    Install `deepagents-cli` with `uv` (preferred) or `pip`:

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

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

    To upgrade an existing `uv` install, run `uv tool upgrade deepagents-cli`.
  </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">
    Generate the project files:

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

    ```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 a post-deploy health check:

    ```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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](#run-the-agent-with-the-api). To confirm the agent deployed, list the agents in your workspace:

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

## Run the agent with the API

Run a Managed Deep Agent with the [REST API](/langsmith/managed-deep-agents-api-overview). The steps below use cURL. For Python and JavaScript examples, see [Run an agent](/langsmith/managed-deep-agents-invoke).

<Steps>
  <Step title="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:

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

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

  <Step title="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
        }
      }'
    ```

    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](/langsmith/managed-deep-agents-api-overview).

    Set the returned thread ID:

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

  <Step title="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"
      }'
    ```

    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`.
  </Step>
</Steps>

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