managed-deep-agents

What this skill does

# Managed Deep Agents

## Overview

Managed Deep Agents is a hosted runtime for creating, running, and operating Deep Agents in LangSmith. It packages the operational layer around the open-source Deep Agents harness: a versioned Context Hub agent repo, durable threads, streamed runs, MCP credential storage, managed files, and optional LangSmith sandboxes.

Use the Managed Deep Agents path when the user wants LangSmith to host and operate the agent. For self-hosted deployments, custom application routes, or the full Agent Server API surface, use a standard LangSmith Deployment via [[langgraph-cli]] instead.

## When to use

Use this skill when the user wants to:

- Deploy a Managed Deep Agent from local project files.
- Create or update a Managed Deep Agent from Python, TypeScript, or REST.
- Run an agent on a durable thread and stream output.
- Build a React chat UI with `@langchain/react` `useStream`.
- Register MCP servers, list MCP tools, or configure tool interrupts.
- Choose between Managed Deep Agents and a self-hosted LangSmith Deployment.

## Prerequisites

- Managed Deep Agents preview access in the target LangSmith workspace.
- A LangSmith API key for that workspace.
- One of the supported clients:

```bash
uv tool install "deepagents-cli>=0.2.2"
pip install managed-deepagents
npm install @langchain/managed-deepagents @langchain/react
```

Set the API key in the shell or server environment:

```bash
export LANGSMITH_API_KEY="<LANGSMITH_API_KEY>"
```

The SDKs default to `https://api.smith.langchain.com/v1/deepagents`. To use a different compatible endpoint, set `LANGSMITH_ENDPOINT` or pass `api_url` / `apiUrl` in the client.

For direct REST examples, set:

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

All REST requests authenticate with:

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

Never expose a long-lived LangSmith API key in browser code. For browser apps, route requests through your own backend or provide a custom `fetch` implementation that proxies requests server-side.

## Choose an interface

| Interface | Use for |
| --- | --- |
| `deepagents-cli>=0.2.2` | Normal project-file workflow: scaffold, edit files, deploy, manage MCP servers. |
| Python SDK `managed-deepagents` | Server-side Python automation, tests, scripts, services, and streaming. |
| TypeScript SDK `@langchain/managed-deepagents` | Server-side TypeScript automation and LangGraph-compatible streaming. |
| React `useStream` | Chat UIs that should let LangGraph own thread/run/projection state. |
| REST `/v1/deepagents` | Low-level fallback when a client does not expose a field yet. |

Prefer the CLI for local agent projects. Prefer the SDKs for application code. Use REST only when you need exact request control.

## Resource groups

| Group | Purpose |
| --- | --- |
| Agents | Create, list, get, update, clone, delete, and health-check Managed Deep Agents. |
| Threads | Create, list, search, count, inspect, update, and delete durable thread state. |
| Runs | Start and stream runs on a thread. |
| MCP servers | Register, list, update, delete, and connect MCP servers. |
| MCP tools | List tools exposed by a registered MCP server for `tools.json`. |
| Auth sessions | Start and inspect OAuth authorization sessions. |

## Project file tree

The CLI uses a local project directory and deploys it into the managed Context Hub agent repo.

```text
my-agent/
  agent.json
  AGENTS.md
  tools.json
  skills/<name>/SKILL.md
  subagents/<name>/agent.json
  subagents/<name>/AGENTS.md
  subagents/<name>/tools.json
```

| File / directory | Purpose |
| --- | --- |
| `agent.json` | Agent name, description, model, backend, permissions, and optional target `agent_id`. |
| `AGENTS.md` | Main agent instructions. |
| `tools.json` | MCP-backed tools plus `interrupt_config`. |
| `skills/` | Reusable instructions and files the agent can load. |
| `subagents/` | Delegated worker definitions and optional subagent-scoped tools. |

At runtime, the agent can read and write managed files, including memory files created by the Deep Agents harness.

## Backends

New projects should use the canonical backend names from `deepagents-cli>=0.2.2`.

Use `state` when the agent does not need sandbox-specific backend behavior:

```json
{
  "backend": {
    "type": "state"
  }
}
```

Use `sandbox` when the agent needs a LangSmith sandbox for code execution, filesystem work, or long-running tasks:

```json
{
  "backend": {
    "type": "sandbox",
    "sandbox_config": {
      "scope": "thread",
      "policy_ids": ["policy-id"],
      "idle_ttl_seconds": 900,
      "delete_after_stop_seconds": 300
    }
  }
}
```

`sandbox_config.scope` must be `thread` or `agent`.

## CLI workflow

Use the CLI for most deploy workflows.

```bash
deepagents init research-assistant
cd research-assistant
```

Edit `agent.json`:

```json
{
  "name": "research-assistant",
  "description": "Research assistant that can search the web and summarize sources.",
  "model": "openai:gpt-5.5",
  "backend": {
    "type": "state"
  }
}
```

Edit `AGENTS.md` with the main instructions, then deploy:

```bash
deepagents deploy
```

Useful CLI commands:

| Command | Use |
| --- | --- |
| `deepagents --version` | Confirm `deepagents-cli>=0.2.2`. |
| `deepagents deploy --dry-run` | Print the agent payload and managed file tree without deploying. |
| `deepagents agents list` | List Managed Deep Agents in the workspace. |
| `deepagents agents get <agent_id> --include-files` | Inspect an agent and its managed files. |
| `deepagents mcp-servers add --url URL --name NAME` | Register a static-header MCP server. |
| `deepagents mcp-servers add --url URL --auth-type oauth --connect` | Register and connect an OAuth MCP server. |
| `deepagents mcp-servers tools <id|name|url>` | List tools and print a paste-ready `tools.json` snippet. |
| `deepagents mcp-servers connect <id|name|url>` | Complete OAuth for a registered OAuth MCP server. |

For shared repositories, put the target `agent_id` in `agent.json`; the CLI asks for confirmation before updating that remote agent. Use `--yes` only when the target is intentional.

## MCP tools

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

```json
{
  "tools": [
    {
      "name": "read_url_content",
      "mcp_server_url": "https://example.com/mcp",
      "mcp_server_name": "my-tools",
      "display_name": "read_url_content"
    }
  ],
  "interrupt_config": {
    "https://example.com/mcp::read_url_content": false
  }
}
```

- `tools[].mcp_server_url` must match a registered workspace MCP server URL.
- `tools[].name` is the tool name exposed by the MCP server, not the workspace MCP-server display name.
- Use `deepagents mcp-servers tools <server>` or the SDK tool-listing methods to confirm exact tool names.
- `interrupt_config` keys use `{mcp_server_url}::{tool_name}`. Additional `::` parts are accepted for compatibility, but do not rely on them for new configs.
- Set the interrupt value to `true` to require human approval before the tool runs.

Python SDK tool listing:

```python
from managed_deepagents import Client

with Client() as client:
    tools = client.mcp_servers.list_tools(
        url="https://example.com/mcp",
        force_refresh=True,
    )
    print(tools["tools"])
```

TypeScript SDK tool listing:

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

const client = new Client({ apiKey: process.env.LANGSMITH_API_KEY });
const tools = await client.mcpServers.listTools({
  url: "https://example.com/mcp",
  forceRefresh: true,
});
console.log(tools.tools);
```

## Python SDK workflow

Use the Python SDK for server-side automation and streaming.

```python
from managed_deepagents import Client

with Client() as client:
    agent = client.agents.create(
        name="research-assistant",
        description="Research assistant that can search the web