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/agentspnpm add @telemetry-dev/openai-agents @openai/agentsyarn add @telemetry-dev/openai-agents @openai/agentsbun add @telemetry-dev/openai-agents @openai/agentsThe 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 workflowunless you setworkflowName, and atask {workflowName}span under it - An
invoke_agent {name}span for each agent, and aturn Nspan 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
groupIdshare a session: the processor sends thegroupIdas the session ID (gen_ai.conversation.id). Runs inside the samepropagateAttributes({ sessionId })session (from@telemetry-dev/sdk) do too; agroupIdtakes 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, inprocess.command_lineandprocess.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.