The Handoff Pattern — Swarm's Innovation

Swarm's breakthrough was the Agent-return-Agent pattern. A tool function returns an Agent object instead of a string, and the runtime interprets the return value as a routing instruction. This collapsed multi-agent orchestration into a single composable abstraction: you could wire up triage agents, specialist agents, and escalation paths using nothing but Python functions and Agent constructors [3]. No state machines, no graphs, no message queues.

Declarative Handoffs — The SDK's Refinement

The Agents SDK kept the core idea but made handoffs declarative. Instead of writing boilerplate transfer functions, you declare handoffs directly on the agent: handoffs=[handoff(refund_agent), handoff(billing_agent)]. The SDK generates the routing functions automatically, validates the handoff topology at agent creation time, and surfaces handoff chains in the tracing UI [4]. This is a strict upgrade — less code, fewer bugs, more observability.

Guardrails — From Zero to Production Safety

Swarm had no safety layer. If an agent generated toxic output or received PII, there was no mechanism to intercept it. The SDK introduces input and output guardrails — lightweight agents that run before and after your main agent, checking for policy violations, PII, format mismatches, or unsafe content [5]. Guardrails can trigger triage-specific responses, block execution, or escalate to a human. This single feature transforms the SDK from a prototyping tool to a deployment platform.

Tracing — From Black Box to Observable System

Swarm's client.run() returned a list of messages. That was it. If a handoff chain had 7 agents and one of them returned the wrong output, you had no way to trace the failure. The SDK bakes in distributed tracing from day one — every agent turn, tool call, handoff, and guardrail check is recorded with timestamps, token counts, and parent-child relationships [6]. Traces can be viewed in OpenAI's hosted UI or exported via OpenTelemetry to any observability platform (Datadog, Grafana, Langfuse).

Sandbox Agents — From Stateless to Stateful Execution

The SDK's v0.14.0 release introduced sandbox agents — containerized execution environments defined by a declarative Manifest. Each agent gets an isolated workspace with exactly the files, dependencies, and tools it needs. State is snapshotted on exit and rehydrated on resume [7]. This is something Swarm couldn't even approximate — Swarm was fundamentally stateless, with no mechanism for durable execution, file persistence, or environment isolation.

Human-in-the-Loop — From Full Autonomy to Controlled Execution

Swarm assumed full agent autonomy — once you called client.run(), the agent chain ran to completion. The SDK introduces human-in-the-loop approval workflows that pause execution at configurable checkpoints: before executing expensive tool calls, before handing off to a sensitive agent, or before finalizing output [8]. This is critical for regulated industries (healthcare, finance, legal) where agent decisions require human sign-off.