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.
agno3.1 or later on 3.- An API key for the model provider. The quick start uses Anthropic, so it
needs
ANTHROPIC_API_KEY. - The
neviaCLI, signed in withnevia 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 -xzThen 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.whlName 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.pyThe 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.18The 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()andprint_response()log an error that namesarun()and the agent doesn't run. Usearun(),aprint_response()or AgentOS. - Timeouts top out at 3600 seconds. A larger
timeout_secondsargument 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.