Managed Deep Agents CLI reference

The deepagents CLI, installed from the deepagents-cli package, 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, available on LangSmith Cloud in the US region only. 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

Managed Deep Agents requires deepagents-cli>=0.2.0.

Install deepagents-cli with uv (preferred) or pip:

uv tool install "deepagents-cli>=0.2.0"

To upgrade an existing uv install, run uv tool upgrade deepagents-cli. The CLI reads LANGSMITH_API_KEY. To create a key, see Create an API key. To override the default endpoint, set LANGSMITH_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 <server>`	Inspect one MCP server with header values redacted.
`deepagents mcp-servers tools <server>`	List a server’s tools and print a `tools.json` snippet.
`deepagents mcp-servers update <server>`	Update an MCP server URL, headers, or auth type.
`deepagents mcp-servers delete <server>`	Delete one MCP server.
`deepagents mcp-servers connect <server>`	Complete OAuth for an OAuth MCP server.

Bare deepagents invocations do not 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 init command creates the following files in the project directory:

File or directory	Description
`agent.json`	Agent metadata, model, backend, permissions, and optional target `agent_id`. See the agent.json section.
`AGENTS.md`	Main agent instructions. See the AGENTS.md section.
`tools.json`	Empty tool configuration. Add MCP-backed tools after registering a server. See the tools.json section.
`skills/example-skill/`	Example skill directory. Edit, replace, or delete it. See the skills section.
`subagents/researcher/`	Example subagent directory. Edit, replace, or delete it. See the subagents section.
`.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 agent. Deploy state is user-local and stored outside your project, so files committed to the repository do not change which agent you deploy to. By default, deploy uploads the project, polls the agent health endpoint, and prints the agent name, ID, short revision, agent URL, and a post-deploy MCP health check. Use --detach to skip polling and exit immediately after create or update.

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.
`-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": "openai:gpt-5.5",
  "backend": {
    "type": "default"
  }
}

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

Validate the project before deploy

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 <id|name|url>.

Manage agents

List agents:

deepagents agents list

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

e2de7a35-9dda-462b-b982-9e57051993bc	my-agent	2026-06-01T12:00:00Z

Inspect an agent:

deepagents agents get <agent_id>

Include managed files in the response:

deepagents agents get <agent_id> --include-files

Flag	Use
`--include-files`	Include managed files in the response.
`-h`, `--help`	Show command help.

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

Flag	Use
`--yes`	Skip the confirmation prompt.
`-h`, `--help`	Show command help.

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 <server>`	Print one MCP server as JSON with header values redacted.
`deepagents mcp-servers tools <server>`	List a server’s tools and print a `tools.json` snippet.
`deepagents mcp-servers update <server>`	Update server URL, headers, or auth type.
`deepagents mcp-servers delete <server>`	Delete one MCP server.
`deepagents mcp-servers connect <server>`	Start or reuse OAuth authorization for one MCP server.

Commands that take <server> accept an MCP server ID, exact name, or URL. Non-ID values are resolved against deepagents mcp-servers list; URL matching ignores case and trailing slashes. If a name or URL matches more than one server, re-run the command with the server ID.

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`.
`--no-tools`	Skip best-effort tool listing after registration.

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: --scope, --force-new, --timeout, and --no-browser.

List MCP server tools

List a registered server’s tools:

deepagents mcp-servers tools <id|name|url>

The command prints each tool name and the first line of its description, then prints a paste-ready tools.json snippet. For OAuth servers, connect first so the MCP server record includes the caller’s oauth_provider_id.

Update MCP servers

Update a server URL or headers:

deepagents mcp-servers update <id|name|url> \
  --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 <id|name|url>

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

deepagents mcp-servers delete <id|name|url> --yes

Connect OAuth MCP servers

Start or reuse OAuth authorization:

deepagents mcp-servers connect <id|name|url>

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 <id|name|url> 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": "openai:gpt-5.5",
  "backend": {
    "type": "default"
  }
}

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 the default backend. Use a LangSmith sandbox backend when the agent needs an isolated environment for code execution, filesystem work, or long-running tasks.

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

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.

Configure permissions

The optional permissions field in agent.json sets identity, visibility, and tenant access. Supported 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. deepagents init creates this file with an empty tools array. Add tool entries after registering an MCP server:

{
  "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 recursively includes all other files in the skill directory, excluding hidden paths.

subagents

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

File	Description
`agent.json`	Subagent metadata. Supports `description` and `model`.
`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": "openai:gpt-5.5"
}

The legacy model_id key is still accepted in local subagent files, but new projects should use model. The REST API SubagentSpec uses model_id. 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.

​Requirements

​Command overview

​Initialize projects

​Deploy projects

​Target existing agents

​Validate the project before deploy

​Manage agents

​Manage MCP servers

​Add MCP servers

​List MCP server tools

​Update MCP servers

​Connect OAuth MCP servers

​Project file reference

​agent.json

​Configure the backend

​Configure permissions

​AGENTS.md

​tools.json

​skills

​subagents

Requirements

Command overview

Initialize projects

Deploy projects

Target existing agents

Validate the project before deploy

Manage agents

Manage MCP servers

Add MCP servers

List MCP server tools

Update MCP servers

Connect OAuth MCP servers

Project file reference

agent.json

Configure the backend

Configure permissions

AGENTS.md

tools.json

skills

subagents