pyox-agents 0.2.0

The fastest, lightest way to build AI agents in Python.
A small Python API on top of a Rust core that runs the whole agent loop.

Documentation · Quickstart · Benchmarks · Examples

You write agents in plain Python: a model, instructions and tools. Rust does the rest: HTTP, streaming, JSON parsing, tool dispatch and the loop that ties them together. The result is an agent library with no Python dependencies that imports and builds an agent in 0.13 s (others: 1.5 to 3.2 s), and spends its time waiting on the model, not on itself.

Against seven popular agent frameworks, on the same tasks and the same fake model server:

_{One agent run with one tool call, 500 runs per library, 100 at once for throughput. The model answers instantly, so this is each library's own overhead. Compared: pydantic-ai, OpenAI Agents SDK, Microsoft Agent Framework, LangGraph, LangChain, LlamaIndex and Agno. Method, every number and how to reproduce them.}

Quickstart

uv add pyox-agents          # or: pip install pyox-agents
export OPENAI_API_KEY=sk-...

import asyncio

from pyox_agents import Agent, TextDelta, tool


@tool
def get_weather(city: str) -> str:
    """Get the current weather in a city."""
    return f"Sunny in {city}"


agent = Agent(model="gpt-5-mini", instructions="Be concise.", tools=[get_weather])


async def main() -> None:
    async for event in agent.execute("Weather in Vigo?"):
        if isinstance(event, TextDelta):
            print(event.text, end="", flush=True)


asyncio.run(main())

The schema of get_weather comes from its type hints and docstring. Events (TextDelta, ToolStarted, ToolFinished, RunFinished) are typed objects built in Rust. Don't need streaming? result = await agent.run("...") returns the final event, with result.text, result.usage and result.messages.

Prebuilt wheels cover Linux, macOS and Windows on Python 3.11 and newer.

Drop to Rust when Python is the bottleneck

Tools, hooks and history stores can also be written in Rust, in your own package. The model calls them without going through Python at all; the argument schema is generated from the struct:

/// Count the words in a text.
#[derive(Deserialize, JsonSchema)]
struct CountWords {
    /// The text to count words in.
    text: String,
}

impl RustTool for CountWords {
    const NAME: &'static str = "count_words";

    fn run(self) -> Result<String, String> {
        Ok(self.text.split_whitespace().count().to_string())
    }
}

import fast_tools  # your Rust package, built with maturin

agent = Agent(model="gpt-5-mini", tools=[fast_tools.count_words])

Start from examples/rust_tool_package, or read Tools.

What's included

Small surface, the features production agents need:

How it works

Python                                Rust
Agent(model, instructions, tools) ──► Engine      config shared by all runs
agent.execute(prompt)             ──► Run         history + bounded event queue
async for event in run            ◄── agent loop  request → stream → tools → repeat
(or `for`, with agent.execute_sync)     ├── one adapter file per API (Chat Completions, Responses)
                                        ├── sync Python tools on threads, async ones on your loop
                                        └── Rust tools called directly, no Python involved

One Agent serves any number of concurrent runs. The Rust code is written to be read by Python developers: small files, plain names and comments on every Rust-specific idea. Start at src/lib.rs.

For coding agents

skills/pyox-agents is an Agent Skill that teaches Claude Code, Codex and other agents that read SKILL.md how to build with pyox-agents, including Rust tools, hooks and history stores:

npx skills add daniprol/pyox-agents

Agents working on this repository read AGENTS.md.

Status

pyox-agents is young (0.x) and its API may still change before 1.0. Anthropic and Gemini adapters are next. Issues and pull requests are welcome: see CONTRIBUTING.md.

Inspired by pi. MIT license.