Run a Managed Deep Agent - Docs by LangChain

Running a Managed Deep Agent covers creating threads, starting runs, and streaming output. Deploy the agent first with the CLI or REST API, then invoke it with the REST API.

Managed Deep Agents is in private preview. Join the waitlist to request access.

CLI: find the agent ID

There is no CLI command for running Managed Deep Agents yet. Use the CLI to find the agent ID, then use the REST API to create threads and stream runs. List agents:

deepagents agents list

Inspect one agent:

deepagents agents get <agent_id>

API: create threads and stream runs

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"
export AGENT_ID="<agent_id>"

Requests require the X-Api-Key header:

X-Api-Key: <LANGSMITH_API_KEY>

Install an HTTP client for Python examples:

uv pip install httpx

The examples below reuse these variables:

Python (httpx)
JavaScript (fetch)
cURL

import os

import httpx

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

const BASE_URL = process.env.DEEPAGENTS_BASE_URL!
const HEADERS = {
  "X-Api-Key": process.env.LANGSMITH_API_KEY!,
  "Content-Type": "application/json",
}
const agentId = process.env.AGENT_ID!

export AGENT_ID="<agent_id>"

Create a thread

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

Python (httpx)
JavaScript (fetch)
cURL

response = httpx.post(
    f"{BASE_URL}/threads",
    headers=HEADERS,
    json={
        "agent_id": agent_id,
        "options": {
            "test_run": False,
            "skip_memory_write_protection": False,
        },
    },
)
response.raise_for_status()
thread_id = response.json()["id"]
print(f"Thread ID: {thread_id}")

const response = await fetch(`${BASE_URL}/threads`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({
    agent_id: agentId,
    options: {
      test_run: false,
      skip_memory_write_protection: false,
    },
  }),
})
if (!response.ok) throw new Error(await response.text())
const { id: threadId } = await response.json()
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
    }
  }'

Stream a run from a thread

Start work on the thread with POST /v1/deepagents/threads/{thread_id}/runs/stream. Include the agent_id in the request body and set Accept: text/event-stream:

Python (httpx)
JavaScript (fetch)
cURL

payload = {
    "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",
}

with httpx.stream(
    "POST",
    f"{BASE_URL}/threads/{thread_id}/runs/stream",
    headers={**HEADERS, "Accept": "text/event-stream"},
    json=payload,
    timeout=None,
) as response:
    response.raise_for_status()
    for line in response.iter_lines():
        if line:
            print(line)

const response = await fetch(
  `${BASE_URL}/threads/${threadId}/runs/stream`,
  {
    method: "POST",
    headers: { ...HEADERS, Accept: "text/event-stream" },
    body: JSON.stringify({
      agent_id: agentId,
      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",
    }),
  }
)
if (!response.ok || !response.body) throw new Error(await response.text())

const reader = response.body.getReader()
const decoder = new TextDecoder()
while (true) {
  const { done, value } = await reader.read()
  if (done) break
  process.stdout.write(decoder.decode(value, { stream: true }))
}

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

Use stream modes based on the experience you want to build:

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.

messages-tuple mode emits a messages event. The payload is a [chunk, metadata] tuple. For route-level details, see the Managed Deep Agents 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.

Documentation Index

​CLI: find the agent ID

​API: create threads and stream runs

​Create a thread

​Stream a run from a thread

CLI: find the agent ID

API: create threads and stream runs

Create a thread

Stream a run from a thread