```
The `deepagents mcp-servers add` command also tries to list tools after registration. Pass `--no-tools` when you want to skip that discovery step.
```json tools.json theme={null}
{
"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`. The `mcp_server_name` and `display_name` fields are optional. Use the optional `interrupt_config` object to require human approval before a tool runs. Key each entry by `"{mcp_server_url}::{tool_name}"` and set it to `true`.
Deploy validates referenced MCP server URLs before sending a request. If a server URL is not registered, deploy fails with a hint to add it. For server setup and OAuth, see [Connect tools](/langsmith/managed-deep-agents-mcp).
### Add subagents
Subagents are delegated workers the main agent can call for focused tasks. Add a `subagents/` directory to the project root, then create one directory per subagent. Each subagent directory requires an `agent.json` and an `AGENTS.md`, and can include its own `tools.json` and `skills/`. The subagent name comes from its directory name.
```text theme={null}
my-agent/
agent.json
AGENTS.md
subagents/
researcher/
agent.json
AGENTS.md
tools.json # Optional: subagent-scoped MCP tools
skills/ # Optional: subagent-local skills
```
The subagent `agent.json` supports an optional `description` and `model`:
```json subagents/researcher/agent.json theme={null}
{
"description": "Researches a topic and returns concise findings with citations.",
"model": "openai:gpt-5.5"
}
```
Use `model` for new projects. For compatibility, the legacy `model_id` key still works in local subagent files.
Write the subagent instructions in `subagents/researcher/AGENTS.md`:
```md subagents/researcher/AGENTS.md theme={null}
# Researcher
Search for sources, take notes, and return concise findings with citations.
```
To give a subagent its own MCP tools, add `subagents/researcher/tools.json` with the same shape as the project-level `tools.json`. Subagent names are checked case insensitively for duplicates.
### Choose a backend
Managed Deep Agents projects generated by the CLI use the `state` backend in `agent.json`:
```json agent.json theme={null}
{
"backend": {
"type": "state"
}
}
```
Use a [LangSmith sandbox](/langsmith/sandboxes) backend when the agent needs an isolated environment for code execution, filesystem work, or long-running tasks. LangSmith manages the underlying sandbox lifecycle while the agent keeps its thread or agent scope.
| Backend type | Use for |
| ----------------------------------------------- | ------------------------------------------------- |
| `state` | Use no sandbox-specific backend behavior. |
| `sandbox` with `sandbox_config.scope: "thread"` | Scope LangSmith sandbox resources to each thread. |
| `sandbox` with `sandbox_config.scope: "agent"` | Scope LangSmith sandbox resources to the agent. |
Add optional sandbox settings under `backend` in `agent.json`:
```json agent.json theme={null}
{
"backend": {
"type": "sandbox",
"sandbox_config": {
"scope": "thread",
"policy_ids": ["policy-id"],
"idle_ttl_seconds": 900,
"delete_after_stop_seconds": 300
}
}
}
```
`backend.sandbox_config` is valid only when `backend.type` is `sandbox`. For standalone sandbox features such as snapshots, service URLs, permissions, CLI commands, and SDK usage, see the [LangSmith sandboxes overview](/langsmith/sandboxes).
### Deploy the project
Deploy the local project:
```bash theme={null}
deepagents deploy
```
To preview the assembled payload and managed file tree before deploying, run `deepagents deploy --dry-run`.
The first deploy creates a Managed Deep Agent. Later deploys update the same remote agent using local deploy state.
On success, the CLI prints the agent name, ID, short revision, the agent URL, and a post-deploy MCP health check:
```text theme={null}
Deployed: my-agent
agent_id: e2de7a35-9dda-462b-b982-9e57051993bc
revision: 13ac11f1
https://smith.langchain.com/o/-/agents/e2de7a35-9dda-462b-b982-9e57051993bc
health: {'agent_id': '...', 'mcp_check': {'ok': True, 'servers': [{'url': 'https://example.com/mcp', 'ok': True}]}, ...}
```
The `health` output above is abbreviated; it includes the full `mcp_check` result for every referenced server. A `mcp_check.ok` value of `True` confirms the agent can reach the MCP servers its tools reference. Each deploy creates a new agent revision, even when no managed files changed, because deploy always sends a metadata update. The managed file tree itself only changes when its contents do.
### Update a shared agent
For shared repositories or intentional updates to an existing Managed Deep Agent, set the target agent's `agent_id` in `agent.json`:
```json agent.json theme={null}
{
"name": "my-agent",
"agent_id": "agent-uuid",
"model": "openai:gpt-5.5",
"backend": {
"type": "state"
}
}
```
Then deploy:
```bash theme={null}
deepagents deploy
```
Deploying with `agent_id` set updates an existing shared agent in place.
On first use, the CLI asks you to confirm before updating that remote agent. To skip the confirmation, pass `--yes`:
```bash theme={null}
deepagents deploy --yes
```
### Troubleshoot a deploy
| Symptom | Cause and fix |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Deploy fails with an unregistered MCP server URL | A tool in `tools.json` references a server that is not registered for the workspace. [Register the server](/langsmith/managed-deep-agents-mcp), then deploy again. |
| `mcp_check.ok` is `False` in the deploy output | The agent cannot reach one or more referenced MCP servers. Find the failing URL under `servers`, confirm the server is running and reachable, then deploy again. |
| Deploy prompts to confirm an update you did not expect | `agent.json` declares an `agent_id` that targets an existing remote agent. Confirm the target before continuing, or remove `agent_id` to create a new agent. |
| Deploy fails with `401` or `403` | The `LANGSMITH_API_KEY` is missing, invalid, or belongs to a workspace without private beta access. Check the key and confirm the workspace has access. |
## Next steps
After you deploy an agent, open the printed agent URL in LangSmith to inspect managed files, revisions, traces, and runtime behavior. To add MCP tools, see [Connect tools](/langsmith/managed-deep-agents-mcp).
***
[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-deploy.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).