Managed Deep Agents

# Managed Deep Agents

## Overview

Managed Deep Agents is an API-first hosted runtime for creating, running, and operating Deep Agents in LangSmith. It packages the operational layer around the open-source Deep Agents harness — versioned agent repo in the Context Hub, durable threads, streamed runs, managed file tree, MCP credential storage — so you don't have to stand up your own agent server.

For self-hosted deployments or full Agent Server APIs, use a standard LangSmith Deployment via [[langgraph-cli]] instead.

## When to use

Use this skill when the user wants to:
- Create or update a Managed Deep Agent (`POST` / `PATCH /v1/deepagents/agents`)
- Run an agent on a durable thread and stream the result
- Register or rotate MCP server credentials for an agent's tools
- Configure per-tool human-in-the-loop interrupts on a managed agent
- Decide between Managed Deep Agents and a self-hosted LangSmith Deployment

## Prerequisites

- A LangSmith API key for that workspace
- The HTTP client of your choice (`httpx` in Python, built-in `fetch` in JS/Node 18+)

```bash
export LANGSMITH_API_KEY="<LANGSMITH_API_KEY>"
export DEEPAGENTS_BASE_URL="https://api.smith.langchain.com/v1/deepagents"
```

All requests authenticate via the `X-Api-Key` header:

```
X-Api-Key: <LANGSMITH_API_KEY>
```

## End-to-end flow

```
1. Register MCP server(s) →  POST /v1/deepagents/mcp-servers
2. Create the agent       →  POST /v1/deepagents/agents
3. Create a thread        →  POST /v1/deepagents/threads
4. Stream a run           →  POST /v1/deepagents/threads/{thread_id}/runs/stream
5. Inspect in LangSmith   →  Traces UI
```

Each step is independent — register MCP servers once per workspace, then point any number of agents at them.

## Resource groups

| Group | Purpose |
|-------|---------|
| **Agents** (`/agents`) | Create, list, get, update (`PATCH`), and delete Managed Deep Agents. |
| **Threads** (`/threads`) | Create, search, count, and inspect durable thread state. |
| **Runs** (`/threads/{thread_id}/runs/stream`) | Start and stream runs on a thread (server-sent events). |
| **MCP servers** (`/mcp-servers`) | Register, list, rotate credentials, and delete MCP servers referenced by agent tools. |

## Agent file tree

Managed Deep Agents keeps the familiar Deep Agents project shape. Keep these in your source repo (so updates are reviewable) and submit them in `POST` / `PATCH /agents` payloads. The platform stores them as a versioned agent repo in the Context Hub, returns a `revision` on each update, and serves the tree to the agent on every run.

| File / directory | Purpose |
|------------------|---------|
| `AGENTS.md` | Agent instructions. |
| `skills/` | Skill definitions the agent can use. |
| `subagents/` | Subagent definitions for delegated work. |
| `tools.json` | Tool configuration (`tools` + `interrupt_config`). |

At runtime, the agent can read and write files — including a `/memories/` directory for durable cross-run state.

## `tools` configuration

Tools are configured with a `tools` array and an `interrupt_config` map. The same shape is used in `tools.json` and inline in agent create/update payloads:

```json
{
  "tools": [
    {
      "name": "tavily_search",
      "mcp_server_url": "https://mcp.tavily.com/mcp/",
      "mcp_server_name": "tavily",
      "display_name": "tavily_search"
    }
  ],
  "interrupt_config": {
    "https://mcp.tavily.com/mcp/::tavily-search::tavily": false
  }
}
```

- Each `tools[].mcp_server_url` must match an MCP server already registered for the workspace; credentials are attached automatically at invocation time.
- `tools[].name` is the tool name **exposed by