Tracing

@deepagents/context/tracing is a subpath export that provides a TelemetryIntegration for the AI SDK. Pass it to experimental_telemetry and every generateText / streamText call produces an OpenAI trace with nested spans for steps, tool calls, and handoffs — shipped to the OpenAI Traces ingest endpoint (or any compatible endpoint).

Assuming sandbox and context have already been constructed (see Sandbox and Agent):

import { groq } from '@ai-sdk/groq';
import { agent } from '@deepagents/context';
import { createOpenAITracesIntegration } from '@deepagents/context/tracing';

const telemetry = createOpenAITracesIntegration({
  apiKey: process.env.OPENAI_API_KEY,
  workflowName: 'support-agent',
});

const assistant = agent({
  name: 'support',
  sandbox,
  context,
  model: groq('gpt-oss-20b'),
  experimental_telemetry: { integrations: [telemetry] },
});

Spans are queued by a BatchTraceProcessor, shipped in batches via an OpenAITracesExporter, and retried with exponential backoff plus jitter on 5xx responses.

createOpenAITracesIntegration(options)

Returns a TelemetryIntegration compatible with the AI SDK's experimental_telemetry hook points. It listens for onStart, onStepStart, onStepFinish, onToolCallStart, onToolCallFinish, and onFinish events and emits one trace per run with nested spans.

Set the env var OPENAI_AGENTS_DISABLE_TRACING=1 to return an empty integration — handy for disabling tracing in tests without changing call sites.

Trace Shape

Each run produces one trace with one root agent span and zero or more nested spans:

When multiple runs are open concurrently (nested agents, asAdvisor), events are routed to the correct run by matching response.id, toolCall.toolCallId, experimental_context, metadata, abortSignal, functionId, model, and an input fingerprint — in descending priority. When exactly one run is open, it gets the event directly. When no run is open, the event is dropped rather than attached to the wrong trace.

Per-Span Wire Contracts

The ingest endpoint is strict about input/output shapes. Before shipping, the exporter rewrites each span to match:

FunctionSpanData and TranscriptionSpanData get their input / output JSON.stringifyed on the way out — sending them as objects or arrays causes a 400 from the API. The GenerationSpanData path keeps arrays. All of this lives in OpenAITracesExporter so processors and handlers can work with native objects until export time.

Trace-level metadata is also normalized at export time. The wire payload sends metadata as Record<string, string>; non-string values are JSON-stringified and empty metadata objects are omitted.

OpenAITracesExporter

A standalone exporter you can instantiate if you want to replace the default pipeline:

import { OpenAITracesExporter } from '@deepagents/context/tracing';

const exporter = new OpenAITracesExporter({
  apiKey: process.env.OPENAI_API_KEY,
  organization: 'org-123',
  maxRetries: 5,
  baseDelayMs: 500,
  maxDelayMs: 15000,
});

await exporter.export(items, abortSignal);

Retries use exponential backoff with 10% jitter. OpenAIExportError carries both the HTTP status code and the raw response body for debugging.

BatchTraceProcessor

The default processor queues spans in memory, flushes on a timer or when the queue hits a threshold, and calls exporter.export(batch).

Pass custom batch options on the integration to tune it:

createOpenAITracesIntegration({
  batch: { maxBatchSize: 32, scheduleDelayMs: 2000 },
});

Custom Processors

TracingProcessor is a minimal interface — start, trace/span lifecycle callbacks, flush, shutdown. Swap the default batch processor for your own implementation (e.g. to mirror spans to stdout during local development):

import type { TracingProcessor } from '@deepagents/context/tracing';

const consoleProcessor: TracingProcessor = {
  onSpanEnd(span) {
    console.log('[trace]', span.span_data.type, span.id);
  },
};

createOpenAITracesIntegration({ processor: consoleProcessor });

Pass an array to run multiple processors — they're combined via CompositeTraceProcessor.

Usage Normalization

normalizeUsage flattens the AI SDK's LanguageModelUsage into the OpenAI trace schema:

• input_tokens, output_tokens on the span usage.
• details.input_token_details (no-cache, cache-read, cache-write).
• details.output_token_details (text, reasoning).
• details.reasoning_tokens, details.cached_input_tokens when present.
• details.raw — the provider's raw usage payload.

The same function is used inside the root span's total_usage metadata on finish.

Disabling Sensitive Data

Set includeSensitiveData: false (or env OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=0) to strip inputs/outputs from generation and function spans. Usage counts, model names, tool names, and errors are still shipped. The tracing shape is identical — only the payload bodies drop.

Related

• Agent — experimental_telemetry on the agent options
• Chat Function — Streaming entry point that forwards telemetry