Getting Started

Installation

Axio is distributed as a uv workspace. Clone the repository and sync dependencies:

git clone https://github.com/axio-agent/axio.git
cd axio
uv sync

To include optional packages (transports, tools, guards):

uv sync --all-extras

Minimal Agent

The smallest possible agent needs three things: a transport to talk to an LLM, a context store to hold conversation history, and an Agent to tie them together.

import asyncio
from axio import Agent, MemoryContextStore
from axio.testing import StubTransport, make_text_response

async def main() -> None:
    transport = StubTransport([
        make_text_response("Hello! I'm a stub agent."),
    ])
    context = MemoryContextStore()
    agent = Agent(
        system="You are a helpful assistant.",
        tools=[],
        transport=transport,
    )
    reply = await agent.run("Hi there!", context)
    print(reply)

asyncio.run(main())

Replace StubTransport with a real transport like OpenAITransport to connect to a live LLM. The agent loop, tool dispatch, and streaming all work the same way regardless of which transport you use — that’s the power of the protocol-driven design.

Adding Tools

Tools are Pydantic models. Define fields for parameters and implement __call__:

from axio import Tool, ToolHandler

class Greet(ToolHandler):
    """Greet someone by name."""
    name: str

    async def __call__(self) -> str:
        return f"Hello, {self.name}!"

agent = Agent(
    system="You are a helpful assistant.",
    tools=[Tool(name="greet", description="Greet someone", handler=Greet)],
    transport=transport,
)

Running the TUI

The axio-tui package provides a terminal UI built with Textual:

uv tool install "axio-tui[all]"
uv tool run axio
Axio TUI — terminal interface showing a conversation with tool calls

The TUI discovers available transports, tools, and guards automatically via the plugin system.

Next Steps