# Agno

> Give an Agno agent a Nevia computer as its tools, so its commands 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/agno

The Agno adapter gives an [Agno](https://www.agno.com) 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](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 Agno's toolkit contract, so
[Agno's toolkit docs](https://docs.agno.com) 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](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-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
```

**pip**

```bash
pip install "./vendor/nevia-sdk-0.1.0/python/nevia_agno-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 the Anthropic client, so the quick start can name
an Anthropic model. The adapter installs Agno 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
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:

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

```text
Python 3.13.18
```

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

## 4. 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](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.
* **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.
