Run LangChain Deep Agents in a Promigence sandbox

LangChain Deep Agents run their shell and file tools through a sandbox backend. The langchain-promigence package gives you PromigenceSandbox, a backend you pass to create_deep_agent, so the agent's commands and file edits happen in a Promigence sandbox. Installing it also registers a promigence provider for deepagents-code, so dcode can use it with no extra wiring.

What you need#

• A Promigence API key in PROMIGENCE_API_KEY.
• Python 3.11 or newer (3.12 for the deepagents-code provider).
• deepagents 0.7.15. The package pins >=0.7.15,<0.8. The dcode provider was tested with deepagents-code 0.1.71.

Install#

pip install langchain-promigence
pip install "langchain-promigence[code]"     # adds the deepagents-code provider
export PROMIGENCE_API_KEY=prom_api_...
export PROMIGENCE_SPEND_CAP=5

A minimal example#

from deepagents import create_deep_agent
from langchain_promigence import PromigenceSandbox

sandbox = PromigenceSandbox.create(image="python:3.12-slim", working_dir="/workspace", spend_cap=1)
try:
    agent = create_deep_agent(model="anthropic:claude-sonnet-4-5", backend=sandbox)
    agent.invoke({"messages": [{"role": "user", "content": "run the tests and fix what fails"}]})
finally:
    sandbox.kill()

From async code, use acreate and akill. The synchronous create refuses to run inside an event loop and says so:

sandbox = await PromigenceSandbox.acreate(image="python:3.12-slim", spend_cap=1)
await agent.ainvoke(...)
await sandbox.akill()

For deepagents-code, pick the provider on the command line and name the image in PROMIGENCE_IMAGE:

dcode --sandbox promigence

Or set it in ~/.deepagents/config.toml. An entry there takes the place of the registered provider, so it names the provider class as well:

[sandboxes.providers.promigence]
class_path = "langchain_promigence.provider:PromigenceSandboxProvider"

[sandboxes.providers.promigence.params]
image = "ghcr.io/your-org/dev@sha256:..."
spend_cap = 5

Name the environment with image or snapshot. A tag is pinned to its digest for you, and the machine running the agent needs no Docker. The first use of an image builds a snapshot from it: a saved, verified environment that each sandbox starts as a fresh copy of. That build is billed per second while it runs, whether it verifies or not, up to $0.17 at the default small size (quickstart), and the sandboxes that reuse the snapshot pay no further build charge. setup and verify let you prepare and check that snapshot. Set working_dir, because the adapter does not read it from the image.

One sandbox per backend#

Each PromigenceSandbox is one sandbox. Give each agent run its own backend and the runs never see each other's files. sandbox.id is the id that promigence sandbox shell <id> and dcode --sandbox-id accept, which is handy when you want to look inside while an agent works.

Setting a spend cap#

spend_cap is the most one sandbox may spend, in US dollars. It falls back to PROMIGENCE_SPEND_CAP, then to your organization's default; with none, creation fails with a configuration error. timeout_sec (3600 by default) bounds the sandbox's lifetime.

Cleaning up#

Call sandbox.kill() (or await sandbox.akill()) when the run is over, ideally in finally. The sandbox also ends on its own at timeout_sec.

Environment failures stay separate from the agent's. A command that exits non-zero comes back in ExecuteResponse.exit_code. A failure of the sandbox itself raises PromigenceEnvironmentError with failure_class set to env; that failure is not billed and is not the task's fault. A broken image raises it with env_definition.

What is not supported yet#

• Images without /bin/sh, python3 and grep. The Deep Agents file tools are built on them, so distroless images cannot run the agent's file tools.
• Streaming output. execute returns once the command finishes.
• deepagents-code snapshot names. Name the environment with image or snapshot instead.
• A JavaScript package. The JS Deep Agents sandbox interface is different and needs its own work.

Next#

Read the agent briefing for what a sandbox gives an agent, or start with the quickstart.