Skip to main content
The Managed Deep Agents API is a private preview API for creating, updating, connecting, and invoking Managed Deep Agents. Use the API when you need a custom client, CLI-free automation, or direct control over request payloads.
Managed Deep Agents is in &private preview. Join the waitlist to request access. For the recommended end-to-end workflow, see the quickstart.

​
Set request defaults

The private preview API uses /v1/deepagents: 
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>
For example, list agents with the base URL and header set above: 
curl "$DEEPAGENTS_BASE_URL/agents" \
  -H "X-Api-Key: $LANGSMITH_API_KEY"
A missing X-Api-Key header returns 401 with {"error": "Unauthorized"}. A key that is invalid or lacks workspace access returns 403 with {"error": "Forbidden"}. These auth responses use a flat {"error": "..."} body, unlike the structured error body returned by other 4xx responses.

​
Understand resource groups

Resource groupPurpose
AgentsCreate and manage Managed Deep Agent resources, including runtime and backend configuration.
ThreadsCreate and manage durable thread state for Managed Deep Agents.
RunsStart and stream Managed Deep Agent runs on threads.
MCP serversRegister MCP servers and store credentials referenced by agent tools.
MCP toolsList tools exposed by a registered MCP server so clients can build tools.json entries.
Auth sessionsStart and poll user OAuth sessions for OAuth MCP servers.
Managed Deep Agents are not LangSmith Deployments. Creating a Managed Deep Agent creates a Managed Deep Agent resource, a separate LangSmith tracing project, and a Context Hub agent repo for the managed file tree.

​
Configure sandboxes

Create-agent and update-agent payloads can include a backend object. Use default when the agent does not need sandbox-specific backend behavior: 
{
  "backend": {
    "type": "default"
  }
}
Use thread_scoped_sandbox or agent_scoped_sandbox when the agent needs a LangSmith sandbox for code execution, filesystem work, or long-running tasks. Sandbox backend settings live under backend.sandbox and are valid only when backend.type is thread_scoped_sandbox or agent_scoped_sandbox: 
{
  "backend": {
    "type": "thread_scoped_sandbox",
    "sandbox": {
      "policy_ids": ["policy-id"],
      "idle_ttl_seconds": 900,
      "delete_after_stop_seconds": 300
    }
  }
}
The sandbox object accepts:
FieldDescription
policy_idsSandbox policy IDs to apply.
idle_ttl_secondsIdle timeout before the sandbox stops, in seconds.
delete_after_stop_secondsDelay before the sandbox is deleted after it stops, in seconds.
For backend guidance, see Deploy an agent. For standalone sandbox concepts, see the LangSmith sandboxes overview.

​
Use common REST commands

​
Agents

See Deploy an agent for the create and update workflow. For deletion behavior, see Limits and notes.
TaskEndpoint reference
Create an agentPOST /v1/deepagents/agents
List agentsGET /v1/deepagents/agents
Get an agentGET /v1/deepagents/agents/{agent_id}
Update an agentPATCH /v1/deepagents/agents/{agent_id}
Delete an agentDELETE /v1/deepagents/agents/{agent_id}

​
Threads

See Run an agent for creating threads and managing the durable state they hold across runs.
TaskEndpoint reference
Create a threadPOST /v1/deepagents/threads
Search threadsPOST /v1/deepagents/threads/search
Count threadsPOST /v1/deepagents/threads/count
Get a threadGET /v1/deepagents/threads/{thread_id}

​
Runs

See Run an agent for starting runs on a thread and streaming their output.
TaskEndpoint reference
Start a thread runPOST /v1/deepagents/threads/{thread_id}/runs
Stream a thread runPOST /v1/deepagents/threads/{thread_id}/runs/stream
Resolve an interruptPOST /v1/deepagents/threads/{threadID}/resolve-interrupt

​
MCP servers

See Connect tools for registering MCP servers and storing the credentials your agent tools use.
TaskEndpoint reference
Create an MCP serverPOST /v1/deepagents/mcp-servers
List MCP serversGET /v1/deepagents/mcp-servers
Get an MCP serverGET /v1/deepagents/mcp-servers/{mcp_server_id}
Update an MCP serverPATCH /v1/deepagents/mcp-servers/{mcp_server_id}
Delete an MCP serverDELETE /v1/deepagents/mcp-servers/{mcp_server_id}
Register an OAuth providerPOST /v1/deepagents/mcp-servers/{mcp_server_id}/oauth-provider

​
MCP tools

See Connect tools for listing the tools a registered server exposes and building tools.json entries.
TaskEndpoint reference
List MCP toolsGET /v1/deepagents/mcp/tools

​
Auth sessions

See Connect tools for running the OAuth flow that authorizes MCP servers.
TaskEndpoint reference
Start an auth sessionPOST /v1/deepagents/auth-sessions
Get an auth sessionGET /v1/deepagents/auth-sessions/{session_id}

​
Paginate the agents list

GET /v1/deepagents/agents is cursor-paginated. Pass page_size (defaults to 20, maximum 100) and the opaque cursor returned by a previous request. The response wraps results in an items array alongside a next_cursor field that is null on the last page: 
{
  "items": [],
  "next_cursor": null
}
The endpoint also accepts name to filter by name substring, sort_by (created_at, updated_at, or name, defaults to updated_at), and sort_order (asc or desc, defaults to desc).

​
Understand API stability

Routes are versioned at /v1/, but the surface is in private preview and may change in backwards-incompatible ways before general availability. See API stability for breaking-change communication. The API does not mirror every LangSmith Deployment endpoint in private preview. Endpoint groups such as integrations, triggers, skills, sandboxes, auth providers, and auth tokens are not mirrored yet.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.