> ## Documentation Index
> Fetch the complete documentation index at: https://developers.agentx.so/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Agents SDK

> Trace OpenAI agent runs with AgentXTracingProcessor

Install the integration extra:

```bash theme={null}
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.

```python theme={null}
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

```python theme={null}
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.

<Note>
  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.
</Note>