> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agno

> Give Agno agents shell-based filesystem access to any Mirage workspace using MirageToolkit.

[Agno](https://github.com/agno-agi/agno) is an agent framework that groups related tools into `Toolkit` classes. Mirage ships `MirageToolkit`, a toolkit backed by a `Workspace` instead of the host machine. The agent gets five shell-style tools (`execute`, `read`, `write`, `ls`, `grep`); mount RAM, S3, GDrive, Slack, etc. and the agent uses them through the same Agno API.

## Install

```bash theme={null}
uv add 'mirage-ai[agno]'
```

Requires `agno>=2.7.4`. The toolkit registers both sync and async variants through Agno's `tools` and `async_tools` parameters.

## Usage

```python theme={null}
import asyncio

from agno.agent import Agent
from agno.models.openai import OpenAIChat

from mirage import MountMode, RAMResource, Workspace
from mirage.agents.agno import MirageToolkit

ws = Workspace({"/data": RAMResource()}, mode=MountMode.WRITE)

agent = Agent(
    model=OpenAIChat(id="gpt-5.4-mini"),
    tools=[MirageToolkit(ws)],
    instructions=("You have access to a virtual filesystem via shell "
                  "tools. Use them to explore and read files."),
    markdown=True,
)


async def main() -> None:
    await ws.execute('echo "hello from mirage" | tee /data/hello.txt')
    await agent.aprint_response(
        "List all files under /data and show the contents of each one.")


asyncio.run(main())
```

## Tools

Every tool is registered as a sync + async pair under one name; Agno picks the async variant in `arun`/`aprint_response` and the sync variant otherwise.

| Tool                   | Mirage translation                                   |
| ---------------------- | ---------------------------------------------------- |
| `execute(command)`     | `await ws.execute(command)`, full shell with pipes   |
| `read(path)`           | `cat <path>`                                         |
| `write(path, content)` | `mkdir -p <parent>`, then `tee <path>` with `stdin=` |
| `ls(path="/")`         | `ls <path>`                                          |
| `grep(pattern, path)`  | `grep -r <pattern> <path>`                           |

## Exports

| Symbol                 | Purpose                                                                   |
| ---------------------- | ------------------------------------------------------------------------- |
| `MirageToolkit`        | Agno `Toolkit` exposing the 5 shell tools, backed by `Workspace.execute`. |
| `MIRAGE_SYSTEM_PROMPT` | Default system prompt describing the virtual filesystem.                  |
| `build_system_prompt`  | Compose the default prompt with mount info and extra instructions.        |

## Examples

* [`examples/python/agents/agno/agno_example.py`](https://github.com/strukto-ai/mirage/blob/main/examples/python/agents/agno/agno_example.py), `Agent` with `MirageToolkit` over a RAM workspace, sync and async.