# LangGraph

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

> Nevia is in early access for selected teams. The CLI installs with `curl -fsSL https://get.nevia.cloud | sh`, and the MCP server is at https://api.nevia.cloud/mcp. A person signs in once in the browser.
> Setup, sign-in and requesting access: [SKILL.md](https://nevia.cloud/SKILL.md). When Nevia fits and when it doesn't: [why.md](https://nevia.cloud/why.md).

> For the complete documentation index, see [llms.txt](https://nevia.cloud/llms.txt). This page's HTML version: https://nevia.cloud/docs/agent-frameworks/langgraph

The LangGraph adapter gives a [LangGraph](https://www.langchain.com/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](https://nevia.cloud/docs/reference/sdk/python.md) 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](https://docs.langchain.com) 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](https://nevia.cloud/docs/get-started/quickstart.md) shows how to install it.
* A Nevia key file for a service account with the **editor** role.
  [Use an automation key file](https://nevia.cloud/docs/guides/automation-key-file.md) shows how a
  workspace admin issues one.

## 1. Install the adapter

> **Invited testers only**
>
> The SDKs are in early access for invited testers. To ask for access, see
> [Request access to Nevia](https://nevia.cloud/docs/get-started/request-access.md).

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

```bash
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**

```bash
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
```

**pip**

```bash
pip install "./vendor/nevia-sdk-0.1.0/python/nevia_langgraph-0.1.0-py3-none-any.whl[anthropic]" \
    ./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.

## 2. Authenticate

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

```bash
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](https://nevia.cloud/docs/reference/sdk/python.md#client).

## 3. Give an agent a computer

Save this as `agent.py`:

```python
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:

```bash
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:

```text
Python 3.13.18
```

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

## 4. 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](https://nevia.cloud/docs/reference/sdk/limits.md).

* **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`.
