OpenAI Agents SDK

Install the integration extra:

pip install "agentx-python[openai-agents]" openai-agents

Usage

Register AgentXTracingProcessor once at startup. It hooks into the OpenAI Agents SDK’s global tracing pipeline, so every subsequent Runner.run() call is traced automatically with no per-call changes.

from agentx import AgentX
from agentx.integrations.openai_agents import AgentXTracingProcessor
from agents import Agent, Runner, add_trace_processor, function_tool

client = AgentX.from_env()  # AGENTX_API_KEY (+ AGENTX_API_BASE_URL for self-host)

add_trace_processor(AgentXTracingProcessor(
    tracer=client.tracer,
    metadata={"env": "production"},
    session_id="session-001",
))

@function_tool
def get_policy(topic: str) -> str:
    """Return the company policy for a given topic."""
    db = {
        "cancel": "Go to Account → Subscription → Cancel.",
        "trial": "14-day free trial, no credit card required.",
        "refund": "Full refund within 30 days.",
    }
    return db.get(topic.lower(), "No policy found.")

agent = Agent(
    name="support-agent",
    instructions="You are a helpful support agent. Use get_policy to look up policies.",
    tools=[get_policy],
)

result = Runner.run_sync(agent, "How do I cancel my subscription?")
print(result.final_output)

client.tracer.flush(timeout=10)

What gets traced

Each top-level agent run (one Runner.run() / Runner.run_sync() call) produces one trace.

Field	Source
`input`	The first generation/response span’s input (last user message)
`output`	The last generation/response span’s output (the final reply)
`latencyMs`	Wall-clock time from `on_trace_start` to `on_trace_end`
`model`	Extracted from the first LLM generation/response span
`inputTokens` / `outputTokens`	Summed from each generation/response span’s `usage` (`input_tokens` / `output_tokens`)
LLM steps	Each `generation`/`response` span becomes a real `"LLM Call N"` child span with its own timing, input/output, model, and tokens - Chat Completions and Responses API both covered
Tool steps	Each `function` span becomes a child span named after the tool, with `input`, `output`, and real timing
`toolCalls`	Each function call is also appended to the root’s flat `toolCalls` list with a `success` flag - this is what the engine’s built-in Tool-failure check and the dashboard’s Tool quality column read
`framework`	Stamped `openai-agents` automatically - the platform label on the framework filter and Monitor’s Platforms chart
`error`	`span.error` from the first failed span in the trace (message + data)

Span kinds: the root span is stamped agent, LLM child spans llm, and tool child spans tool. The processor’s constructor takes no name parameter - the root trace is named after the Agents SDK trace name, which defaults to "openai-agent" when the trace carries none.

`AgentXTracingProcessor` reference

AgentXTracingProcessor(
    tracer: Tracer,
    metadata: dict | None = None,
    session_id: str | None = None,
)

Parameter	Description
`tracer`	`client.tracer` from your `AgentX` instance
`metadata`	Static key-value metadata attached to every trace
`session_id`	Links traces from the same conversation thread

The processor also implements force_flush() and shutdown(), which both call tracer.flush(). These are invoked automatically by the OpenAI Agents SDK at process exit.

Call tracer.flush() before your process exits in scripts or one-shot jobs. In long-running servers it is not required: traces drain automatically in the background.

​Usage

​What gets traced

​AgentXTracingProcessor reference

Usage

What gets traced

`AgentXTracingProcessor` reference