5 minute setup

Trace an OpenAI Agents run

Aletheia is a focused trace processor for the OpenAI Agents SDK. It maps agent, model, tool, handoff, guardrail, and MCP spans into inspectable executions.

Install the adapter

Add the OpenAI Agents SDK and the Aletheia trace processor to your agent application.

pnpm add @openai/agents @avinash27/aletheia

Create a project key

Open API keys in your project settings. Keys are project-scoped and shown once.

ALETHEIA_API_KEY=al_live_replace_me

Register the processor

Aletheia is added as a trace destination. Duration, usage, and cost are rolled up automatically; the optional OpenAI key adds evidence-based decision events and is never exported.

import { addTraceProcessor } from "@openai/agents";
import { createAletheiaTraceProcessor } from "@avinash27/aletheia";

addTraceProcessor(createAletheiaTraceProcessor({
  apiKey: process.env.ALETHEIA_API_KEY!,
  openaiApiKey: process.env.OPENAI_API_KEY,
  captureContent: false,
}));

What happens next

The processor batches trace events and flushes the completed execution when the Agents SDK ends the trace. Open Executions to inspect its timeline and causal graph.

Open your workspace