# Pydantic AI

> Give a Pydantic AI agent a Nevia computer as its workspace, so its shell and file tools 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/pydantic-ai

The Pydantic AI adapter gives a [Pydantic AI](https://ai.pydantic.dev) agent a
workspace on a Nevia computer. The agent's shell and file 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 Pydantic AI's workspace
contract, so [Pydantic AI's docs](https://ai.pydantic.dev) cover the tools and
options. This page covers only what is particular to Nevia.

## Prerequisites

You need:

* Python 3.11 or later.
* `pydantic-ai-slim` 2.52 or later on 2.
* `pydantic-ai-harness` for the shell and file tools.
* 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 ./vendor/nevia-sdk-0.1.0/python/nevia_pydantic_ai-0.1.0-py3-none-any.whl \
    ./vendor/nevia-sdk-0.1.0/python/nevia-0.1.0-py3-none-any.whl \
    pydantic-ai-harness "pydantic-ai-slim[anthropic]"
```

**pip**

```bash
pip install ./vendor/nevia-sdk-0.1.0/python/nevia_pydantic_ai-0.1.0-py3-none-any.whl \
    ./vendor/nevia-sdk-0.1.0/python/nevia-0.1.0-py3-none-any.whl \
    pydantic-ai-harness "pydantic-ai-slim[anthropic]"
```

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 the Anthropic client, so the quick start can name
an Anthropic model.

## 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
import anyio
from pydantic_ai import Agent
from pydantic_ai_harness.filesystem import FileSystem
from pydantic_ai_harness.shell import Shell

from nevia_pydantic_ai import NeviaWorkspace

workspace = NeviaWorkspace(image='docker.io/library/python:3.13-slim')

agent = Agent(
    'anthropic:claude-sonnet-5-5',
    instructions='You write and run code on your computer. Use the tools and keep answers short.',
    capabilities=[workspace, Shell(), FileSystem()],
)


async def main():
    async with workspace.backend() as backend:
        try:
            result = await agent.run(
                'Write hello.py that prints the Python version, then run it. Answer with its output only.',
                workspace=backend,
            )
            print(result.output)
        finally:
            await backend.destroy()


anyio.run(main)
```

Run it:

```bash
python agent.py
```

The agent writes `hello.py` in the computer's home directory with `write_file`,
runs `python hello.py` with `run_command` 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
run throws. `nevia ls` confirms the computer is gone.

A run never deletes its computer. Without an explicit backend, each run creates
one and `result.workspace.ref` names it. Pass that reference as `workspace=` to
a later run to reach the same computer, files included. Call
`await workspace.destroy(ref)` when you are done.

## How the workspace maps to a computer

`NeviaWorkspace` is a Pydantic AI capability. It goes in `capabilities` beside
the harness `Shell()` and `FileSystem()`, so the agent uses their tools.
`NeviaWorkspace` takes `image`, `name`, `env` for environment variables stored
on the computer, `working_dir` and `nevia` for a client to share between runs.

A run without a workspace reference creates a computer with the given `name`
or a generated one. Names are unique per Nevia workspace. A run with a reference
attaches to that computer and wakes it if it sleeps. `image`, `name` and `env`
apply only when the adapter creates the computer.

Commands start in the image user's home directory unless you pass
`working_dir`, which the adapter creates on a new computer.
`NeviaBackend(user='node')` runs the commands as another image user.

Ending a run closes the client the run opened and leaves the computer as it
is. `backend.destroy()` and `workspace.destroy(ref)` delete it.

Commands run in the foreground with direct exec and keep the last 64 KiB of
each output stream. A command that writes more raises
`WorkspaceOutputLimitError` with the retained output. A command that outlasts
its timeout raises `WorkspaceTimeoutError` with the partial output.

## 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.
* **Timeouts top out at 3600 seconds.** A larger timeout raises a `NeviaError`
  with the code `validation_failed` before the command runs.
* **Cancelling doesn't stop the command.** Cancelling a run returns at once,
  but the command can keep running on the computer.
* **A bad key or image shows up in the run.** The adapter creates the computer
  on the first tool call, not when you build the agent, so the error comes back
  as a tool failure.
