Legacy flight recorder

Compatibility notes for importing earlier trace bundles into the current evidence model.

The Flight Recorder streams public OpenAI Agents SDK trace and span objects into Engram’s Observe mode. It is a secondary trace processor: adding it does not replace the SDK’s default OpenAI exporter.

This endpoint is an ephemeral legacy demo transport. It does not provide durability, delivery guarantees, retention controls, or a production telemetry pipeline. Use the authenticated telemetry v2 ingestion path for durable data.

Connect

1. Open Observe, select Live, and start a recorder session.
2. Copy src/lib/traces/flight-recorder-client.ts into the instrumented agent project or expose the same helper from a shared package.
3. Use the endpoint and channel generated by Engram:

import { addTraceProcessor } from "@openai/agents";
import { createEngramTracingProcessor } from "./flight-recorder-client";

addTraceProcessor(createEngramTracingProcessor({
  endpoint: "https://your-engram-host/api/traces/live",
  channelId: "live-generated-in-the-ui"
}));

Local development remains unauthenticated when ENGRAM_INGEST_KEYS_JSON is empty. When ingest keys are configured, every GET and POST requires the raw token as a Bearer credential. The processor’s injectable fetch can add it:

addTraceProcessor(createEngramTracingProcessor({
  endpoint: "https://your-engram-host/api/traces/live",
  channelId: "live-generated-in-the-ui",
  fetch: (input, init) => {
    const headers = new Headers(init?.headers);
    headers.set("Authorization", `Bearer ${process.env.ENGRAM_INGEST_TOKEN}`);
    return fetch(input, { ...init, headers });
  }
}));

The processor implements onTraceStart, onTraceEnd, onSpanStart, onSpanEnd, forceFlush, and shutdown. It serializes only through the SDK’s public toJSON() methods and explicitly disables tracing API key persistence.

OpenAI’s Agents SDK documents custom processors as an additive way to receive traces and spans, and documents Trace.toJSON() and Span.toJSON() as the serialization surface:

• https://openai.github.io/openai-agents-js/guides/tracing/
• https://openai.github.io/openai-agents-js/openai/agents/interfaces/tracingprocessor/

Evidence boundary

• Generic model, agent, tool, guardrail, and handoff spans appear as execution evidence but do not animate memory.
• Native engram.memory events are labeled observed.
• Recognized memory tool calls are translated deterministically and labeled mapped.
• Engram does not infer hidden chain-of-thought or unrecorded memory operations.

Security and runtime limits

• Browser origins receive CORS access only when they exactly match an origin in ENGRAM_INGEST_ALLOWED_ORIGINS. There is no wildcard CORS fallback.
• When ENGRAM_INGEST_KEYS_JSON is configured, Bearer authentication is mandatory. Authenticated channels are isolated by tenant and project even if two clients choose the same public channel ID. Optional top-level or query tenantId and projectId claims must match the credential.
• In production, the endpoint returns unavailable unless ENGRAM_LEGACY_LIVE_RECORDER_ENABLED=true and ingest keys are configured.
• The built-in browser recorder uses EventSource, which cannot attach a Bearer header. Treat that flow as local development functionality; do not place raw ingest tokens in browser code or URL query strings.
• Credential-shaped keys and values are redacted before a live item reaches the browser and again before export.
• Live channels are in-memory, capped, and removed after inactivity. On serverless deployments a process restart can end a channel. This is an interactive demo transport, not a durable telemetry backend.
• Do not rely on this endpoint for production telemetry. Use telemetry v2 with durable storage, retention controls, and operational monitoring instead.