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

# Run a Managed Deep Agent

> Create threads and stream runs for a Managed Deep Agent.

Running a [Managed Deep Agent](/langsmith/managed-deep-agents-overview) involves creating a thread, starting a run, and streaming output. [Deploy the agent](/langsmith/managed-deep-agents-deploy) first, then invoke it with the SDKs or REST API.

For a shorter end-to-end path, see the [quickstart](/langsmith/managed-deep-agents-quickstart).

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

## Find the agent ID

Find the agent ID with the CLI or the REST API.

<Tabs>
  <Tab title="CLI">
    List agents:

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

    Inspect one agent:

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    deepagents agents get <agent_id>
    ```
  </Tab>

  <Tab title="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"
    ```

    Requests require the `X-Api-Key` header:

    ```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    X-Api-Key: <LANGSMITH_API_KEY>
    ```

    Install an HTTP client for Python examples (run this inside an activated virtual environment):

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    uv pip install httpx
    ```

    List agents with `GET /v1/deepagents/agents`, then read the `id` of the agent you want:

    <CodeGroup>
      ```python Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      import os

      import httpx

      BASE_URL = os.environ["DEEPAGENTS_BASE_URL"]
      HEADERS = {"X-Api-Key": os.environ["LANGSMITH_API_KEY"]}

      response = httpx.get(f"{BASE_URL}/agents", headers=HEADERS)
      response.raise_for_status()
      for agent in response.json()["items"]:
          print(agent["id"], agent["name"])
      ```

      ```ts JavaScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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`, { headers: HEADERS })
      if (!response.ok) throw new Error(await response.text())
      const { items } = await response.json()
      for (const agent of items) {
        console.log(agent.id, agent.name)
      }
      ```

      ```bash cURL theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      curl --request GET \
        --url "$DEEPAGENTS_BASE_URL/agents" \
        --header "X-Api-Key: $LANGSMITH_API_KEY"
      ```
    </CodeGroup>

    To inspect a single agent, call [`GET /v1/deepagents/agents/{agent_id}`](/langsmith/managed-deep-agents-api/agents/get-agent).
  </Tab>
</Tabs>

## Create threads and stream runs

You can create threads and stream runs with the SDK or REST API. Currently, there is no CLI command for running Managed Deep Agents.

Install the SDK for your runtime:

<CodeGroup>
  ```bash Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  pip install managed-deepagents
  ```

  ```bash TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  npm install @langchain/managed-deepagents
  ```
</CodeGroup>

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

The SDKs read `LANGSMITH_API_KEY` by default. REST requests require the `X-Api-Key` header:

```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
X-Api-Key: <LANGSMITH_API_KEY>
```

Export the agent ID you retrieved in the [previous section](#find-the-agent-id):

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

The examples below reuse these variables:

<Tabs>
  <Tab title="Python SDK">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    import os

    from managed_deepagents import Client

    agent_id = os.environ["AGENT_ID"]
    client = Client()
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    import { Client } from "@langchain/managed-deepagents";

    const agentId = process.env.AGENT_ID!;
    const client = new Client({
      apiKey: process.env.LANGSMITH_API_KEY,
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    # The cURL examples below reuse the shell variables exported above.
    # No additional setup is required.
    ```
  </Tab>
</Tabs>

### Create a thread

Create a thread before running the agent. Threads preserve conversation and execution state for long-running work.

The `options` object is optional, and both fields default to `false`. Set `test_run` to `true` to mark the thread as a test run that is filtered out of usage and analytics. By default, `skip_memory_write_protection` lets the runtime raise a human-in-the-loop interrupt before the agent writes to long-term memory, so you can approve or reject the write. Set it to `true` to let memory writes proceed immediately, which is useful for headless runs where no human is available to approve the write. For the full field reference, see the [API reference](/langsmith/managed-deep-agents-api-overview).

<Tabs>
  <Tab title="Python SDK">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    thread = client.threads.create(
        agent_id=agent_id,
        options={
            "test_run": False,
            "skip_memory_write_protection": False,
        },
    )
    thread_id = thread["id"]
    print(f"Thread ID: {thread_id}")
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    const thread = await client.threads.create({
      agent_id: agentId,
      options: {
        test_run: false,
        skip_memory_write_protection: false,
      },
    });
    const threadId = thread.id;
    console.log(`Thread ID: ${threadId}`);
    ```
  </Tab>

  <Tab title="cURL">
    ```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 before streaming:

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

### Stream a run from a thread

Start work on the thread and stream the result:

<Tabs>
  <Tab title="Python SDK">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    for event in client.threads.stream(
        thread_id,
        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",
    ):
        print(event.event, event.data)
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```ts theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    const langGraphClient = client.getLangGraphClient({ agentId });
    const stream = langGraphClient.runs.stream(threadId, agentId, {
      input: {
        messages: [
          {
            role: "user",
            content:
              "Research recent approaches to agent memory and summarize the main tradeoffs.",
          },
        ],
      },
      streamMode: ["values", "updates", "messages-tuple"],
      streamSubgraphs: true,
    });

    for await (const event of stream) {
      console.log(event.event, event.data);
    }
    ```
  </Tab>

  <Tab title="cURL">
    ```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"'",
        "input": {
          "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"
      }'
    ```
  </Tab>
</Tabs>

The endpoint streams Server-Sent Events (`text/event-stream`). With the stream mode (`stream_mode`, `streamMode`) shown, you receive incremental `updates` and `messages-tuple` events as the agent works, followed by a final `values` event with the run's full state, including the agent's response. Set `stream_subgraphs` (`streamSubgraphs`) to `true` to also stream events from subgraphs, such as subagents. The optional `user_timezone` sets the caller's IANA timezone so the agent reasons about dates in local time, defaulting to the agent's configured timezone or `UTC`.

The cURL example prints raw SSE lines. Parse its `data:` payloads as JSON to drive a UI. The Python and TypeScript SDK examples yield decoded events with `event.event` and `event.data`.

Choose a stream mode:

| Stream mode      | Use for                                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------------------------- |
| `values`         | Full state snapshots after steps.                                                                               |
| `updates`        | Incremental state updates as the agent works.                                                                   |
| `messages-tuple` | Token-level message output for chat UIs. Emits a `messages` event whose payload is a `[chunk, metadata]` tuple. |

### Stream with React `useStream`

The previous Python SDK and TypeScript SDK examples stream route-level events. The following React `useStream` example exposes LangGraph projections such as `stream.messages`, `stream.values`, and output state for chat UIs.

For React applications, use the TypeScript SDK's LangGraph client adapter with `@langchain/react`:

<Warning>
  Do not ship your LangSmith API key to the browser. In production React apps, route requests through your backend with a custom `fetch` instead of passing `apiKey` directly.
</Warning>

```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { Client } from "@langchain/managed-deepagents";
import { useStream } from "@langchain/react";

const agentId = "<agent_id>";

const managedDeepAgents = new Client({
  // In browser apps, prefer passing a custom fetch that calls your backend.
  apiKey: process.env.LANGSMITH_API_KEY,
});

const client = managedDeepAgents.getLangGraphClient({ agentId });

export function ManagedDeepAgentStream() {
  const stream = useStream({
    client,
    assistantId: agentId,
    fetchStateHistory: false,
  });

  return (
    <section>
      <button
        type="button"
        disabled={stream.isLoading}
        onClick={() => {
          void stream.submit({
            messages: [
              { role: "user", content: "Write a short status update." },
            ],
          });
        }}
      >
        Run agent
      </button>

      {stream.messages.map((message, index) => (
        <p key={message.id ?? index}>{String(message.content)}</p>
      ))}
    </section>
  );
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="SDK reference" icon="book" href="/langsmith/managed-deep-agents-sdk">
    SDK configuration details for the Python and TypeScript clients.
  </Card>

  <Card title="API reference" icon="api" href="/langsmith/managed-deep-agents-api-overview">
    Route-level request and response details.
  </Card>
</CardGroup>

<Note>
  If a request fails, confirm that your API key is valid, that the workspace has [private preview access](https://www.langchain.com/langsmith-managed-deep-agents-waitlist), and that you are calling the supported region. For response status codes and error shapes, see the [API reference](/langsmith/managed-deep-agents-api-overview).
</Note>

***

<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-invoke.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>