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.
deepagents init [name] [--force] # scaffold a new projectdeepagents dev [--config deepagents.toml] [--port 2024] [--allow-blocking] # bundle and run locallydeepagents 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:
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.
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).
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.
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.
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).
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.
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 = trueapp_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.
[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:
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.
Bundle time — the bundler reads user/AGENTS.md (or uses an empty string) and includes it in the seed payload.
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.
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.
Writable — the agent can update it using the edit_file tool. The shared AGENTS.md file and skills folder are read-only.
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.
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.
[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 ResearcherYou are a market research specialist. Your job is to gather and synthesizemarket 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
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
