使用 CLI 部署

使用深度智能体 CLI 将模型无关的开源智能体部署到生产环境

deepagents deploy 将你的智能体配置和文件打包在一起，作为 LangSmith 部署进行部署。

LangSmith 部署是水平可扩展的服务器，提供 30 多个端点，包括 MCP、A2A、Agent Protocol、人机协作和记忆 API。基于开放标准构建：

• 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 and requires deepagents-cli>=0.0.36. APIs, configuration format, and behavior may change between releases. See the releases page for detailed changelogs.

与 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	✅	❌

安装

安装 CLI 或直接使用 uvx 运行：

uv

uv tool install deepagents-cli

用法

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 your project files and run deepagents deploy.

设置

deploy 命令使用以下项目布局。将以下文件放在 deepagents.toml 旁边，它们会被自动发现和部署：

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	Description
deepagents.toml	Required. Configures the agent’s identity, authentication, sandbox environment, and the deployment of a prebuilt frontend Reach chat UI.
AGENTS.md	Required. Memory for the agent. Provides persistent context (project conventions, instructions, preferences) that is always loaded at startup. Read-only at runtime.
skills/	Optional. Directory of skill definitions that provide specialized workflows and domain knowledge. Each subdirectory should contain a SKILL.md file. Read-only at runtime. Dotfiles are skipped when uploading.
user/	Optional. Per-user writable memory. If an 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). The agent can read from and write to this file. Preloaded into the agent’s context via the memory middleware.
mcp.json	Optional. MCP tools (HTTP/SSE). If mcp.json exists, it is included in the deployment and langchain-mcp-adapters is added as a dependency. See MCP (LangChain) for more information. 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.
subagents/	Optional. Specialized 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.
.env	Optional. Environment variables (API keys, secrets). Placed alongside deepagents.toml at the project root. See Environment variables.

配置文件

deepagents.toml 配置智能体的身份和沙箱环境。只有 [agent] 部分是必需的。[sandbox] 部分是可选的，默认不使用沙箱。

Field	Type	Description
[agent]	Object	Required. Core agent identity (name and model).
[sandbox]	Object	Optional. Configure the isolated execution environment where the agent runs code. Defaults to no sandbox.
[auth]	Object	Optional. Configure authentication on the deployed agent. Required when [frontend].enabled = true.
[frontend]	Object	Optional. Enable and configure the built-in chat UI frontend.

[agent]

Configure the core agent identity:

deepagents.toml

[agent]
name = "research-assistant"
description = "Researches market trends, competitors, and target audiences"
model = "google_genai:gemini-3.1-pro-preview"

Field	Type	Description
name	string	Required. Name for the deployed agent. Used as the assistant identifier in LangSmith.
description	string	Optional. Human-readable description of what the agent does.
model	string	Optional. Model identifier in provider:model format. See supported models. The provider: prefix in the model field determines the required langchain-* package (e.g., google_genai -> langchain-google-genai) which is automatically included in the deployment. This includes models specified in subagent configs. Defaults to a credential-based model if omitted (tries openai:gpt-5.2, then anthropic:claude-sonnet-4-6, then google_genai:gemini-3.1-pro-preview, then google_vertexai:gemini-3.1-pro-preview, then nvidia:nvidia/nemotron-3-super-120b-a12b).

[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.

deepagents.toml

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

Field	Type	Description
provider	string	Optional. Sandbox provider. Supported values: "none", "daytona", "modal", "runloop", "langsmith" (private beta). The relevant partner package is automatically included in the deployment. See sandbox integrations for provider details. Defaults to "none". When omitted or set to provider = "none", the sandbox is disabled.
template	string	Optional. Provider-specific template name for the sandbox environment. Defaults to "deepagents-deploy".
image	string	Optional. Base Docker image for the sandbox container. Defaults to "python:3".
scope	string	Optional. Sandbox lifecycle scope. Defaults to "thread". "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.

[auth]

Add an [auth] section to configure authentication on the deployed agent. [auth] is required when [frontend].enabled = true; otherwise it is optional (without it, LangSmith Deployment’s default x-api-key requirement applies).

deepagents.toml

[agent]
name = "my-agent"
model = "google-genai:gemini-3.1-pro-preview"

[auth]
provider = "supabase"   # supabase | clerk | anonymous

Field	Type	Description
provider	string	Required. Auth provider. Supported values: "supabase", "clerk", "anonymous".

Pick one of three providers:

• Clerk ([auth] provider = "clerk") — per-user real authentication. Each user signs in; threads and memory are scoped per user.
• Supabase ([auth] provider = "supabase") — per-user real authentication. Same per-user scoping as Clerk.
• Anonymous ([auth] provider = "anonymous") — the bundler ships a permissive auth handler that overrides LangSmith Deployment’s default x-api-key requirement so the frontend can reach /threads, which means anyone with the deploy URL can call the API. The frontend assigns each browser a UUID cookie and filters the thread picker by it (UX-only scoping, not security). The CLI requires an interactive y/N confirmation before pushing.

Depending on your provider, add the following credentials to your .env alongside your other credentials:

Provider	Required env vars
supabase	SUPABASE_URL, SUPABASE_PUBLISHABLE_DEFAULT_KEY
clerk	CLERK_SECRET_KEY
anonymous	None

Runtime behavior:

• Unauthenticated requests return 401.
• On success, the authenticated user’s identity is injected into config.configurable.langgraph_auth_user_id.
• All resources (threads, runs, store) are automatically scoped per user via metadata.owner.
• LangSmith Studio bypasses auth for local development.

For information on how to authenticate, see Authentication.

[frontend]

Frontend deployment requires deepagents-cli>=0.0.43.

Optionally enable [frontend] to ship a prebuilt React chat UI alongside your agent on the same deployment. The frontend is mounted at /app on your deployment URL; your LangGraph API stays at the root (/threads, /runs, /assistants). The frontend provides:

• Streaming chat with the agent
• Thread picker with auto-generated titles from the first user message
• Real-time todos, files, and subagent activity panels that reflect your deep agent’s live graph state
• Light/dark theme toggle that follows OS preference on first load and persists after
• (Clerk / Supabase only) Sign-in / sign-up / sign-out flows — Clerk ships its full widget (social logins, password reset); Supabase ships email/password with a built-in password reset flow

Every frontend uses one of three authentication providers — Clerk, Supabase, or anonymous (see [auth]).

deepagents.toml

[agent]
name = "my-agent"
model = "anthropic:claude-sonnet-4-6"

[auth]
provider = "supabase"   # or "clerk"

[frontend]
enabled = true
app_name = "My Agent"
subtitle = "Your AI research assistant"
prompts = [
  "Summarize this paper",
  "Find related work",
  "Draft an outline",
]

Field	Type	Description
enabled	boolean	Optional. If true, bundle the default chat UI into the deployment. Defaults to false.
app_name	string	Optional. Display name shown in the UI header and browser tab. Defaults to [agent].name.
subtitle	string	Optional. Subtitle shown under the app name in the header and on the empty-state hero. Use it to describe what the agent does. Defaults to "Your deep agent, deployed.".
prompts	string[]	Optional. Suggestion chips shown on the empty-state when there are no messages. Defaults to a generic research-themed set; override to tailor the chips to your agent.

Environment variables:

The frontend reuses most of what [auth] already requires. Only Clerk needs one additional browser-facing key.

Provider	Additional var
supabase	None — reuses SUPABASE_URL and SUPABASE_PUBLISHABLE_DEFAULT_KEY from [auth]
clerk	CLERK_PUBLISHABLE_KEY (browser-facing publishable key; distinct from CLERK_SECRET_KEY)

Post-deploy setup:

After deploying, add your deployment URL to your auth provider’s dashboard so auth redirects land back in the app. This is a one-time step per deployment URL.

• Clerk: Dashboard → your application → Domains → add your deployment host (e.g. clerk-abc.us.langgraph.app). Clerk development instances auto-whitelist localhost; production deployment URLs need explicit whitelisting.
• Supabase: Dashboard → Authentication → URL Configuration → add https://<your-deployment>/app/** to Redirect URLs. Without this, password-reset and email-confirmation links won’t route back to your app.

环境变量

将 .env 文件放在 deepagents.toml 旁边，包含你的 API 密钥：

# 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=...

# Required if [auth] provider = "supabase"
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_PUBLISHABLE_DEFAULT_KEY=eyJhbGc...

# Required if [auth] provider = "clerk"
CLERK_SECRET_KEY=sk_test_...

# Required if [frontend].enabled = true AND [auth] provider = "clerk"
CLERK_PUBLISHABLE_KEY=pk_test_...

身份认证

运行时的认证策略取决于 [auth]：

• [auth] provider = "supabase" or "clerk" — per-user real authentication. Pass the user’s auth-provider token in the Authorization header.
• [auth] provider = "anonymous" — the bundler ships a permissive auth handler. The API is open to anyone with the deploy URL. No header required. (Required when shipping [frontend] without real per-user auth.)
• No [auth] section — the deploy falls back to LangSmith Deployment’s default x-api-key requirement. Pass your LangSmith API key in the x-api-key header. Only valid when [frontend].enabled is false or unset.

When [auth] is configured for supabase or clerk, pass the token from your auth provider in the Authorization header:

curl

curl -X POST https://your-deployment-url/threads \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {}}'

Python (langgraph-sdk)

from langgraph_sdk import get_client

client = get_client(
    url="https://your-deployment-url",
    headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"},
)

thread = await client.threads.create()

Provider	Where to get the token
Supabase	Supabase session access_token from supabase.auth.getSession()
Clerk	Clerk session token from getToken()

Each user’s threads and memory are isolated automatically—User B cannot see User A’s threads.

部署端点

部署的服务器暴露以下端点：

• 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

用户记忆

用户记忆为每个用户提供自己的可写 AGENTS.md，跨对话持久化。要启用它，在项目根目录创建 user/ 目录：

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.

子智能体

子智能体允许主智能体将专门的任务委派给隔离的子智能体。每个子智能体有自己的系统提示词、可选的技能和可选的 MCP 工具。主智能体接收一个 task 工具，按名称将工作分派给子智能体。

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

subagents/researcher/deepagents.toml

[agent]
name = "researcher"
description = "Researches market trends, competitors, and target audiences"
model = "google_genai:gemini-3.1-pro-preview"

Field	Type	Description
name	string	Required. Unique identifier for the subagent. Must be unique across all subagents.
description	string	Required. What this subagent does. The main agent uses this to decide when to delegate. Must be non-empty.
model	string	Optional. Model override in provider:model format. Omit to inherit the main agent’s model.

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:

deepagents.toml

[agent]
name = "gtm-strategist"
model = "google_genai:gemini-3.1-pro-preview"

subagents/researcher/deepagents.toml

[agent]
name = "researcher"
description = "Researches market trends, competitors, and target audiences to inform GTM strategy"
model = "google_genai:gemini-3.1-pro-preview"

subagents/researcher/AGENTS.md

# 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

限制

• MCP：仅支持 HTTP/SSE。 Stdio 传输在打包时会被拒绝。
• 不支持自定义 Python 工具。 使用 MCP 服务器来暴露自定义工具逻辑。

示例

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

deepagents.toml

[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:

deepagents.toml

[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

A lightweight internal-demo agent with the bundled UI in anonymous mode (no signup, no infrastructure):

deepagents.toml

[agent]
name = "internal-demo"
model = "anthropic:claude-sonnet-4-6"

[auth]
provider = "anonymous"   # API open to anyone with the URL — confirm at deploy time

[frontend]
enabled = true

---

连接这些文档到 Claude、VSCode 等工具，通过 MCP 获取实时答案。

Edit this page on GitHub or file an issue.