Agent frameworks

Agno

Give an Agno agent a Nevia computer as its tools, so its commands and file tools run on the computer

The Agno adapter gives an Agno agent a toolkit that runs each session on its own Nevia computer. The agent's run_command 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 Agno's toolkit contract, so Agno's toolkit docs cover the tools and options. This page covers only what is particular to Nevia.

Prerequisites

You need:

  • Python 3.11 or later.
  • agno 3.1 or later on 3.
  • 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-agno[anthropic] @ ./vendor/nevia-sdk-0.1.0/python/nevia_agno-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 the Anthropic client, so the quick start can name an Anthropic model. The adapter installs Agno 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:

import asyncio

from agno.agent import Agent
from agno.models.anthropic import Claude

from nevia_agno import NeviaTools


async def main():
    async with NeviaTools(image='docker.io/library/python:3.13-slim') as tools:
        agent = Agent(
            model=Claude(id='claude-sonnet-5-5'),
            tools=[tools],
            instructions='You write and run code on your computer. Keep answers short.',
        )
        try:
            response = await agent.arun(
                'Write hello.py that prints the Python version, then run it. Answer with its output only.',
                session_id='quickstart',
            )
            print(response.content)
        finally:
            await tools.destroy()


asyncio.run(main())

Run it:

python agent.py

The agent writes /workspace/hello.py 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 of the session creates the computer and waits until it is ready.

Clean up

The finally block deletes every computer the toolkit created when the agent is done, even when the call throws. async with then closes the toolkit's HTTP client. nevia ls confirms the computer is gone.

A run never deletes its computer. To keep the computer between runs, skip destroy(). The session ID names the computer, so a later run with the same session_id finds the same computer, files included, even from another process. Call await tools.destroy(session_id='quickstart') from that program when you are done.

How the toolkit maps to a computer

NeviaTools is an Agno Toolkit, so you pass it in tools and the agent calls run_command, read_file, write_file and list_files, plus expose_port for a public HTTPS URL to a port on the computer. NeviaTools takes image, env for environment variables stored on the computer, working_dir, timeout_seconds, max_output_chars, name_prefix and nevia for a client to share.

Each session gets its own computer, named name_prefix followed by a hash of the session ID. Pass computer_id to use one existing computer for every session. image and env apply only when the adapter creates the computer. Commands and relative paths start in /workspace, or in workspace under the home directory when /workspace isn't writable. Pass working_dir to change it.

The adapter wakes a sleeping computer on the next call. If someone deleted the computer, the next call reports that once and the call after it creates a new computer.

run_command runs in the foreground with direct exec, in bash when the image has it. A command stops after 120 seconds unless you pass another timeout_seconds. Each output stream keeps its last 64 KiB and a truncated result says (output truncated). max_output_chars caps the tool result.

A missing file or a deleted computer raises NeviaToolError, which Agno hands the model as a tool error. A nonzero exit code or a timeout comes back as a normal result.

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.
  • The tools are async only. run() and print_response() log an error that names arun() and the agent doesn't run. Use arun(), aprint_response() or AgentOS.
  • Timeouts top out at 3600 seconds. A larger timeout_seconds argument runs with 3600 and the constructor refuses a larger default.
  • Cancelling doesn't stop the command. Cancelling a run returns at once, but the command can keep running on the computer.

On this page