OpenAI Agents

Overview

OpenAI Agents is a lightweight framework for creating agentic workflows using agent swarms, handoffs, and tool use. Confident AI lets you trace and evaluate OpenAI Agents workflows with one line of code — call init() from confident-trace, Confident AI's OpenTelemetry-native tracing SDK, and your agents, tools, handoffs, and guardrails stay exactly as they are.

Auto-Instrument

1. Install Dependencies

   Run the following command to install confident-trace alongside the OpenAI Agents SDK:

   PythonTypeScript

   pip install 'confident-trace[openai-agents]' openai-agents

2. Set Your API Keys

   Get your Confident AI Project API key and set it as an environment variable, along with your OpenAI key:

   export CONFIDENT_API_KEY="<your-confident-project-key>"
   export OPENAI_API_KEY="<your-openai-key>"

3. Instrument OpenAI Agents

   Call init() once before running agents. It detects the Agents SDK automatically and hooks its tracing — there's no trace processor to register in your code.

   PythonTypeScript

   from agents import Agent, Runner
   from confident_trace import init, shutdown
   
   init()
   agent = Agent(name="Assistant", instructions="You are a helpful assistant")
   
   try:
       result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
       print(result.final_output)
   finally:
       shutdown()

4. Run OpenAI Agents

   Run your script to send the trace to Confident AI:

   PythonTypeScript

   python main.py

   Done ✅. Open the Observatory in your Confident AI project to inspect the trace and its workflow, agent, and model spans.

What Gets Captured

The integration converts the Agents SDK's native tracing objects into spans and preserves their parentage, so the trace tree in the Observatory matches the run:

Regular and streamed Runner executions are supported, including runs that hand off between agents or trigger guardrails.

Set Trace Span Properties

Use a trace context to add properties you know before the call starts. It creates no extra span; the trace started by Runner.run_sync() / run() inherits the tags, metadata, and user ID.

from confident_trace import init, trace_context
from agents import Agent, Runner

init()

agent = Agent(name="Assistant", instructions="Be concise.")

with trace_context(
    tags=["support"],
    metadata={"release": "2026-09"},
    user_id="user-42",
):
    result = Runner.run_sync(agent, "Explain OpenTelemetry in one sentence.")

import { init, traceContext } from "confident-trace";
import { Agent, run } from "@openai/agents";

init();

const agent = new Agent({ name: "Assistant", instructions: "Be concise." });

const result = await traceContext(
  { tags: ["support"], metadata: { release: "2026-09" }, userId: "user-42" },
  () => run(agent, "Explain OpenTelemetry in one sentence."),
);

See trace context for every supported trace property and update behavior.

Instrumenting Multi-Turn

You do not need turn() when one OpenAI Agents entry-point call is already one conversational turn—the integration creates that turn's trace automatically. Use turn() when you want to define the boundary yourself, such as grouping two sequential OpenAI Agents calls into one turn. Reuse the same thread ID on later turns to group them into one conversation.

from confident_trace import init, turn

init()

with turn("support-turn", thread_id="chat-42"):
    context = Runner.run_sync(agent, "Find the relevant account details.")
    answer = Runner.run_sync(agent, f"Summarize these details: {context.final_output}")

import { init, turn } from "confident-trace";

init();

const answer = await turn({ name: "support-turn", threadId: "chat-42" }, async () => {
  const context = await run(agent, "Find the relevant account details.");
  return run(agent, `Summarize these details: ${context.finalOutput}`);
});

See threads for thread I/O, turn IDs, and user IDs.

Troubleshooting

For general issues, see troubleshooting.

Disable OpenAI Agents Instrumentation

Pass init() a list of integration identifiers to opt in to only those integrations. The identifier for OpenAI Agents is "openai_agents" in Python or "openai-agents" in TypeScript; omit it to disable this integration. An empty list disables all automatic instrumentation:

from confident_trace import init
init(instrumentations=())
# Use ("openai_agents",) to opt in; omit "openai_agents" to disable it.

import { init } from "confident-trace";
init({ instrumentations: [] });
// Use ["openai-agents"] to opt in; omit "openai-agents" to disable it.

This turns off Confident AI's automatic instrumentation; calls made after initialization are not instrumented by this integration.

Next Steps

Last updated on September 10, 2026