Axio¶
Axio is a small asynchronous foundation for building LLM agent harnesses in Python. It provides the agent loop and explicit extension points for model transports, tools, context storage, permissions, and streamed events.
Axio is a library, not an application framework. Your code keeps control of sessions, input and output, resource lifetimes, persistence, observability, and deployment.
The canonical course. Each lesson fixes the next failure, from a text-only assistant to a tested multi-session harness with isolated execution.
Reference documentation for the agent, transports, tools, events, and context.
Write transports, tools, guards, and context stores.
Public classes, events, and methods.
The boundary Axio provides¶
flowchart TD
H[Your harness] -->|prompt + context| A[Agent loop]
A -->|one request| T[Transport]
T <--> L[LLM provider]
A -->|validated call| X[Async tools]
A <--> C[Context store]
A -->|typed events| H
The transport normalizes one provider request into typed events. The agent consumes those events, executes requested tools, appends results to context, and calls the transport again. Your harness consumes the same event stream and turns it into application behavior.
Start with Build an Agent Harness with Axio. One small harness grows through four causal stages:
give a text-only agent useful tools and enforce their boundaries;
make every action visible, persistent, and bounded in context;
isolate generated code and separate concurrent user sessions;
add runtime integrations, a product event protocol, and deterministic tests.
Design principles¶
- Explicit composition
Create an Agent from a transport and tools, then supply one context store per session. Dependencies remain visible in ordinary Python.
- Provider isolation
Provider-specific authentication, message encoding, streaming, and stop reasons stay behind CompletionTransport.
- Typed streaming
Text, reasoning, refusals, citations, tool requests, tool results, usage, and failures are observable while the turn runs. A payload axio has no type for is forwarded rather than dropped, so nothing a provider sends disappears on the way through.
- Application-owned state
Context is supplied by the caller. The same agent definition can serve many isolated sessions.
- Plain async tools
Tool handlers are async functions. Annotations become the input schema. Guards, runtime context, and concurrency limits are explicit.