Skip to content

deploy.mdx

Latest commit

 

History

History
432 lines (323 loc) · 19.2 KB

deploy.mdx

File metadata and controls

432 lines (323 loc) · 19.2 KB
title Deploy with the CLI
description Deploy a model-agnostic, open source agent to production with the Deep Agents CLI

Deep Agents Deploy takes your agent configuration and deploys it as a LangSmith Deployment: a horizontally scalable server with 30+ endpoints including MCP, A2A, Agent Protocol, human-in-the-loop, and memory APIs. Built on open standards:

  • Open source harness: MIT licensed, available for Python and TypeScript
  • AGENTS.md: open standard for agent instructions
  • Agent Skills: open standard for agent knowledge and actions
  • Any model, any sandbox: no provider lock-in
  • Open protocols: MCP, A2A, Agent Protocol
  • Self-hostable: LangSmith Deployments can be self-hosted so memory stays in your infrastructure
Deep Agents Deploy is currently in beta. APIs, configuration format, and behavior may change between releases. See the [releases page](https://github.com/langchain-ai/deepagents/releases) for detailed changelogs.

Compare to Claude Managed Agents

Deep Agents Deploy Claude Managed Agents
Model support OpenAI, Anthropic, Google, Bedrock, Azure, Fireworks, Baseten, OpenRouter, many more Anthropic only
Harness Open source (MIT) Proprietary, closed source
Sandbox LangSmith, Daytona, Modal, Runloop, or custom Built in
MCP support ✅ ✅
Skill support ✅ ✅
AGENTS.md support ✅ ❌
Agent endpoints MCP, A2A, Agent Protocol Proprietary
Self hosting ✅ ❌

What you're deploying

deepagents deploy packages your agent configuration and deploys it as a LangSmith Deployment. You configure your agent with a few parameters:

Parameter Description
model The LLM to use. Any provider works — see supported models.
AGENTS.md The system prompt, loaded at the start of each session.
skills Agent Skills for specialized knowledge and actions. Skills are synced into the sandbox so the agent can execute them at runtime. See skills docs.
user/ Per-user writable memory. If a AGENTS.md template is present in the user folder, the agents seeds the template per user (if the folder is empty the agents creates an empty AGENTS.md). Writable at runtime. Preloaded into the agent's context via the memory middleware.
mcp.json MCP tools (HTTP/SSE). See MCP docs.
subagents/ Specialized subagents the main agent can delegate to. Each subdirectory contains its own deepagents.toml, AGENTS.md, and optionally a skills folder. See subagents.
sandbox Optional execution environment. Thread-scoped sandboxes are provisioned per thread and will be re-created if the server restarts. Use scope = "assistant" if you need sandbox state that persists across threads. See sandbox providers.

Install

Install the CLI or run directly with uvx:

```bash uv uv tool install deepagents-cli ``` 
```bash uvx (no install)
uvx deepagents-cli deploy
```

Usage

deepagents init [name] [--force]                                             # scaffold a new project
deepagents dev  [--config deepagents.toml] [--port 2024] [--allow-blocking]  # bundle and run locally
deepagents deploy [--config deepagents.toml] [--dry-run]                     # bundle and deploy

By default, deepagents deploy looks for deepagents.toml in the current directory. Pass --config to use a different path:

deepagents deploy --config path/to/deepagents.toml

deepagents deploy fully rebuils and creates a new revision on every invocation. Use deepagents dev for local iteration.

deepagents init

Scaffold a new agent project:

deepagents init my-agent

This creates the following files:

File Purpose
deepagents.toml Agent config — name, model, optional sandbox
AGENTS.md System prompt loaded at session start
.env API key template (GOOGLE_API_KEY, LANGSMITH_API_KEY, etc.)
mcp.json MCP server configuration (empty by default)
skills/ Directory for Agent Skills, with an example review skill

After init, edit AGENTS.md with your agent's instructions and run deepagents deploy. Optionally add a user/ directory with per-user memory templates — see User Memory.

Project layout

The deploy command uses a convention-based project layout. Place the following files alongside your deepagents.toml and they are automatically discovered:

my-agent/
├── deepagents.toml
├── AGENTS.md
├── .env
├── mcp.json
├── skills/
│   ├── code-review/
│   │   └── SKILL.md
│   └── data-analysis/
│       └── SKILL.md
├── subagents/
│   └── researcher/
│       ├── deepagents.toml
│       └── AGENTS.md
└── user/
    └── AGENTS.md
File/directory Purpose Required
AGENTS.md Memory for the agent. Provides persistent context (project conventions, instructions, preferences) that is always loaded at startup. Read-only at runtime. Yes
skills/ Directory of skill definitions. Each subdirectory should contain a SKILL.md file. Read-only at runtime. No
user/ Per-user writable memory. If a AGENTS.md template is present in the user folder, the agents seeds the template per user (if the folder is empty the agents creates an empty AGENTS.md). Writable at runtime. Preloaded into the agent's context via the memory middleware. No
subagents/ Subagents the main agent can delegate to. Each subdirectory must contain a deepagents.toml, AGENTS.md, and optionally a skills folder. Auto-discovered at bundle time. No
mcp.json MCP server configuration. Only http and sse transports are supported in deployed contexts. No
.env Environment variables (API keys, secrets). Placed alongside deepagents.toml at the project root. No
`mcp.json` must only contain servers using `http` or `sse` transports. Servers using `stdio` transport are not supported in deployed environments because there is no local process to spawn. 
Convert stdio servers to HTTP or SSE before deploying.

Configuration file

deepagents.toml configures the agent's identity and sandbox environment. Only the [agent] section is required. The [sandbox] section is optional and defaults to no sandbox.

[agent]

(Required)

Core agent identity. For more on model selection and provider configuration, see supported models.

Name for the deployed agent. Used as the assistant identifier in LangSmith. Model identifier in `provider:model` format. See [supported models](/oss/deepagents/models#supported-models). 
[agent]
name = "research-assistant"
model = "google_genai:gemini-3.1-pro-preview"
The `name` field is the only required value in the entire configuration file. Everything else has defaults.

Skills, user memories, subagents, MCP servers, and model dependencies are auto-detected from the project layout:

  • Skills: the bundler recursively scans skills/, skipping hidden dotfiles, and bundles the rest.
  • User memory: if user/ exists, a single AGENTS.md is bundled as per-user memory (from user/AGENTS.md if present, otherwise empty). At runtime, each user gets their own copy (seeded on first access, never overwritten). The agent can read from and write to this file.
  • Subagents: if subagents/ exists, the bundler scans for valid subdirectories (each must contain deepagents.toml and AGENTS.md). The main agent receives a task tool to delegate work to each subagent by name. See subagents.
  • MCP servers: if mcp.json exists, it is included in the deployment and langchain-mcp-adapters is added as a dependency. Only HTTP/SSE transports are supported (stdio is rejected at bundle time).
  • Model dependencies: the provider: prefix in the model field determines the required langchain-* package (e.g., google_genai -> langchain-google-genai). This includes models specified in subagent configs.
  • Sandbox dependencies: the [sandbox].provider value maps to its partner package (e.g., daytona -> langchain-daytona).

[sandbox]

Configure the isolated execution environment where the agent runs code. Sandboxes provide a container with a filesystem and shell access, so untrusted code cannot affect the host. For supported providers and advanced sandbox configuration, see sandboxes.

When omitted or set to provider = "none", the sandbox is disabled. Sandboxes are for if you need code execution or skill script execution.

Sandbox provider. Determines where the container runs. Supported values: `"none"`, `"daytona"`, `"modal"`, `"runloop"`, `"langsmith"` (private beta). See [sandbox integrations](/oss/integrations/sandboxes) for provider details. Provider-specific template name for the sandbox environment. Base Docker image for the sandbox container. Sandbox lifecycle scope. `"thread"` creates one sandbox per conversation. `"assistant"` shares a single sandbox across all conversations for the same assistant.

Scope behavior:

  • "thread" (default): Each conversation gets its own sandbox. Different threads get different sandboxes, but the same thread reuses its sandbox across turns. Use this when each conversation should start with a clean environment.
  • "assistant": All conversations share one sandbox. Files, installed packages, and other state persist across conversations. Use this when the agent maintains a long-lived workspace like a cloned repo.

.env

Place a .env file alongside deepagents.toml with your API keys:

# Required — model provider keys
ANTHROPIC_API_KEY=sk-...
OPENAI_API_KEY=sk-...
# ...etc.

# Required for deploy and LangSmith sandbox
LANGSMITH_API_KEY=lsv2_...

# Optional — sandbox provider keys
DAYTONA_API_KEY=...
MODAL_TOKEN_ID=...
MODAL_TOKEN_SECRET=...
RUNLOOP_API_KEY=...

Sandbox providers

Set [sandbox].provider in deepagents.toml and add the required env vars to .env. For available providers, see sandbox integrations. For lifecycle patterns and SDK usage, see sandboxes.

Deployment endpoints

The deployed server exposes:

  • MCP: call your agent as a tool from other agents
  • A2A: multi-agent orchestration via A2A protocol
  • Agent Protocol: standard API for building UIs
  • Human-in-the-loop: approval gates for sensitive actions
  • Memory: short-term and long-term memory access

Examples

A content writing agent with per-user preferences that the agent can update:

[agent]
name = "deepagents-deploy-content-writer"
model = "google_genai:gemini-3.1-pro-preview"
my-content-writer/
├── deepagents.toml
├── AGENTS.md
├── skills/
│   ├── blog-post/SKILL.md
│   └── social-media/SKILL.md
└── user/
    └── AGENTS.md          # writable — agent learns user preferences

A coding agent with a LangSmith sandbox for running code:

[agent]
name = "deepagents-deploy-coding-agent"
model = "google_genai:gemini-3.1-pro-preview"

[sandbox]
provider = "langsmith"
template = "coding-agent"
image = "python:3.12"

A GTM strategy agent that delegates research to a subagent:

my-gtm-agent/
├── deepagents.toml
├── AGENTS.md
├── skills/
│   └── competitor-analysis/
│       └── SKILL.md
└── subagents/
    └── market-researcher/
        ├── deepagents.toml
        ├── AGENTS.md
        └── skills/
            └── analyze-market/
                └── SKILL.md

User Memory

User memory gives each user their own writable AGENTS.md that persists across conversations. To enable it, create a user/ directory at your project root:

user/
└── AGENTS.md          # optional — seeded as empty if not provided

If the user/ directory exists (even if empty), every user gets their own AGENTS.md at /memories/user/AGENTS.md. If you provide user/AGENTS.md, its contents are used as the initial template; otherwise an empty file is seeded.

At runtime, user memory is scoped per user via custom auth (runtime.server_info.user.identity). The first time a user interacts with the agent, their namespace is seeded with the template. Subsequent interactions reuse the existing file — the agent's edits persist, and redeployments never overwrite user data.

How it works

  1. Bundle time — the bundler reads user/AGENTS.md (or uses an empty string) and includes it in the seed payload.
  2. Runtime (first access) — when the agent sees a user_id for the first time, it writes the AGENTS.md template to the store under that user's namespace. Existing entries are never overwritten.
  3. Preloaded — the user AGENTS.md is passed to the memory middleware, so the agent sees its contents in context at the start of every conversation.
  4. Writable — the agent can update it using the edit_file tool. The shared AGENTS.md file and skills folder are read-only.

Permissions

Path Writable Scope
/memories/AGENTS.md No Shared (assistant-scoped)
/memories/skills/** No Shared (assistant-scoped)
/memories/user/** Yes Per-user (user_id-scoped)
/memories/subagents/<name>/** By subagent only Per-subagent (isolated)

User identity

The user_id is resolved from custom auth via runtime.user.identity. The platform injects the authenticated user's identity automatically — no need to pass it through configurable. If no authenticated user is present, user memory features are gracefully skipped for that invocation.

Subagents

Subagents let the main agent delegate specialized tasks to isolated child agents. Each subagent has its own system prompt, optional skills, and optional MCP tools. The main agent receives a task tool that dispatches work to subagents by name.

For background on why subagents are useful and how they work at the SDK level, see Subagents.

Directory structure

Create a subagents/ directory at your project root. Each subdirectory is a subagent:

my-agent/
├── deepagents.toml
├── AGENTS.md
└── subagents/
    ├── researcher/
    │   ├── deepagents.toml       # name, description, optional model override
    │   ├── AGENTS.md             # subagent system prompt
    │   ├── skills/               # optional — subagent-specific skills
    │   │   └── analyze-market/
    │   │       └── SKILL.md
    │   └── mcp.json              # optional — HTTP/SSE MCP tools
    └── writer/
        ├── deepagents.toml
        └── AGENTS.md

Each subagent subdirectory must contain:

File Purpose
deepagents.toml Subagent config with [agent].name and [agent].description
AGENTS.md System prompt for the subagent

Each subagent subdirectory may contain:

File Purpose
skills/ Subagent-specific skills (with SKILL.md files)
mcp.json MCP server configuration (HTTP/SSE only; stdio is rejected)

Subagent configuration

Unique identifier for the subagent. Must be unique across all subagents. What this subagent does. The main agent uses this to decide when to delegate. Must be non-empty. Model override in `provider:model` format. Omit to inherit the main agent's model. 
[agent]
name = "researcher"
description = "Researches market trends, competitors, and target audiences"
model = "anthropic:claude-haiku-4-5-20251001"

Inheritance

Subagents inherit some properties from the main agent by default:

Property Inherited Notes
Model Yes Override with model in the subagent's deepagents.toml
Tools Yes Override by adding mcp.json to the subagent directory
Skills No Declare explicitly in the subagent's own skills/ directory

Memory isolation

Each subagent gets a dedicated, isolated memory namespace at /memories/subagents/<name>/. The subagent's AGENTS.md and skills are seeded into this namespace at deploy time.

Path Main agent Subagent
/memories/AGENTS.md Read No access
/memories/skills/** Read No access
/memories/user/** Read + Write No access
/memories/subagents/<name>/** Read Read + Write

Example

A go-to-market agent that delegates research to a specialized subagent:

[agent]
name = "gtm-strategist"
model = "anthropic:claude-sonnet-4-6"
[agent]
name = "researcher"
description = "Researches market trends, competitors, and target audiences to inform GTM strategy"
model = "anthropic:claude-haiku-4-5-20251001"
# Market Researcher

You are a market research specialist. Your job is to gather and synthesize
market data to support go-to-market decisions.

## Focus Areas
- Market sizing: TAM, SAM, SOM estimates
- Competitor analysis: product positioning, pricing, market share
- Audience segmentation: demographics, psychographics, buying behavior

Limitations

  • MCP: HTTP/SSE only. Stdio transports are rejected at bundle time.
  • No custom Python tools. Use MCP servers to expose custom tool logic.