pyox-agents¶

The fastest, lightest way to build AI agents in Python: a small Python API on top of a Rust core. Inspired by pi.

You define the agent (model, instructions, tools) in Python and iterate over its events. Rust does the heavy lifting: HTTP, streaming decoding, JSON parsing and the agent loop.

Install¶

uv add pyox-agents  # or: pip install pyox-agents

Prebuilt wheels cover Linux, macOS and Windows on Python 3.11 and newer, and pyox-agents has no Python dependencies.

Your first agent¶

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.stream("Weather in Vigo?"):
        if isinstance(event, TextDelta):
            print(event.text, end="", flush=True)


asyncio.run(main())

export OPENAI_API_KEY=sk-...
uv run first_agent.py

The model calls get_weather, gets "Sunny in Vigo" back and streams its answer.

Don't need streaming? await agent.run(...) runs to the end and returns the final event:

result = await agent.run("Weather in Vigo?")
print(result.text)

Next¶

• Streaming: the events of a run, how it ends (and run.stop()), and grouping streamed text.
• Tools: Python functions and your own Rust tools.
• Structured output: answers as dataclasses, TypedDicts or pydantic models.
• Images and files: send pictures and PDFs in a prompt, and get them from tools.
• History: continue conversations and store them in a database.
• MCP servers: give an agent the tools of any MCP server.
• Hooks: watch or change a run at fixed points.
• Tracing: OpenTelemetry spans and metrics for runs, model requests and tool calls.
• Errors: what happens when a tool fails, and the errors a run raises.
• Client: API keys, other servers, timeouts and retries.
• Using a coding agent? Install the pyox-agents skill with npx skills add daniprol/pyox-agents.
• Complete, runnable scripts are in examples/.