OpenAI Agents SDK – Miguel Armengol

Definition

The OpenAI Agents SDK (@openai/agents) is a TypeScript framework for building multi-agent systems. It is the architectural successor to the experimental "Swarm" framework, focusing on lightweight, modular orchestration with minimal abstractions.

The SDK manages the Agent Loop—the iterative process of sending prompts, receiving tool calls, and returning results to the model until a terminal state is reached.

Core Primitives

Agents

An Agent is a model instance configured with specific instructions, tools, and guardrails. Agents represent a single "role" or "persona" in the system.

Handoffs

Handoffs are the mechanism for multi-agent coordination. An agent can transfer the conversation to another specialized agent by returning it as a tool output.

Pattern: A "Router" agent receives a query and hands off to a "Billing" or "Tech Support" agent based on intent.

Sandbox Agents (Beta)

Specialized agents paired with an isolated filesystem workspace. They are pre-configured with tools for file manipulation (read, write, patch) and shell execution (bash), running within a secure Docker or Unix-based sandbox.

Technical Features

Type-Safe Tooling

The SDK uses Zod for schema definition and validation. Tools are defined as standard TypeScript functions, and the SDK automatically generates the JSON schema for model consumption.

const weatherAgent = new Agent({
  tools: [
    {
      name: "getWeather",
      parameters: z.object({ location: z.string() }),
      run: async ({ location }) => ({ temp: "22C" })
    }
  ]
});

Guardrails

Parallel validation logic that inspects inputs or outputs. Guardrails can "trip" to block execution if safety or policy violations are detected (e.g., PII detection or restricted topics).

Model Context Protocol (MCP)

Native support for MCP, allowing agents to connect to standardized external data sources and tool servers via a unified interface.

Implementation Ownership

Component	Responsibility	Ownership
Agent Logic	Developer	Defining instructions, handoff logic, and tool implementations.
Orchestration	System	The `run()` function manages the iterative LLM/Tool execution loop.
Sandbox Isolation	System/Developer	The SDK provides the Sandbox API; the developer must provide the Docker/Unix runtime environment.
Tracing	System	Built-in OpenTelemetry instrumentation for visualizing agent reasoning paths.

Examples and Tools

Runtime: Node.js 22+, Deno, Bun.
Packages: @openai/agents, zod.
Infrastructure: Docker (for Sandboxes), OpenTelemetry collectors (for tracing).