OpenAI Agents SDK Whiteboard Breakdown: Three Primitives and Tracing Mechanism

OpenAI Agents SDK is described in its official documentation as a "lightweight, easy-to-use package with very few abstractions," and is the production-grade upgrade of the earlier experimental project Swarm. Yet few articles explain its internal structure clearly. Based on a whiteboard explainer video, this article breaks down the SDK's three core primitives and focuses on the previously under-discussed Tracing mechanism.

Three Primitives: Agents, Orchestration, and Guardrails

The SDK documentation lists only three primitives, deliberately kept minimal by design.

Agent is a language model equipped with instructions and tools. Each Agent runs a built-in loop until the task is complete. This loop is the SDK's default behavior—developers don't need to write while loops manually.

Agents as tools and handoffs address multi-agent collaboration. The two patterns have clear divisions of labor: treating an Agent as a tool means having a primary Agent call another Agent to complete a subtask, while a handoff means transferring control entirely to another Agent. The whiteboard explainer notes that in handoff scenarios, a triage Agent routes the conversation to a specialist Agent, which then becomes the active Agent. This "classify first, then direct" pattern is called routing.

Guardrails validate Agent inputs and outputs. When validation fails, a guardrail triggers a "tripwire" that immediately aborts the run. This is a hard interruption mechanism, not a soft warning.

Key Features Beyond the Primitives

Beyond the three primitives, the SDK also includes human in the loop, Sessions, and Tracing. Sessions are a persistent memory layer that stores working context; human in the loop provides a built-in way to introduce human judgment during a run. Tracing, meanwhile, is exactly what the previous video series didn't cover.

Swarm is an experimental multi-agent orchestration framework that OpenAI open-sourced in October 2024. It demonstrates the two collaboration paradigms—"agents as tools" and "handoffs"—with extremely minimal Python code, designed to help developers quickly validate multi-agent workflows. It doesn't provide production-grade capabilities like persistence, tracing, or guardrails, and is explicitly labeled as experimental. Agents SDK was rewritten based on Swarm's core philosophy, adding built-in loops, tracing, guardrails, sessions, and other capabilities, while promising backward compatibility with Swarm's main abstractions. Understanding this lineage helps clarify why the SDK deliberately keeps "very few abstractions"—it continues Swarm's philosophy while filling in the observability and control mechanisms needed for production environments.

Tracing On by Default: The Nested Structure of Trace and Span

Tracing is enabled by default in the SDK, which is worth noting—if developers don't configure it actively, events are already being recorded. What it records includes model generations, tool calls, handoffs, guardrails, and custom events.

Understanding tracing requires distinguishing two concepts. A Trace is the end-to-end operation of a workflow, representing a complete run. A Span is a single operation within it with a start and end time, and can point to a parent Span, forming a nested structure.

The whiteboard example is intuitive: by default, the entire run is wrapped in a Trace; each Agent run is wrapped in an Agent Span. Within the Agent Span, model calls correspond to generation spans, tool calls to function spans, and handoffs to handoff spans. Additionally, runner calls and model turns generate Spans by default, as do guardrails—the whiteboard diagram omits these for simplicity.

The Default Risk of Recording Sensitive Data

The explainer specifically flags a security detail: generation spans and function spans store inputs and outputs, which may contain sensitive data, and this is included by default. This means the convenience of out-of-the-box tracing comes with a default surface for data exposure. For production environments, this requires a tradeoff between observability and data security.

OpenTelemetry (OTel) is an open-source observability standard led by the Cloud Native Computing Foundation (CNCF), unifying the data models and collection protocols for traces, metrics, and logs. In OTel semantics, a Trace represents the complete call chain of a distributed request, composed of multiple Spans; each Span records an operation's name, start and end times, attributes, and events, and can form tree-like nesting via parent span IDs. The Agents SDK's tracing model borrows directly from this set of concepts, so its Trace/Span structure can be seamlessly exported to OTel-compatible backends (such as Jaeger, Zipkin, or commercial APMs). This means teams with an existing OTel-based observability system can integrate SDK tracing without rebuilding data pipelines—they just need to configure an exporter to reuse existing storage and query capabilities.

PII (Personally Identifiable Information) refers to data that can identify a specific natural person, such as names, email addresses, phone numbers, ID numbers, and payment information. In LLM applications, user inputs and model outputs are highly likely to contain such information, and generation spans and function spans record it in full by default. Once tracing data is exported to third-party observability platforms or retained long-term, it may constitute a compliance risk (such as violating GDPR, CCPA, or domestic personal information protection laws). Common mitigation measures include: disabling the recording of sensitive fields in the SDK configuration, using sanitization processors to apply regex replacement on span attributes, or exporting tracing data to a controlled self-hosted backend. Teams should clarify data retention policies and access controls early in integration rather than remediating at audit time.

Positioning and Tradeoffs

From a design perspective, the SDK's orientation is very clear: use minimal abstractions to lower the learning curve, distill orchestration into three concepts—Agents, handoffs, and guardrails—and then add observability through tracing. Compared to Agent frameworks that aim for breadth and completeness, it's more like a set of building blocks with clear conventions. The cost is that fewer abstractions mean many capabilities require developers to compose themselves, and the fact that tracing records sensitive data by default also requires teams to think through their data strategy at integration time.

For readers wanting to understand Agent workflow patterns, routing is just one of them; the whiteboard explainer notes that subsequent content will cover more workflow patterns, which can serve as a direction for further reading.

One-line Summary

OpenAI Agents SDK achieves observability through three primitives and default-enabled tracing with minimal abstractions, but beware the default risk of recording sensitive data.

Paragraph Summary

Based on a whiteboard explainer video, this article systematically breaks down the internal structure of OpenAI Agents SDK. The SDK has only three primitives: Agent (equipped with instructions and tools, with a built-in run loop), agents as tools and handoffs (enabling multi-agent collaboration and routing), and Guardrails (validating inputs and outputs and hard-aborting via tripwires). Beyond the primitives, the SDK also provides human in the loop, a Sessions memory layer, and Tracing. Tracing is enabled by default; a Trace represents an end-to-end workflow, while a Span is a single operation with start and end times that can be nested. Within an Agent Span, it's subdivided into generation, function, handoff, and other spans. The article specifically cautions that generation spans and function spans store inputs and outputs by default, potentially leaking sensitive data, so production environments need to weigh observability against data security. Overall, the SDK continues Swarm's minimalist philosophy, trading low learning cost for flexible composition, at the cost of having to assemble capabilities yourself.