> ## 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 API reference > Common REST commands and generated endpoint references for Managed Deep Agents. The Managed Deep Agents API is a private preview API for creating, updating, connecting, and invoking [Managed Deep Agents](/langsmith/managed-deep-agents-overview). Use the API when you need a custom client, CLI-free automation, or direct control over request payloads. For the recommended end-to-end workflow, see the [quickstart](/langsmith/managed-deep-agents-quickstart). 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. ## Set request defaults The private preview API uses `/v1/deepagents`: ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export 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: ``` For example, list agents with the base URL and header set above: ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} 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 group | Purpose | | -------------- | -------------------------------------------------------------------------------------------- | | Agents | Create and manage Managed Deep Agent resources, including runtime and backend configuration. | | Threads | Create and manage durable thread state for Managed Deep Agents. | | Runs | Start and stream Managed Deep Agent runs on threads. | | MCP servers | Register MCP servers and store credentials referenced by agent tools. | | MCP tools | List tools exposed by a registered MCP server so clients can build `tools.json` entries. | | Auth sessions | Start 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: ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} { "backend": { "type": "default" } } ``` Use `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. Sandbox backend settings live under `backend.sandbox` and are valid only when `backend.type` is `thread_scoped_sandbox` or `agent_scoped_sandbox`: ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} { "backend": { "type": "thread_scoped_sandbox", "sandbox": { "policy_ids": ["policy-id"], "idle_ttl_seconds": 900, "delete_after_stop_seconds": 300 } } } ``` The `sandbox` object accepts: | Field | Description | | --------------------------- | --------------------------------------------------------------- | | `policy_ids` | Sandbox policy IDs to apply. | | `idle_ttl_seconds` | Idle timeout before the sandbox stops, in seconds. | | `delete_after_stop_seconds` | Delay before the sandbox is deleted after it stops, in seconds. | For backend guidance, see [Deploy an agent](/langsmith/managed-deep-agents-deploy#choose-a-backend). For standalone sandbox concepts, see the [LangSmith sandboxes overview](/langsmith/sandboxes). ## Use common REST commands ### Agents See [Deploy an agent](/langsmith/managed-deep-agents-deploy#api-create-or-update-an-agent) for the create and update workflow. For deletion behavior, see [Limits and notes](/langsmith/managed-deep-agents-overview#delete-agents). | Task | Endpoint reference | | --------------- | --------------------------------------------------------------------------------------------------- | | Create an agent | [`POST /v1/deepagents/agents`](/langsmith/managed-deep-agents-api/agents/create-agent) | | List agents | [`GET /v1/deepagents/agents`](/langsmith/managed-deep-agents-api/agents/list-agents) | | Get an agent | [`GET /v1/deepagents/agents/{agent_id}`](/langsmith/managed-deep-agents-api/agents/get-agent) | | Update an agent | [`PATCH /v1/deepagents/agents/{agent_id}`](/langsmith/managed-deep-agents-api/agents/update-agent) | | Delete an agent | [`DELETE /v1/deepagents/agents/{agent_id}`](/langsmith/managed-deep-agents-api/agents/delete-agent) | ### Threads See [Run an agent](/langsmith/managed-deep-agents-invoke#create-a-thread) for creating threads and managing the durable state they hold across runs. | Task | Endpoint reference | | --------------- | ------------------------------------------------------------------------------------------------- | | Create a thread | [`POST /v1/deepagents/threads`](/langsmith/managed-deep-agents-api/threads/create-thread) | | Search threads | [`POST /v1/deepagents/threads/search`](/langsmith/managed-deep-agents-api/threads/search-threads) | | Count threads | [`POST /v1/deepagents/threads/count`](/langsmith/managed-deep-agents-api/threads/count-threads) | | Get a thread | [`GET /v1/deepagents/threads/{thread_id}`](/langsmith/managed-deep-agents-api/threads/get-thread) | ### Runs See [Run an agent](/langsmith/managed-deep-agents-invoke#stream-a-run-from-a-thread) for starting runs on a thread and streaming their output. | Task | Endpoint reference | | -------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Start a thread run | [`POST /v1/deepagents/threads/{thread_id}/runs`](/langsmith/managed-deep-agents-api/runs/create-thread-run) | | Stream a thread run | [`POST /v1/deepagents/threads/{thread_id}/runs/stream`](/langsmith/managed-deep-agents-api/runs/stream-thread-run) | | Resolve an interrupt | [`POST /v1/deepagents/threads/{threadID}/resolve-interrupt`](/langsmith/managed-deep-agents-api/runs/resolve-interrupt) | ### MCP servers See [Connect tools](/langsmith/managed-deep-agents-mcp#connect-tools-with-the-api) for registering MCP servers and storing the credentials your agent tools use. | Task | Endpoint reference | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Create an MCP server | [`POST /v1/deepagents/mcp-servers`](/langsmith/managed-deep-agents-api/mcp-servers/create-mcp-server) | | List MCP servers | [`GET /v1/deepagents/mcp-servers`](/langsmith/managed-deep-agents-api/mcp-servers/list-mcp-servers) | | Get an MCP server | [`GET /v1/deepagents/mcp-servers/{mcp_server_id}`](/langsmith/managed-deep-agents-api/mcp-servers/get-mcp-server) | | Update an MCP server | [`PATCH /v1/deepagents/mcp-servers/{mcp_server_id}`](/langsmith/managed-deep-agents-api/mcp-servers/update-mcp-server) | | Delete an MCP server | [`DELETE /v1/deepagents/mcp-servers/{mcp_server_id}`](/langsmith/managed-deep-agents-api/mcp-servers/delete-mcp-server) | | Register an OAuth provider | [`POST /v1/deepagents/mcp-servers/{mcp_server_id}/oauth-provider`](/langsmith/managed-deep-agents-api/mcp-servers/register-oauth-provider) | ### MCP tools See [Connect tools](/langsmith/managed-deep-agents-mcp#connect-tools-with-the-api) for listing the tools a registered server exposes and building `tools.json` entries. | Task | Endpoint reference | | -------------- | --------------------------------------------------------------------------------------------- | | List MCP tools | [`GET /v1/deepagents/mcp/tools`](/langsmith/managed-deep-agents-api/mcp-tools/list-mcp-tools) | ### Auth sessions See [Connect tools](/langsmith/managed-deep-agents-mcp#connect-tools-with-the-api) for running the OAuth flow that authorizes MCP servers. | Task | Endpoint reference | | --------------------- | -------------------------------------------------------------------------------------------------------------------- | | Start an auth session | [`POST /v1/deepagents/auth-sessions`](/langsmith/managed-deep-agents-api/auth-sessions/start-auth-session) | | Get an auth session | [`GET /v1/deepagents/auth-sessions/{session_id}`](/langsmith/managed-deep-agents-api/auth-sessions/get-auth-session) | ## Paginate the agents list [`GET /v1/deepagents/agents`](/langsmith/managed-deep-agents-api/agents/list-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: ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} { "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](/langsmith/managed-deep-agents-overview#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](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers. [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/managed-deep-agents-api-overview.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).