Skip to content

Home

Jump to bottom
Jason Shotwell edited this page Mar 12, 2026 · 1 revision

AIR Blackbox Gateway Wiki

Welcome to the AIR Blackbox Gateway wiki — the central knowledge base for the AI governance control plane.

AIR Blackbox records every LLM call, tool invocation, and agent decision as a tamper-proof, replayable trace. This wiki covers installation, architecture, configuration, compliance, and more.

Table of Contents

Getting Started

Prerequisites

  • Python 3.9+
  • Docker & Docker Compose (for full gateway stack)
  • An LLM provider API key (e.g., OpenAI)

Quick Install

pip install air-blackbox

30-Second Demo

air-blackbox demo

This generates 10 sample AI agent records across 4 models and 3 providers, complete with PII detection, prompt injection scanning, and HMAC-SHA256 chain verification.

Architecture Overview

AIR Blackbox acts as a reverse proxy and control tower for AI agents. All AI traffic flows through the gateway where it is recorded, analyzed, and made traceable.

Agents / Apps
      │
      ▼
AIR Blackbox Gateway
      │
  ┌─────────────┐
  │  Governance  │
  │  Security    │
  │  Compliance  │
  └─────────────┘
      │
      ▼
Agent Runtime (LLMs + Tools)
      │
      ▼
Observability + Replay

Key Layers

  1. Entry Layer — Agents, SDKs, or applications send requests through the gateway.
  2. Safety & Governance Layer — Policy engine, prompt vault, security scanner, and compliance checker.
  3. Execution Layer — Orchestrates LLM calls, tools, and external APIs.
  4. Observability Fabric — Trace regression, agent episode store, runtime AI-BOM, and OpenTelemetry traces.
  5. Developer Interface — Replay agent decisions, inspect prompt chains, and audit policy decisions.

Installation & Setup

Option 1: Wrap Your OpenAI Client (2 Lines)

from air_blackbox import AirBlackbox

air = AirBlackbox()
client = air.wrap(openai.OpenAI())

Option 2: LangChain Trust Layer

from air_blackbox.trust.langchain import AirLangChainHandler

chain.invoke(input, config={"callbacks": [AirLangChainHandler()]})

Option 3: Auto-Detect Any Framework

from air_blackbox import AirTrust

trust = AirTrust()
trust.attach(your_agent)

Option 4: Full Gateway Stack (Docker)

git clone https://github.com/airblackbox/gateway.git
cd gateway
cp .env.example .env   # add your OPENAI_API_KEY
docker compose up

Then point any OpenAI-compatible client at http://localhost:8080/v1.

CLI Commands

Command Description
air-blackbox demo Generate sample records and explore features
air-blackbox replay Full trace reconstruction with HMAC verification
air-blackbox discover AI-BOM generation and shadow AI detection
air-blackbox comply -v EU AI Act compliance checks (20 checks, Articles 9–15)
air-blackbox export Signed evidence bundle for auditors

Trust Layers

Non-blocking callback handlers that observe and log agent activity without controlling or blocking execution.

Framework Install Status
LangChain / LangGraph pip install "air-blackbox[langchain]" ✅ Full
OpenAI SDK pip install "air-blackbox[openai]" ✅ Full
CrewAI pip install "air-blackbox[crewai]" 🔧 Scaffold
AutoGen pip install "air-blackbox[autogen]" 🔧 Scaffold
Google ADK pip install "air-blackbox[adk]" 🔧 Scaffold

Every trust layer includes:

  • PII Detection — Emails, SSNs, phone numbers, credit cards in prompts
  • Prompt Injection Scanning — 7 patterns (instruction override, role hijack, etc.)
  • Audit Logging — Every LLM call + tool invocation as .air.json
  • Non-blocking — If logging fails, your agent keeps running

EU AI Act Compliance

Enforcement deadline: August 2, 2026 — Penalties up to €35M or 7% of global turnover.

air-blackbox comply -v checks 20 controls across 6 articles:

Article Coverage Detection
Art. 9 — Risk Management Risk assessment, active mitigations HYBRID
Art. 10 — Data Governance PII in prompts, data vault, governance docs AUTO + HYBRID
Art. 11 — Technical Documentation README, AI-BOM, model cards AUTO + HYBRID
Art. 12 — Record-Keeping Event logging, HMAC chain, traceability 100% AUTO
Art. 14 — Human Oversight Human-in-the-loop, kill switch AUTO + MANUAL
Art. 15 — Robustness & Security Injection protection, error resilience AUTO + MANUAL

Shadow AI Detection & AI-BOM

Discover unapproved AI models and services in your environment:

air-blackbox discover                                    # See everything your agents use
air-blackbox discover --init-registry                    # Lock down approved models
air-blackbox discover --approved=approved-models.json    # Flag unapproved models
air-blackbox discover --format=cyclonedx -o aibom.json   # CycloneDX AI-BOM export

Configuration Reference

Variable Default Description
LISTEN_ADDR :8080 Gateway listen address
PROVIDER_URL https://api.openai.com Upstream LLM provider
VAULT_ENDPOINT localhost:9000 MinIO/S3 endpoint
VAULT_ACCESS_KEY minioadmin S3 access key
VAULT_SECRET_KEY minioadmin S3 secret key
VAULT_BUCKET air-runs S3 bucket name
OTEL_EXPORTER_OTLP_ENDPOINT localhost:4317 OTel collector gRPC
RUNS_DIR ./runs AIR record directory
TRUST_SIGNING_KEY (none) HMAC-SHA256 signing key

File Structure

gateway/
├── cmd/              # Go proxy binary + replayctl CLI
├── collector/        # Go gateway core
├── pkg/              # Go shared packages (trust, audit chain)
├── sdk/              # Python SDK (pip install air-blackbox)
│   └── air_blackbox/
│       ├── cli.py
│       ├── gateway_client.py
│       ├── compliance/
│       ├── aibom/
│       ├── replay/
│       ├── export/
│       └── trust/
├── deploy/           # Docker Compose + Prometheus + Makefile
├── docs/             # Documentation + quickstart
└── examples/         # Demo apps

Related Projects

  • air-platform — Docker Compose stack: Gateway + Jaeger + Prometheus in one command
  • air-blackbox-mcp — MCP server for EU AI Act compliance scanning in Claude Desktop, Cursor, or any MCP client

Contributing

We welcome contributions in AI agent tracing, governance tooling, and agent safety. Current priorities:

  • Trust layers for CrewAI, AutoGen, and Google ADK
  • CycloneDX AI-BOM enrichment (training data provenance, model weights origin)
  • Latency benchmarks for trust layer overhead
  • Documentation and integration examples

See CONTRIBUTING.md for guidelines.

License

Apache-2.0 — See LICENSE for details.

Clone this wiki locally