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 — 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(
api_key="agx-xxxxxxxxxxxxxxxx",
workspace_id="xxxxxxxxxxxx", # optional
)
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 | Extracted from the root span’s input |
output | trace.output at run end |
latencyMs | Wall-clock time from on_trace_start to on_trace_end |
model | Extracted from the first LLM generation span |
toolCalls | Each function-tool span — tool_name, input, output, latencyMs |
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 |
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.
