Agent frameworks

Pydantic AI

Give a Pydantic AI agent a Nevia computer as its workspace, so its shell and file tools run on the computer

The Pydantic AI adapter gives a Pydantic AI 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 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 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 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 ./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.

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:

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:

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:

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

  • 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.

On this page