deep agents/backends

111 notes in this subject, read out of this brain and free to use. This is page 1 of 2.

A2A server documentation in LangSmith

The A2A server is documented as part of LangSmith and is referenced as a server component for integration with LangSmith, located at the path /langsmith/server-a2a in the documentation.

Skills and memory configuration in ACP

Configure skills and memory for an ACP agent using the skills and memory options in agent configuration. Example: skills: ["./skills/", "~/.deepagents/skills/"], memory: ["./.deepagents/AGENTS.md"].

ACP vs MCP distinction

ACP is designed for agent-editor integrations. If you want your agent to call tools hosted by external servers, use Model Context Protocol (MCP) instead.

Install deepagents-acp package

Install the ACP integration package using pip install deepagents-acp (Python), npm install deepagents-acp (Node.js), yarn add deepagents-acp, or pnpm add deepagents-acp.

ACP Agent Registry availability

Deep Agents is available in the ACP Agent Registry for one-click installation in Zed and JetBrains IDEs. When an ACP client supports the registry, users can discover and install Deep Agents without any manual configuration.

Agent Client Protocol (ACP) purpose and use

Agent Client Protocol (ACP) standardizes communication between coding agents and code editors or IDEs. With ACP, you can expose custom deep agents to any ACP-compatible client, allowing your code editor to provide project context and receive rich updates. ACP is designed for agent-editor integrations.

ACP server stdio mode operation

The ACP server starts in stdio mode, reading requests from stdin and writing responses to stdout. In practice, it is usually run as a command launched by an ACP client (such as a code editor), which communicates with the server over stdio.

Python ACP quickstart example

The example shows importing from deepagents_acp and using the package to expose a deep agent over ACP in Python.

JavaScript ACP quickstart with startServer

Example shows using startServer from deepagents-acp package: await startServer({ agents: { name: "coding-assistant", description: "AI coding assistant with filesystem access" }, workspaceRoot: process.cwd() });

deepagents-acp CLI command

You can start an ACP server using the CLI without writing any code: npx deepagents-acp

ACP client examples

Notable ACP clients that work with deep agents include: Zed, JetBrains IDEs, Visual Studio Code (via vscode-acp), and Neovim (via ACP-compatible plugins).

Register deep agent with Zed simple setup

Register a deep agent with Zed by adding it to settings.json (~/.config/zed/settings.json on Linux, ~/Library/Application Support/Zed/settings.json on macOS). For simple setup without code, use: { "agent": { "profiles": { "deepagents": { "name": "DeepAgents", "command": "npx", "args": ["deepagents-acp"], "env": { "ANTHROPIC_API_KEY": "sk-ant-..." } } } } }

Zed registration with CLI options

Register a deep agent with Zed using CLI options: { "agent": { "profiles": { "deepagents": { "name": "DeepAgents", "command": "npx", "args": ["deepagents-acp", "--name", "my-assistant", "--skills", "./skills", "--debug"], "env": { "ANTHROPIC_API_KEY": "sk-ant-..." } } } } }

Zed registration with custom server script

For more control with Zed, create a TypeScript server script and point Zed at it: { "agent": { "profiles": { "my-agent": { "name": "My Agent", "command": "npx", "args": ["tsx", "./server.ts"] } } } }. The server.ts can use import { startServer } from "deepagents-acp"; and configure the agent.

deepagents-acp CLI options reference

CLI options: --name/-n (Agent name, default: "deepagents"), --description/-d (Agent description), --model/-m (LLM model, default: "claude-sonnet-4-5-20250929"), --workspace/-w (Workspace root directory, default: cwd), --skills/-s (Comma-separated skill paths), --memory (Comma-separated AGENTS.md paths), --debug (Enable debug logging to stderr), --help/-h (Show help message), --version/-v (Show version).

deepagents-acp environment variables

Environment variables for the CLI: ANTHROPIC_API_KEY (API key for Anthropic/Claude models, required), OPENAI_API_KEY (API key for OpenAI models), DEBUG (Set to "true" to enable debug logging), WORKSPACE_ROOT (Alternative to --workspace flag).

startServer function for ACP

The startServer function from deepagents-acp is a convenience function to create and start a server in one call. It accepts options including agents (agent configuration), workspaceRoot, and other server settings.

DeepAgentsServer class for full control

For full control over server creation, use the DeepAgentsServer class directly from deepagents-acp instead of the startServer convenience function.

Server options for DeepAgentsServer

Server options for DeepAgentsServer: agents (DeepAgentConfig | DeepAgentConfig[], required), serverName (string, default: "deepagents-acp"), serverVersion (string, default: "0.0.1"), workspaceRoot (string, default: process.cwd()), debug (boolean, default: false).

Agent configuration options

Agent configuration options: name (string, required, unique agent name), description (string, agent description), model (string, LLM model with default "claude-sonnet-4-5-20250929"), tools (StructuredTool[], custom LangChain tools), systemPrompt (string, custom system prompt), middleware (AgentMiddleware[], custom middleware appended to the Deep Agents stack), backend (AnyBackendProtocol, filesystem backend), skills (string[], skill source paths), memory (string[], memory source paths for AGENTS.md), interruptOn (Record<string, boolean | InterruptOnConfig>, tools requiring user approval for HITL), commands (Array<{ name, description, input? }>, custom slash commands).

Built-in slash commands in ACP

The ACP server registers built-in slash commands with the IDE: /plan, /agent, /ask, /clear, and /status. You can also define custom commands per agent.

Multiple agents from single server

You can expose multiple agents from a single ACP server. The ACP client selects which agent to use when creating a session. Some ACP clients like Zed do not currently expose a UI for selecting between agents, so you may need to run separate server instances with a single agent each.

Agent Protocol compatibility for async subagents

Async subagents communicate with any server that implements the Agent Protocol. You can use LangSmith Deployments or self-host any Agent Protocol-compatible server. Each subagent runs independently of the supervisor, which controls them through the SDK to launch, check, update, and cancel.

Install sandbox extras with dcode --install

Install sandbox extras with `dcode --install` (for example, `dcode --install daytona` or `dcode --install all-sandboxes`).

Remote sandbox routing with --sandbox

Route code execution to a remote sandbox with `--sandbox`. Built-in providers include `langsmith`, `agentcore`, `daytona`, `modal`, `runloop`, and `vercel`. Third-party and config-declared providers are also accepted. Pass `--sandbox` with no value to use `[sandboxes].default` from `config.toml`. Examples: `dcode --sandbox langsmith`, `dcode --sandbox runloop --sandbox-id dbx_abc123`, `dcode --sandbox modal --sandbox-setup ./setup.sh`, `dcode --sandbox`. Because `--sandbox` accepts an optional value, keep the bare form last on the command line.

Cloud-hosted open weights models in Deep Agents Code

Cloud options for open weights models include: (1) Groq: Free API key at console.groq.com, install groq extra, select model with /model or dcode --model groq:openai/gpt-oss-120b; (2) Fireworks: Install fireworks extra, set FIREWORKS_API_KEY, use dcode --model fireworks:accounts/fireworks/models/deepseek-v4-pro; (3) Baseten: Install baseten extra, set BASETEN_API_KEY, use dcode --model baseten:moonshotai/Kimi-K2.7-Code; (4) Together, OpenRouter, and Hugging Face also support open weights.

Model providers reference table

Deep Agents Code supported model providers

Deep Agents Code supports any LangChain-compatible chat model provider that supports tool calling. It includes OpenAI, Anthropic, and Gemini by default. Any service that exposes an OpenAI-compatible or Anthropic-compatible API also works out of the box.

OpenRouter and LiteLLM model routers

Model routers provide access to models from multiple providers through a single endpoint. OpenRouter (langchain-openrouter) uses config openrouter:<model> and is a built-in provider. LiteLLM (langchain-litellm) uses config litellm:<model> and is also a built-in provider. Install with /install openrouter or /install litellm in session, or dcode --install openrouter or dcode --install litellm from shell.

Local inference with Ollama in Deep Agents Code

To use open weights models locally with Ollama: (1) Install Ollama from ollama.com and pull a model (e.g., ollama pull qwen3:4b); (2) Install Ollama extra with /install ollama (in session) or dcode --install ollama (shell); (3) Select model with /model or pass directly: dcode --model ollama:qwen3:4b. This requires no API key.

AgentCore sandbox credentials and setup

AgentCore sandbox requires AWS credentials: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION (e.g., us-west-2). When using temporary/STS credentials, also set AWS_SESSION_TOKEN. Run with: dcode --sandbox agentcore. Default working directory is /tmp.

Daytona sandbox credentials and setup

Daytona sandbox requires setting DAYTONA_API_KEY environment variable. Run with: dcode --sandbox daytona. Default working directory is /home/daytona.

Modal sandbox credentials and setup

Modal sandbox requires running: modal setup. Run Deep Agents Code with: dcode --sandbox modal. Default working directory is /workspace.

Runloop sandbox credentials and setup

Runloop sandbox requires setting RUNLOOP_API_KEY environment variable. Run with: dcode --sandbox runloop. Default working directory is /home/user.

Vercel sandbox credentials and setup

Vercel sandbox requires setting VERCEL_TOKEN, VERCEL_PROJECT_ID, and VERCEL_TEAM_ID environment variables. When running on Vercel, OIDC credentials are used automatically instead. Run with: dcode --sandbox vercel. Default working directory is /vercel/sandbox.

E2B sandbox credentials and setup

E2B is a third-party sandbox provider published by the langchain-e2b package. Requires setting E2B_API_KEY environment variable. Install with: dcode --install langchain-e2b --package. Run with: dcode --sandbox e2b. Default working directory is /home/user.

Sandbox provider working directories

Default working directories by provider: LangSmith /root, AgentCore /tmp, Daytona /home/daytona, Modal /workspace, Runloop /home/user, Vercel /vercel/sandbox, E2B /home/user. Setup scripts and execute commands run from these directories unless overridden.

Publishing a sandbox provider with entry points

To distribute a sandbox provider, implement a SandboxProvider subclass and register it under the deepagents_code.sandbox_providers entry-point group in pyproject.toml. Override the metadata property to surface working directory and capability flags without instantiating the provider. Implement get_or_create and delete methods. Register in pyproject.toml: [project.entry-points."deepagents_code.sandbox_providers"] acme = "acme_sandbox.provider:AcmeProvider"

SandboxProvider metadata implementation

SandboxProvider subclass must return SandboxProviderMetadata from metadata property with fields: name (string), working_dir (string), install (SandboxInstallHint), supports_sandbox_id (boolean), supports_snapshot_name (boolean). If metadata property is omitted, a generic default is used: /workspace, no snapshot support.

Sandbox provider discovery priority

Deep Agents Code discovers sandbox providers from three sources with priority: config-declared providers (highest), third-party providers via entry points, built-in providers (lowest). When two sources define the same provider name, the higher priority wins, so config can override third-party entry points and built-ins.

Setup script execution in sandbox

Use --sandbox-setup PATH to run a shell script inside the sandbox after creation. Deep Agents Code expands ${VAR} references in setup scripts using local environment variables. This is useful for cloning repos, installing dependencies, and configuring environment variables. Store secrets in a local .env file for the setup script to access.

Sandbox snapshot support

--sandbox-snapshot-name NAME allows using or creating a sandbox snapshot. Supported by langsmith and runloop providers, and any third-party provider that advertises snapshot support. Cannot be combined with --sandbox-id. Snapshots allow saving and restoring sandbox state.

Setup script example

#!/bin/bash set -e # Clone repository using GitHub token git clone https://x-access-token:${GITHUB_TOKEN}@github.com/username/repo.git $HOME/workspace cd $HOME/workspace # Make environment variables persistent cat >> ~/.bashrc <<'EOF' export GITHUB_TOKEN="${GITHUB_TOKEN}" export OPENAI_API_KEY="${OPENAI_API_KEY}" cd $HOME/workspace EOF source ~/.bashrc

Reuse existing sandbox by ID

Use dcode --sandbox runloop --sandbox-id dbx_abc123 to reuse an existing sandbox by ID instead of creating a new one. This skips creation and cleanup. Only supported by providers that allow reattaching by ID. Refer to sandbox provider documentation for specific ID format.

Third-party sandbox provider discovery

A package can publish a sandbox provider under the deepagents_code.sandbox_providers entry-point group. Once installed, its provider is available to --sandbox automatically without config changes. Example: dcode --install langchain-e2b --package then dcode --sandbox e2b.

Deep Agents Code sandbox as tool pattern

Deep Agents Code uses the sandbox as tool pattern: the dcode process (LLM loop, memory, tool dispatch) runs on your machine, but agent tool calls (read_file, write_file, execute, etc.) target the remote sandbox, not your local filesystem. To get files into the sandbox, use a setup script or the provider's file transfer APIs.

Built-in sandbox providers

Deep Agents Code supports these built-in sandbox providers: LangSmith (included by default), AgentCore, Daytona, Modal, Runloop, and Vercel. These are available as extras in the deepagents-code package. Install all at once with the all-sandboxes extra.

Install provider dependencies

Install built-in providers in session with /install PROVIDER or from shell with dcode --install PROVIDER. Third-party providers like E2B use the --package flag: /install langchain-e2b --package or dcode --install langchain-e2b --package. Install all built-in providers at once with /install all-sandboxes or dcode --install all-sandboxes.

LangSmith sandbox credentials and setup

LangSmith sandbox requires setting LANGSMITH_API_KEY environment variable. Run with: dcode --sandbox langsmith. LangSmith is included by default when installing deepagents-code. Default working directory is /root.

CompositeBackend flexible routing

A flexible backend where you can specify different routes in the filesystem to point towards different backends.

StateBackend filesystem behavior

A thread-scoped filesystem backend stored in langgraph state. Files persist across turns within a thread (via your checkpointer) and are not shared across threads.

FilesystemBackend security warning

The local machine's filesystem. This backend grants agents direct filesystem read/write access. Use with caution and only in appropriate environments. Wrap FilesystemBackend in a CompositeBackend to prevent internal agent data (offloaded tool results, conversation history) from being written to disk alongside your project files. See the recommended pattern in the backends documentation.

LocalShellBackend security warning

A filesystem with shell execution directly on the host. Provides filesystem tools plus the execute tool for running commands. This backend grants agents direct filesystem read/write access and unrestricted shell execution on your host. Use with extreme caution and only in appropriate environments.

StoreBackend persistent storage

A filesystem that provides long-term storage that is persisted across threads. When deploying to LangSmith Deployment, omit the store parameter—the platform automatically provisions a store for your agent. The namespace parameter controls data isolation. For multi-user deployments, always set a namespace factory to isolate data per user or tenant.

ContextHubBackend durable storage

Durable filesystem storage in a LangSmith Hub repo. See the backends documentation for more details on ContextHubBackend.

Available sandbox providers for Deep Agents

Sandbox providers available for Deep Agents code execution include: LangSmith, AgentCore, Daytona, E2B, Modal, and Runloop. Each has specific setup requirements and installation dependencies.

Backends enable sandboxed code execution

Deep Agents use backends to execute code in sandboxed environments. Backends are configurable and support multiple providers including LangSmith sandbox, local shell (with security warnings), AgentCore, Daytona, E2B, Modal, and Runloop. A sandboxed environment is highly recommended for any production use.

LangSmith sandbox backend setup

To use LangSmith sandbox as a backend, install langsmith[sandbox] and import: from langsmith.experimental.sandbox import LangSmithSandbox. Then create the backend: backend = LangSmithSandbox().

Local shell backend security considerations

The LocalShellBackend provides unrestricted filesystem and shell access and should be used only in controlled environments for development and testing. It is not recommended for production use.

Deep Agents execution backends

Deep Agents supports pluggable execution backends including local filesystem, virtual filesystem, remote sandbox, and custom backends. Claude Agent SDK only supports the local filesystem of the sandbox it runs in.

Give your agent this brain