Managed Deep Agents CLI reference

The deepagents CLI provides deployment tooling for Managed Deep Agents. Use it to scaffold local agent projects, deploy them to LangSmith, manage Managed Deep Agent resources, and register MCP servers.

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

For the fastest end-to-end path, see the quickstart. For workflow guides, see Connect tools, Deploy an agent, and Run an agent.

Requirements

Install or upgrade deepagents-cli with uv:

uv tool install --prerelease allow deepagents-cli

If you already installed the tool, upgrade it:

uv tool upgrade --prerelease allow deepagents-cli

If you were given an exact beta version, pin that version:

uv tool install --force "deepagents-cli==<version>"

As a fallback, install the CLI with pip:

pip install -U --pre deepagents-cli

The CLI reads LANGSMITH_API_KEY, or LANGCHAIN_API_KEY as a fallback. It reads LANGSMITH_ENDPOINT, or LANGCHAIN_ENDPOINT as a fallback, when you need to override the default endpoint.

export LANGSMITH_API_KEY="<LANGSMITH_API_KEY>"

Project .env files can set API keys. Project .env files cannot set endpoint, proxy, or TLS environment variables for managed API requests. Set those overrides in your shell or in ~/.deepagents/.env.

Command overview

Command	Use
`deepagents --help`	Show CLI help.
`deepagents --version`	Show the installed `deepagents-cli` version.
`deepagents init [name]`	Scaffold a new Managed Deep Agents project.
`deepagents deploy`	Create or update a Managed Deep Agent from local project files.
`deepagents agents list`	List Managed Deep Agents in the workspace.
`deepagents agents get <agent_id>`	Inspect one Managed Deep Agent.
`deepagents agents delete <agent_id>`	Delete one Managed Deep Agent.
`deepagents mcp-servers list`	List registered workspace MCP servers.
`deepagents mcp-servers add`	Register a workspace MCP server.
`deepagents mcp-servers get <mcp_server_id>`	Inspect one MCP server with header values redacted.
`deepagents mcp-servers update <mcp_server_id>`	Update an MCP server URL, headers, or auth type.
`deepagents mcp-servers delete <mcp_server_id>`	Delete one MCP server.
`deepagents mcp-servers connect <mcp_server_id>`	Complete OAuth for an OAuth MCP server.

Bare deepagents invocations no longer start an interactive REPL. Install and run Deep Agents Code for interactive coding sessions.

Initialize projects

Use deepagents init to create a project directory:

deepagents init my-agent

If you omit the project name, the CLI prompts for it:

deepagents init

Argument or flag	Use
`name`	Project directory name. If omitted, the CLI prompts for a name.
`--force`	Overwrite files in an existing project directory.
`-h`, `--help`	Show command help.

The command creates:

File or directory	Purpose
`agent.json`	Agent metadata, model, backend, permissions, and optional target `agent_id`.
`AGENTS.md`	Main agent instructions.
`skills/`	Optional skill directories.
`.gitignore`	Excludes local `.env` files.

Deploy projects

Run deepagents deploy from a project directory:

deepagents deploy

The first deploy creates a Managed Deep Agent. Later deploys update the same remote agent by using user-local deploy state. The state is stored outside the project checkout, so repository-controlled files do not silently steer authenticated deploys.

Flag	Use
`--dir DIR`	Project directory. Defaults to the current working directory.
`--dry-run`	Print the agent payload and managed file tree without sending a request.
`--detach`	Exit after create or update without polling the agent health endpoint.
`--reset`	Discard local deploy state and create a fresh agent. Cannot be used when `agent.json` declares `agent_id`.
`--yes`	Confirm target-agent updates without prompting. Useful in automation.
`-h`, `--help`	Show command help.

deepagents deploy --dry-run prints JSON with:

Field	Description
`agent_payload`	The create or update payload for the Managed Deep Agent resource.
`directory_files`	The managed file tree that deploy syncs to Context Hub.

Target existing agents

For shared repositories or intentional updates to an existing Managed Deep Agent, declare the target in agent.json:

{
  "name": "my-agent",
  "agent_id": "agent-uuid",
  "model": "anthropic:claude-sonnet-4-6",
  "backend": {
    "type": "thread_scoped_sandbox"
  }
}

On first use, the CLI asks you to confirm before updating that remote agent. Use --yes to skip the prompt.

Deploy validation

Deploy fails before sending a request when the project is malformed. Common validation rules include:

agent.json and AGENTS.md are required.
agent.json must contain a non-empty name.
backend.sandbox requires backend.type to be thread_scoped_sandbox or agent_scoped_sandbox.
backend.sandbox.policy_ids must be an array of strings.
backend.sandbox.idle_ttl_seconds and backend.sandbox.delete_after_stop_seconds must be integers.
Symlinks are not allowed in deploy project inputs.
tools.json must contain a tools array.
Each tool in tools.json must include name and mcp_server_url.
Skill files require YAML frontmatter with name and description.
Subagent directories require agent.json and AGENTS.md.
Legacy deepagents.toml and mcp.json files produce migration hints instead of being deployed.

Before deploying, the CLI also validates referenced MCP server URLs. If a server URL is not registered, deploy fails with a command hint to add it. If an OAuth server is registered but the caller cannot invoke it, deploy fails with a hint to run deepagents mcp-servers connect <mcp_server_id>.

Manage agents

List agents:

deepagents agents list

The command prints tab-separated rows with agent ID, agent name, and update time. Inspect an agent:

deepagents agents get <agent_id>

Include managed files in the response:

deepagents agents get <agent_id> --include-files

Delete an agent:

deepagents agents delete <agent_id>

The delete command asks for confirmation. Skip the prompt with --yes:

deepagents agents delete <agent_id> --yes

Manage MCP servers

For a practical setup guide, see Connect tools.

Command	Use
`deepagents mcp-servers list`	List MCP server IDs, names, and URLs.
`deepagents mcp-servers add --url URL`	Register a static-header MCP server.
`deepagents mcp-servers add --url URL --auth-type oauth`	Register an OAuth MCP server.
`deepagents mcp-servers get <mcp_server_id>`	Print one MCP server as JSON with header values redacted.
`deepagents mcp-servers update <mcp_server_id>`	Update server URL, headers, or auth type.
`deepagents mcp-servers delete <mcp_server_id>`	Delete one MCP server.
`deepagents mcp-servers connect <mcp_server_id>`	Start or reuse OAuth authorization for one MCP server.

Add MCP servers

deepagents mcp-servers add \
  --url https://example.com/mcp \
  --name my-tools \
  --header Authorization="Bearer <token>"

Flag	Use
`--url URL`	MCP server URL. Required.
`--name NAME`	Display name. Defaults to the URL hostname.
`--header KEY=VALUE`	Static credential header. Repeat for multiple headers.
`--auth-type headers`	Static-header auth. This is the default.
`--auth-type oauth`	OAuth auth. Cannot be combined with `--header`.
`--connect`	Start OAuth connection after creating an OAuth MCP server. Requires `--auth-type oauth`.

deepagents mcp-servers add \
  --url https://example.com/mcp \
  --name github-tools \
  --auth-type oauth \
  --connect

OAuth add supports the same OAuth flags as connect.

Update MCP servers

Update a server URL or headers:

deepagents mcp-servers update <mcp_server_id> \
  --url https://new.example.com/mcp \
  --header Authorization="Bearer <token>"

Flag	Use
`--url URL`	Replace the server URL.
`--header KEY=VALUE`	Replace stored headers with the provided header set. Repeat for multiple headers.
`--clear-headers`	Clear stored headers. Cannot be combined with `--header`.
`--auth-type headers`	Set the auth type to static headers.

The command requires at least one change flag. Delete an MCP server:

deepagents mcp-servers delete <mcp_server_id>

The delete command asks for confirmation. Skip the prompt with --yes:

deepagents mcp-servers delete <mcp_server_id> --yes

Connect OAuth MCP servers

Start or reuse OAuth authorization:

deepagents mcp-servers connect <mcp_server_id>

Flag	Use
`--scope SCOPE`	OAuth scope to request. Repeat for multiple scopes.
`--force-new`	Create a fresh OAuth session instead of reusing an existing token.
`--timeout SECONDS`	Seconds to wait for OAuth completion. Use `0` to skip polling. Defaults to `300`.
`--no-browser`	Print the verification URL without opening a browser.

If authorization is pending, the CLI prints the verification URL. When --timeout 0 is set, the CLI starts authorization and exits. Re-run deepagents mcp-servers connect <mcp_server_id> later to complete or reuse the connection.

Project file reference

Managed Deep Agents projects use this layout:

my-agent/
  agent.json
  AGENTS.md
  tools.json
  skills/<name>/SKILL.md
  skills/<name>/<file>
  subagents/<name>/agent.json
  subagents/<name>/AGENTS.md
  subagents/<name>/tools.json
  subagents/<name>/skills/<skill-name>/SKILL.md

agent.json

agent.json configures the Managed Deep Agent resource:

{
  "name": "my-agent",
  "description": "A managed deep agent.",
  "model": "anthropic:claude-sonnet-4-6",
  "backend": {
    "type": "thread_scoped_sandbox"
  }
}

Field	Description
`name`	Required non-empty agent name.
`description`	Optional agent description.
`agent_id`	Optional existing Managed Deep Agent ID to update.
`model`	Optional shorthand model identifier in `{provider}:{model_id}` form.
`runtime`	Optional API-shaped runtime object. Use either `model` or `runtime`, not both.
`backend`	Optional backend configuration.
`permissions`	Optional identity, visibility, and tenant access settings.
`extras`	Optional extra metadata passed through to the API.

Configure the backend

Managed Deep Agents projects generated by the CLI use a LangSmith sandbox backend by default. Use a sandbox backend when the agent needs an isolated environment for code execution, filesystem work, or long-running tasks.

Backend type	Use for
`thread_scoped_sandbox`	Default. Scope LangSmith sandbox resources to each thread.
`agent_scoped_sandbox`	Scope LangSmith sandbox resources to the agent.
`default`	Use no sandbox-specific backend behavior.

The legacy sandbox value is normalized to thread_scoped_sandbox. Sandbox backends can include optional sandbox settings:

{
  "backend": {
    "type": "thread_scoped_sandbox",
    "sandbox": {
      "policy_ids": ["policy-id"],
      "idle_ttl_seconds": 900,
      "delete_after_stop_seconds": 300
    }
  }
}

backend.sandbox is valid only when backend.type is thread_scoped_sandbox or agent_scoped_sandbox. For standalone sandbox features such as snapshots, service URLs, permissions, CLI commands, and SDK usage, see the LangSmith sandboxes overview.

Field	Description
`policy_ids`	Array of sandbox policy IDs.
`idle_ttl_seconds`	Integer idle timeout.
`delete_after_stop_seconds`	Integer deletion delay after stop.

Supported permission values are:

Field	Values
`identity`	`personal`, `shared`
`visibility`	`tenant`, `user`
`tenant_access_level`	`read`, `run`, `write`

AGENTS.md

AGENTS.md contains the main agent instructions. The CLI sends this content as the agent system prompt and stores it in the managed file tree.

tools.json

tools.json configures MCP-backed tools. Add this file only when the agent uses MCP tools:

{
  "tools": [
    {
      "name": "example_tool",
      "mcp_server_url": "https://example.com/mcp",
      "mcp_server_name": "my-tools",
      "display_name": "example_tool"
    }
  ],
  "interrupt_config": {
    "https://example.com/mcp::example_tool": true
  }
}

Each tool requires name and mcp_server_url. mcp_server_name and display_name are optional. interrupt_config is optional and must be an object when present. Key each interrupt entry by "{mcp_server_url}::{tool_name}". Additional ::{mcp_server_name} components are accepted for compatibility.

skills

Each skill lives under skills/<name>/SKILL.md and requires YAML frontmatter:

---
name: summarize
description: Summarize text into a one-paragraph summary.
---

# Summarize

Given a text, produce a one-paragraph summary.

The CLI includes sibling files under the same skill directory recursively, excluding hidden paths.

subagents

Each subagent lives under subagents/<name>/ and requires:

File	Purpose
`agent.json`	Subagent metadata. Supports `description` and `model_id`.
`AGENTS.md`	Subagent instructions.
`tools.json`	Optional MCP-backed tools for the subagent.
`skills/`	Optional subagent-local skills.

Example subagent agent.json:

{
  "description": "Researches a topic.",
  "model_id": "anthropic:claude-sonnet-4-6"
}

Subagent names come from directory names. Names are checked case-insensitively for duplicates.

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

​Requirements

​Command overview

​Initialize projects

​Deploy projects

​Target existing agents

​Deploy validation

​Manage agents

​Manage MCP servers

​Add MCP servers

​Update MCP servers

​Connect OAuth MCP servers

​Project file reference

​agent.json

​Configure the backend

​AGENTS.md

​tools.json

​skills

​subagents

Requirements

Command overview

Initialize projects

Deploy projects

Target existing agents

Deploy validation

Manage agents

Manage MCP servers

Add MCP servers

Update MCP servers

Connect OAuth MCP servers

Project file reference

agent.json

Configure the backend

AGENTS.md

tools.json

skills

subagents