AgentIO

A trace visualization tool for the OpenAI Agents SDK, inspired by trackio.

Features

• 📊 Local trace collection - Store traces in SQLite for offline analysis
• 🌐 Remote mode - Send traces to a central AgentIO server
• 📤 Export capabilities - Export traces to JSON, CSV, or Parquet
• 🔍 Auto-naming - Human-readable trace names with collision handling
• 🔄 Resume modes - Control trace continuation behavior
• 🛡️ Thread-safe - Safe for multi-threaded applications

Installation

pip install agentio

For additional features:

# Remote trace sending
pip install agentio[remote]

# Run as server
pip install agentio[server]

# Export to parquet
pip install agentio[export]

Quick Start

Basic Usage

import agentio
from agents import Agent

# Initialize local tracing
agentio.init(project="my_assistant")

# Your agent code - traces automatically captured
agent = Agent(...)
response = agent.run("Help me with...")

# Export traces
agentio.export("traces.json")

Remote Server Mode

import agentio

# Send traces to remote server
agentio.init(
    project="production_bot",
    server_url="https://traces.mycompany.com",
    token="secret_token"
)

# Traces automatically sent to server
agent.run("...")

Run as Trace Server

# Start trace collection server
agentio serve --port 8080 --token my_secret_token

CLI Commands

• agentio serve - Run as trace collection server
• agentio export - Export traces to file
• agentio show - Display dashboard (UI not implemented yet)

API Reference

agentio.init()

Initialize AgentIO tracing.

Parameters:

• project (str): Project name for grouping traces
• name (str, optional): Trace name (auto-generated if not provided)
• server_url (str, optional): Remote server URL for trace collection
• db_path (str, optional): Path to SQLite database
• token (str, optional): Auth token for remote server
• resume (str): Resume mode - "must", "allow", or "never"
• replace_default (bool): Replace OpenAI's default processor

agentio.export()

Export traces to file.

Parameters:

• output_path (str): Output file path
• format (str): Export format - "json", "csv", or "parquet"
• project (str, optional): Project to export

agentio.serve()

Run AgentIO as a standalone server.

Parameters:

• host (str): Host to bind to
• port (int): Port to bind to
• db_path (str, optional): Database path
• auth_token (str, optional): Authentication token

License

MIT