Run a Managed Deep Agent

Running a Managed Deep Agent involves creating a thread, starting a run, and streaming output. Deploy the agent first, then invoke it with the SDKs or REST API. For a shorter end-to-end path, see the quickstart.

Managed Deep Agents is in private preview, available on LangSmith Cloud in the US region only. Join the waitlist to request access.

Find the agent ID

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

List agents:

deepagents agents list

Inspect one agent:

deepagents agents get <agent_id>

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 (run this inside an activated virtual environment):

uv pip install httpx

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

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"])

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

curl --request GET \
  --url "$DEEPAGENTS_BASE_URL/agents" \
  --header "X-Api-Key: $LANGSMITH_API_KEY"

To inspect a single agent, call GET /v1/deepagents/agents/{agent_id}.

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:

pip install managed-deepagents

npm install @langchain/managed-deepagents

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"

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

X-Api-Key: <LANGSMITH_API_KEY>

Export the agent ID you retrieved in the previous section:

export AGENT_ID="<agent_id>"

The examples below reuse these variables:

Python SDK
TypeScript SDK
cURL

import os

from managed_deepagents import Client

agent_id = os.environ["AGENT_ID"]
client = Client()

import { Client } from "@langchain/managed-deepagents";

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

# The cURL examples below reuse the shell variables exported above.
# No additional setup is required.

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.

Python SDK
TypeScript SDK
cURL

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}")

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}`);

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:

export THREAD_ID="<thread_id>"

Stream a run from a thread

Start work on the thread and stream the result:

Python SDK
TypeScript SDK
cURL

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)

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);
}

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"
  }'

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:

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.

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

SDK reference

SDK configuration details for the Python and TypeScript clients.

API reference

Route-level request and response details.

If a request fails, confirm that your API key is valid, that the workspace has private preview access, and that you are calling the supported region. For response status codes and error shapes, see the API reference.

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

Edit this page on GitHub or file an issue.

Agent server

Core capabilities

Develop agents

Deployment guides

Studio

Auth & access control

Server customization

Find the agent ID

Create threads and stream runs

Create a thread

Stream a run from a thread

Stream with React `useStream`

Next steps

SDK reference

API reference

​Find the agent ID

​Create threads and stream runs

​Create a thread

​Stream a run from a thread

​Stream with React useStream

​Next steps

SDK reference

API reference

Find the agent ID

Create threads and stream runs

Create a thread

Stream a run from a thread

Stream with React `useStream`

Next steps