Skip to content
telemetry.dev
Esc
↑↓navigate↵open⌘Jpreview
On this page

OpenAI Agents SDK

Trace TypeScript OpenAI Agents SDK runs, model calls, tool calls, and sandbox commands with their exit codes.

@telemetry-dev/openai-agents sends the runs of the TypeScript OpenAI Agents SDK to telemetry.dev: the agents and their turns, each model call with its token usage, each tool call, and each command that a sandbox agent ran, with its exit code.

The package is a trace processor for the Agents SDK. It reads the spans the SDK already records, so you don’t change your agents or tools.

Install

npm install @telemetry-dev/openai-agents @openai/agents
pnpm add @telemetry-dev/openai-agents @openai/agents
yarn add @telemetry-dev/openai-agents @openai/agents
bun add @telemetry-dev/openai-agents @openai/agents

The package supports @openai/agents 0.22.0 and later 0.x releases, and needs Node.js 22 or later, the Agents SDK’s minimum.

Set the API key

Create a project at telemetry.dev, then create an API key on the project’s Setup page. Set it where your app runs:

export TELEMETRY_DEV_API_KEY=td_live_...
export TELEMETRY_DEV_ENVIRONMENT=development
export OTEL_SERVICE_NAME=support-agent

Without an API key, the processor does nothing.

Add the processor

Register the processor once, before the first run:

import { addTraceProcessor, Agent, run } from "@openai/agents";
import { telemetryDevProcessor } from "@telemetry-dev/openai-agents";

addTraceProcessor(telemetryDevProcessor());

const agent = new Agent({ name: "Assistant", instructions: "Answer briefly." });
await run(agent, "What is OpenTelemetry?");

addTraceProcessor keeps the Agents SDK’s default exporter, so traces also reach the OpenAI Traces dashboard. To send them only to telemetry.dev, replace the default exporter instead:

import { setTraceProcessors } from "@openai/agents";
import { telemetryDevProcessor } from "@telemetry-dev/openai-agents";

setTraceProcessors([telemetryDevProcessor()]);

setTraceProcessors is also how you keep content away from OpenAI. With addTraceProcessor, the OpenAI exporter still receives tool arguments and results, Chat Completions inputs and outputs, sandbox commands and working directories, and trace metadata.

Check the trace

Run your agent once and open Traces in your project. A run contains:

  • A root span named after the run’s workflow, Agent workflow unless you set workflowName, and a task {workflowName} span under it
  • An invoke_agent {name} span for each agent, and a turn N span for each of its turns
  • A chat {model} span for each model call, with its token usage, which telemetry.dev prices
  • An execute_tool {name} span for each tool call
  • Handoff, guardrail, and MCP tool-listing spans when the run has them

How runs group into traces:

  • A run is one trace by default.
  • A run that starts inside an active OpenTelemetry span, such as an HTTP request span, joins that span’s trace.
  • Runs that share a groupId share a session: the processor sends the groupId as the session ID (gen_ai.conversation.id). Runs inside the same propagateAttributes({ sessionId }) session (from @telemetry-dev/sdk) do too; a groupId takes precedence. Outside an active span, the runs of a session land in one trace per session, each run as a root span.
  • With telemetryDevProcessor({ sessionMode: "process" }), runs without a session of their own share the process’s generated session in the same way. Use this in a CLI or script that holds one conversation per process, not in a long-running server.

In short-lived runtimes such as serverless functions, flush at the end of each request:

import { getGlobalTraceProvider } from "@openai/agents";

await getGlobalTraceProvider().forceFlush();

The root span ends when the Agents SDK trace ends. A run that throws before the SDK ends its trace leaves it open, so the processor also ends the root when the run’s task or agent span ends with the error. forceFlush and shutdown of the trace provider end the root of every trace that has no open span, at the end of its last span, which covers a run that failed before its first span.

Trace sandbox agents

Sandbox runs need no extra setup. Each sandbox.* span of the Agents SDK, such as sandbox.create_session and sandbox.exec, arrives with:

Attribute Value
sandbox.operation The operation, such as create_session or exec
sandbox.backend The sandbox backend, such as e2b or modal, on the spans that create or resume a session

The exec_command and write_stdin tool spans get process.exit.code once the command has exited. A command that exits with a non-zero code is not marked as an error, because many commands, such as grep, exit non-zero without failing.

Control captured content

The processor takes the init() options of @telemetry-dev/sdk. Use captureInput and captureOutput to keep content out of telemetry.dev, and mask to redact it:

addTraceProcessor(
  telemetryDevProcessor({
    captureInput: false,
    captureOutput: false,
  }),
);

These count as content:

  • Model inputs and outputs
  • Tool arguments and results
  • The command and working directory of sandbox.exec, in process.command_line and process.working_directory

With capture off, telemetry.dev still receives span names and timing, model names, response IDs, token usage, turn numbers, agent, tool, handoff, and guardrail names, each agent’s tools, handoffs, and output type, whether a guardrail triggered, the MCP server of a tool call and the number of tools an MCP server listed, exit codes, sandbox backends, error types, the session ID (such as the run’s groupId, a propagateAttributes() session, or the process session), the user ID and metadata of propagateAttributes(), the Agents SDK trace ID, and the string, number, and boolean values of trace metadata and of the data of custom spans. Trace metadata, custom span data, and propagateAttributes() metadata do not go through mask.

Keep the Agents SDK’s traceIncludeSensitiveData on, which is its default. With it off, the SDK leaves token usage and tool output off its spans, and the Responses API model leaves off the model name too, so telemetry.dev cannot price model calls or read exit codes. Turn content off with captureInput and captureOutput instead.

Don’t also instrument the OpenAI client

The processor already records each model call as a chat span. Don’t also instrument the OpenAI client that the Agents SDK uses with @telemetry-dev/openai: neither a client wrapped with wrapOpenAI() and passed to setDefaultOpenAIClient, nor instrumentOpenAI(), which instruments every client in the process. Each model call would be recorded and priced twice.

Options

telemetryDevProcessor() accepts every init() option of @telemetry-dev/sdk. The variables you are most likely to set:

Variable Default Description
TELEMETRY_DEV_API_KEY None Ingest API key. Without a key, the processor does nothing.
TELEMETRY_DEV_BASE_URL https://api.telemetry.dev Ingest base URL
TELEMETRY_DEV_ENVIRONMENT production Environment on exported telemetry
OTEL_SERVICE_NAME SDK default Service name

The first processor created in a process sets up the SDK, and later processors ignore their options. Pass SDK options to the processor rather than calling init() yourself: the processor replaces a client that an earlier init() call made.

Limitations

The Agents SDK shuts the trace provider down on SIGTERM, SIGINT, and unhandled rejections. The processor then ends every open span so nothing is lost if the process exits. A model call that was in progress at that moment is sent without its token usage.

For the package source and changelog, see @telemetry-dev/openai-agents on GitHub.

Last updated on November 20, 2026

Was this page helpful?