Agent frameworks

LangGraph

Give a LangGraph or deepagents agent a Nevia computer as its sandbox backend, so its file tools and commands run on the computer

The LangGraph adapter gives a LangGraph agent a sandbox backend on a Nevia computer. The agent's ls, read_file, write_file, edit_file, glob, grep and execute tools run on the computer, not on your machine. The adapter is built on the Python SDK and is in early access, so names and behaviour can change.

The quick start gives an agent a computer, asks it to write and run a program and deletes the computer. The adapter follows the deepagents sandbox backend contract, so the deepagents docs cover the tools and options. This page covers only what is particular to Nevia.

Prerequisites

You need:

  • Python 3.11 or later.
  • deepagents 0.7.
  • langgraph 1.2 or later.
  • An API key for the model provider. The quick start uses Anthropic, so it needs ANTHROPIC_API_KEY.
  • The nevia CLI, signed in with nevia login, to download the SDK bundle. The Quickstart shows how to install it.
  • A Nevia key file for a service account with the editor role. Use an automation key file shows how a workspace admin issues one.

Install the adapter

Invited testers only

The SDKs are in early access for invited testers. To ask for access, see Request access to Nevia.

From your project's root, download the SDK bundle. It unpacks to vendor/nevia-sdk-0.1.0/:

curl -fsSL --oauth2-bearer "$(nevia auth access-token)" https://sdk.nevia.cloud/0.1.0.tar.gz | tar -xz

Then install the adapter, with the SDK beside it, from the bundle:

uv add "nevia-langgraph[anthropic] @ ./vendor/nevia-sdk-0.1.0/python/nevia_langgraph-0.1.0-py3-none-any.whl" \
    ./vendor/nevia-sdk-0.1.0/python/nevia-0.1.0-py3-none-any.whl

Name the SDK's file next to the adapter's, so both come from the bundle and nothing is looked up on a public registry.

The anthropic extra adds langchain-anthropic, so the quick start can name an Anthropic model. The adapter installs deepagents with it.

Authenticate

Point the adapter at the key file and set the model provider's key:

export NEVIA_KEY_FILE="$HOME/path/to/key.json"
export ANTHROPIC_API_KEY="sk-ant-..."

Without NEVIA_KEY_FILE, the adapter falls back to your nevia login session. It finds credentials in the same order as the Python SDK.

Give an agent a computer

Save this as agent.py:

from deepagents import create_deep_agent
from nevia_langgraph import NeviaSandbox

backend = NeviaSandbox(name='quickstart', image='docker.io/library/python:3.13-slim')

agent = create_deep_agent(model='anthropic:claude-sonnet-5-5', backend=backend)

try:
    result = agent.invoke(
        {
            'messages': [
                {
                    'role': 'user',
                    'content': 'Write hello.py that prints the Python version, then run it. Answer with its output only.',
                }
            ]
        }
    )
    print(result['messages'][-1].text)
finally:
    backend.destroy()

Run it:

python agent.py

The agent writes /workspace/hello.py with write_file, runs python hello.py with execute and answers with the output. The Python version varies:

Python 3.13.18

The first tool call creates the computer and waits until it is ready.

Clean up

The finally block deletes the computer when the agent is done, even when the call throws. nevia ls confirms the computer is gone.

To keep the computer between runs, skip destroy(). The sandbox name names the computer, so a later program that builds NeviaSandbox with the same name finds the same computer, files included. Call destroy() from that program when you are done. To reach a computer by its ID instead, pass computer=.

How the sandbox maps to a computer

NeviaSandbox is a deepagents sandbox backend, so create_deep_agent() gives the agent deepagents' own tools. For a plain LangGraph agent, pass FilesystemMiddleware(backend=backend) from deepagents.middleware to create_agent(). The adapter adds the options image, env for environment variables stored on the computer, working_dir, timeout, max_output_bytes and capture_offload.

Two sandboxes with the same name share one computer, even across processes. Without name or computer, each sandbox creates a computer with a generated name. image and env apply only when the adapter creates the computer. Commands and relative paths start in /workspace, which the adapter creates. Pass working_dir to change it.

stop() sleeps the computer and the next call wakes it with its files intact. A sleeping computer's disk still counts toward storage until destroy() deletes it. close() closes the sandbox's HTTP client and leaves the computer as it is.

Commands run in the foreground with direct exec, in bash when the image has it. A command stops after 30 minutes unless you pass another timeout. Each output stream keeps its last 64 KiB, and max_output_bytes sets another cap. A truncated answer says so. The image needs no Python of its own.

Every method has an async form with an a prefix, such as aexecute and adestroy, so agent.ainvoke() works too. The async forms run the sync method in a worker thread.

Limitations

These add to the SDK's Limits and workarounds.

  • No background commands. A command must end before the tool answers. Redirect long output to a file and read parts of it.
  • Large results go to a file. capture_offload is on by default, so deepagents saves a large result in /large_tool_results on the computer and returns a preview. If the image user can't write there, pass capture_offload=False.
  • Timeouts top out at 3600 seconds. A larger timeout makes execute answer Error: Nevia could not run the command with timeout_seconds is above 3600 in the message. timeout=0 removes the command timeout, but the session still ends after one hour.
  • Cancelling doesn't stop the command. Cancelling aexecute returns at once and frees its thread, but the command can keep running on the computer.
  • The sandbox takes a sync client. nevia= accepts a Nevia and raises TypeError for an AsyncNevia.

On this page