OpenAI

For agents built on the higher-level OpenAI Agents SDK instead of the plain client, see OpenAI Agents SDK. Install the integration extra:

pip install "agentx-python[openai]"

Usage

Call patch_openai_client() once after creating your OpenAI client. All subsequent client.chat.completions.create() calls are traced automatically. No changes to individual API calls are needed. Works with both openai.OpenAI and openai.AsyncOpenAI.

from agentx import AgentX
from agentx.integrations.openai import patch_openai_client
import openai

agentx = AgentX.from_env()
client = openai.OpenAI()

patch_openai_client(
    client,
    tracer=agentx.tracer,
    name="support-agent",
    metadata={"env": "production"},
    session_id="session-xyz-789",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "How do I cancel my subscription?"}],
)
print(response.choices[0].message.content)

agentx.tracer.flush(timeout=10)

Async client:

patch_openai_client(async_client, tracer=agentx.tracer, name="support-agent")

response = await async_client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "How do I cancel my subscription?"}],
)

What gets traced

By default, each non-streaming chat.completions.create() call produces its own trace.

Field	Source
`input`	`messages` kwarg
`output`	`response.choices[0].message.content` (or a tool-call description if the reply is a pure tool call)
`latencyMs`	Wall-clock time of the API call - measured after the real response comes back, for both sync and async clients
`model`	`model` kwarg
`inputTokens` / `outputTokens`	`response.usage.prompt_tokens` / `.completion_tokens`
`error`	Exception message if the API call raises

Calls made with stream=True are passed through untraced. Safely wrapping a chunk iterator without disrupting the caller’s own consumption of it needs different handling than a single request/response call, so streaming isn’t covered by this integration yet.

The raw OpenAI SDK has no built-in concept of “tool call” or “retrieval”; those only exist as plain Python code around your chat.completions.create() calls, so the patch can’t see them on its own. Use tracer.trace_tool_call() and tracer.trace_retrieval() to record them manually so they show up in the trace’s performance summary - see the Anthropic integration’s tool-use example for the same pattern (identical API, different client).

Multi-call agentic loops

Like the Anthropic integration, wrap a multi-call tool-use loop in with tracer.trace(...) to collapse every chat.completions.create() call made inside it into one trace instead of one trace per call:

with agentx.tracer.trace("support-agent", framework="openai") as span:
    span.input = question
    # ... call client.chat.completions.create() as many times as needed ...
    span.output = final_answer

This works because patch_openai_client() checks tracer.current_span on every call: if a span is active on the current thread, the call is attached to it as an "LLM Call N" step; otherwise it sends its own trace as usual.

`patch_openai_client()` reference

patch_openai_client(
    client: openai.OpenAI | openai.AsyncOpenAI,
    tracer: Tracer,
    name: str = "openai-agent",
    metadata: dict | None = None,
    session_id: str | None = None,
) -> None

Parameter	Description
`client`	The `openai.OpenAI()` or `openai.AsyncOpenAI()` instance to patch
`tracer`	`agentx.tracer` from your `AgentX` instance
`name`	Label shown in the AgentX UI for every trace
`metadata`	Static key-value metadata attached to every trace
`session_id`	Links traces from the same conversation thread

Calling patch_openai_client() on an already-patched client is a no-op; it is safe to call multiple times.

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.

Tracing

Framework Integrations

Usage

What gets traced

Multi-call agentic loops

`patch_openai_client()` reference

​Usage

​What gets traced

​Multi-call agentic loops

​patch_openai_client() reference

Usage

What gets traced

Multi-call agentic loops

`patch_openai_client()` reference