Skip to main content

OpenAI Agents Integration

OpenAIAgentsTracer hooks into the OpenAI Agents SDK global tracing layer to capture agent runs, tool calls, agent handoffs, guardrail evaluations, and model generations without modifying agent code.

Installation​

pip install briefcase-ai
pip install openai-agents

Quick Setup​

The recommended approach uses install() to register the tracer globally. It is idempotent — calling it multiple times returns the same processor.

from briefcase.integrations.frameworks import openai_agents_hook

tracer = openai_agents_hook.install()

Or import install directly from the handler module:

from briefcase.integrations.frameworks.openai_agents_handler import install

tracer = install(context_version="v2.1", async_capture=True)

Manual Registration​

from briefcase.integrations.frameworks import OpenAIAgentsTracer
from agents import add_trace_processor

tracer = OpenAIAgentsTracer(
    context_version="v2.1",   # optional version tag
    async_capture=True,        # export in background thread (default)
)
add_trace_processor(tracer)

Constructor​

OpenAIAgentsTracer(
    context_version: Optional[str] = None,
    async_capture: bool = True,
)
ParameterDefaultDescription
context_versionNoneVersion tag added to all trace records
async_captureTrueExport in a background daemon thread

Running Agents​

After registration, run agents normally. All activity is captured automatically:

from agents import Agent, Runner

agent = Agent(
    name="claims-reviewer",
    instructions="Review insurance claims and return a decision with confidence.",
    tools=[lookup_policy, calculate_risk_score],
)

result = Runner.run_sync(agent, "Evaluate claim CLM-00123")

Inspecting Records​

records = tracer.get_records()   # List[Dict[str, Any]]
tracer.clear()

Each record has this structure:

{
    "trace_id": "trace_abc123",
    "name": "claims-reviewer",           # agent name
    "started_at": "2026-02-26T10:00:00Z",
    "ended_at": "2026-02-26T10:00:02Z",
    "context_version": "v2.1",
    "spans": [
        {
            "span_id": "span_001",
            "trace_id": "trace_abc123",
            "type": "agent_run",
            "agent_name": "claims-reviewer",
            "tools": ["lookup_policy", "calculate_risk_score"],
            "handoffs": [],
            "output_type": "str",
            "started_at": "2026-02-26T10:00:00Z",
            "ended_at": "2026-02-26T10:00:02Z",
            "execution_time_ms": 2043.0
        },
        {
            "span_id": "span_002",
            "type": "tool_call",
            "tool_name": "lookup_policy",
            "input": "{\"policy_id\": \"medicare-2024\"}",
            "output": "{\"coverage\": \"full\"}",
            "execution_time_ms": 85.2
        },
        {
            "span_id": "span_003",
            "type": "generation",
            "model": "gpt-4o",
            "usage": {"input_tokens": 380, "output_tokens": 95},
            "execution_time_ms": 1870.0
        }
    ]
}

Span Types​

typeCaptured whenKey fields
agent_runAn agent starts and completesagent_name, tools, handoffs, output_type
tool_callA function/tool is invokedtool_name, input, output
handoffControl transfers between agentsfrom_agent, to_agent
guardrailA guardrail is evaluatedguardrail_name, triggered (bool)
generationAn LLM generates a responsemodel, usage, input, output

Export on Trace Completion​

When a trace ends, on_trace_end triggers _trigger_export, passing the assembled record to the configured BriefcaseConfig.exporter.

from briefcase.config import setup
from briefcase.exporters import OTelExporter

setup(exporter=OTelExporter(endpoint="http://localhost:4317"))

# Now register the tracer — it will use the configured exporter
tracer = openai_agents_hook.install()

With async_capture=True, export runs in a daemon thread and does not block agent execution.

Troubleshooting​

ImportError: openai-agents is required: Install with pip install openai-agents. The tracer raises at import time if the package is absent.

No records captured: Verify that add_trace_processor was called before the agent ran. If using install(), call it at application startup.

Double registration: install() is idempotent — it returns the existing processor if already installed. Do not call add_trace_processor manually after install().

See Also​