Skip to content

Home

Jump to bottom
jshotwell edited this page Feb 22, 2026 · 1 revision

AIR Blackbox Wiki

Welcome to the official wiki for AIR Blackbox — the open-source flight recorder for AI agents.

What is AIR Blackbox?

AIR Blackbox is an observability and trust layer for AI agents. It sits between your agent and any LLM API, recording every prompt, response, tool call, and decision — so you always know what your agent did and why.

Think of it like a flight data recorder, but for AI. When something goes wrong (or right), you have the full trace.

Key capabilities:

  • Full episode recording — every LLM call, tool invocation, and response, captured end-to-end
  • Trust scoring — evaluate agent outputs against configurable trust policies before they execute
  • OpenAI-compatible Gateway — drop-in proxy, one base_url change and you're recording
  • Distributed tracing — OpenTelemetry-native, traces ship to Jaeger out of the box
  • Framework agnostic — works with any agent that speaks the OpenAI API (LangChain, CrewAI, AutoGen, plain Python)

Architecture

Your Agent
    │
    ▼
AIR Gateway  ←──── Trust Plugin (policy evaluation)
    │
    ▼
Episode Store  ──── OpenTelemetry traces ──── Jaeger
    │
    ▼
LLM API (OpenAI, Anthropic, etc.)

Components:

  • AIR Gateway — OpenAI-compatible proxy that intercepts all LLM traffic. One base_url change connects your agent.
  • Episode Store — Persistent store for full agent episodes. Every prompt, tool call, and response is saved.
  • Trust Plugin — Pluggable policy engine that evaluates agent outputs before they reach tools or users.
  • Jaeger — Distributed tracing UI. Shipped as part of the Docker Compose stack.

Quickstart

Prerequisites

  • Docker + Docker Compose
  • make

1. Clone the repo

git clone https://github.com/airblackbox/air-platform.git
cd air-platform

2. Start the stack

make up

This starts the Gateway, Episode Store, and Jaeger.

3. Point your agent at the Gateway

Change your base_url to the AIR Gateway instead of hitting OpenAI directly:

from openai import OpenAI

client = OpenAI(
    api_key="your-openai-key",
    base_url="http://localhost:8080/v1"  # AIR Gateway
)

That's it. Every call is now recorded.

4. View traces in Jaeger

Open http://localhost:16686 and select the air-gateway service to see your agent's traces.

Wiki Pages

Page Description
Architecture Deep dive into each component
Quickstart Step-by-step setup guide
Trust Plugin How to configure trust policies
Framework Integrations LangChain, CrewAI, AutoGen examples
Episode Store How episodes are stored and queried
FAQ Common questions and troubleshooting

Contributing

We welcome contributions! Good starting points:

  • Check the good first issue label on GitHub Issues
  • Join the conversation in Discussions
  • Read the contributing guidelines in the repo root

Links

Clone this wiki locally