# Practical and Useful Patterns for OpenAI Agent SDK
🌍 See what's happening inside your agents. Built-in tracing captures every LLM call, tool execution, handoff, and guardrail evaluation in your agent flow.
Tracing is enabled by default. Visualize agent behavior in the Traces dashboard to accelerate debugging and quality improvement.
📌 Title: Tracing
🔗 URL:
🧩 Overview
The OpenAI Agent SDK's built-in tracing automatically records every step of agent execution -- LLM calls, tool executions, handoffs, and guardrail evaluations. It's enabled by default and visualized in OpenAI's Traces dashboard. Group related runs with `with trace("name")`, ensure trace delivery in worker environments with `flush_traces()`, and control privacy with `RunConfig(trace_include_sensitive_data=False)` or environment variables.
🛠 How to Use
Import `Agent`, `Runner`, and `trace` from `agents`. Create an `Agent` and run it with ` "What are the latest AI trends?")` -- tracing is automatically enabled by default, recording all LLM calls and tool executions.
🏗 Practical Usage Patterns
**Grouping Related Runs with trace()**
Bundle multiple agent runs into a single trace for a bird's-eye view of the entire workflow.
Import `trace` from `agents` and wrap multiple ` calls inside a `with trace("Joke workflow"):` block. The joke generation, evaluation, and conditional improvement flow are grouped into a single trace for end-to-end visibility in the dashboard.
**Reliable Trace Delivery with flush_traces()**
In Celery/RQ/FastAPI background workers, flush traces before the process exits.
Import `flush_traces` from `agents`. In Celery tasks, call `flush_traces()` after ` message))` to send traces. In FastAPI, call `flush_traces()` in the `
@app.on_event("shutdown")` hook to guarantee trace delivery before process exit.
**Privacy Controls for Sensitive Data**
Control tracing in ZDR (Zero Data Retention) environments or when handling personal information.
Pass `run_config=RunConfig(trace_include_sensitive_data=False)` to ` (the default is `True`) to omit LLM inputs/outputs and function call data from traces; the default can also be flipped with the `OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA` environment variable. To disable tracing entirely, set `OPENAI_AGENTS_DISABLE_TRACING=1` or pass `RunConfig(tracing_disabled=True)`.
💡 Use Cases
📊 Visualize LLM/tool/handoff/guardrail flows in the Traces dashboard with zero-config default tracing
🔗 Group multiple agent runs under with trace("Joke workflow") for end-to-end workflow visibility
🔄 Call flush_traces() in Celery/RQ/FastAPI workers to guarantee trace delivery before process exit
🔒 Protect medical/financial data privacy with trace_include_sensitive_data=False
⚠️ Caveats
- Tracing is on by default, so sensitive data may inadvertently appear in traces. Review `trace_include_sensitive_data` settings for production environments.
- `flush_traces()` is a blocking operation. Call it in shutdown hooks or task completion, not in the critical request path.
- Trace data is sent to OpenAI. For compliance requirements, disable with `OPENAI_AGENTS_DISABLE_TRACING=1` or redirect with custom processors (see next section).
✨ Built-in tracing's greatest strength is "it just works with zero config." Start by checking the dashboard as-is, then add workflow grouping and privacy controls as needed!
#
OpenAIAgentSDK# #
AIAgent#