LangChain Deep Agents

In this guide we’ll give a LangChain Deep Agent a real computer to work in. The langchain-upstash-box package wraps an Upstash Box (a secure, isolated cloud container with a full Linux shell, filesystem, git, and a runtime) as a Deep Agents sandbox backend. The agent’s shell and file tools then run inside the box instead of on your machine.

1. Installation

pip install langchain-upstash-box

uv add langchain-upstash-box

Get a Box API key from the Upstash Console and export it:

export UPSTASH_BOX_API_KEY="box_xxxxxxxxxxxxxxxxxxxxxxxx"

2. Create a sandbox backend

UpstashBoxSandbox.create() provisions a new box, waits until it is ready, and returns a backend that implements the Deep Agents SandboxBackendProtocol:

The API key and base URL can also be passed directly as api_key= and base_url= arguments instead of the UPSTASH_BOX_API_KEY and UPSTASH_BOX_BASE_URL environment variables. The base URL defaults to https://us-east-1.box.upstash.com.

from langchain_upstash_box import UpstashBoxSandbox

# Creates a box and waits until it is ready.
sandbox = UpstashBoxSandbox.create(runtime="python")

result = sandbox.execute("echo hello")
print(result.output)     # "hello"
print(result.exit_code)  # 0

# Filesystem helpers (ls / read / write / edit / glob / grep) come for free.
sandbox.write("/workspace/home/hello.py", "print('hi from box')")
print(sandbox.execute("python3 /workspace/home/hello.py").output)

sandbox.delete()

If you already have a box, wrap it by id instead of creating a new one:

sandbox = UpstashBoxSandbox(box_id="current-wasp-05510")

3. Use with a Deep Agent

Pass the sandbox as the agent’s backend. Every shell command and file operation the agent performs now runs inside the box:

from deepagents import create_deep_agent
from langchain_upstash_box import UpstashBoxSandbox

sandbox = UpstashBoxSandbox.create(runtime="python")

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    system_prompt="You are a coding assistant with sandbox access.",
    backend=sandbox,
)

result = agent.invoke(
    {
        "messages": [
            {"role": "user", "content": "Create a hello world Python script and run it"}
        ]
    }
)
print(result["messages"][-1].content)

sandbox.delete()

The model="anthropic:..." shorthand requires langchain-anthropic (install with pip install "langchain[anthropic]") and an ANTHROPIC_API_KEY environment variable. Any LangChain chat model works here.

4. Cleanup

You own the box lifecycle, so call sandbox.delete() when you are done. An idle box pauses automatically: its compute is released but the filesystem is kept, and it wakes up on the next command. The box itself stays around until you delete it. Commands have a default execution timeout of 30 minutes. You can override it for the whole backend or per call:

sandbox = UpstashBoxSandbox.create(runtime="python", timeout=600)
result = sandbox.execute("sleep 5 && echo done", timeout=30)

To see everything else a box can do, like snapshots, git, previews, and schedules, check the Box quickstart.

Introduction

Basics

Lifecycle

Security

Browser

Guides

1. Installation

2. Create a sandbox backend

3. Use with a Deep Agent

4. Cleanup

​1. Installation

​2. Create a sandbox backend

​3. Use with a Deep Agent

​4. Cleanup

1. Installation

2. Create a sandbox backend

3. Use with a Deep Agent

4. Cleanup