====== OpenAI Agents SDK ======

**OpenAI Agents SDK** is a lightweight, production-ready framework for building agentic AI applications, launched in March 2025 as an evolution of the experimental **Swarm** project. The SDK provides four core primitives — Agents, Handoffs, Tools, and Guardrails — enabling developers to build multi-agent systems with minimal abstraction overhead.

The SDK is available for both Python and TypeScript (TypeScript released July 2025) and is optimized for OpenAI models while supporting other LLM providers via the Chat Completions API.

===== Evolution from Swarm =====

Swarm was OpenAI's initial experimental framework for multi-agent orchestration, released as a research prototype. The Agents SDK represents the production-grade evolution, upgrading Swarm's concepts into a stable toolkit with:

  * Formalized agent handoff protocols
  * Built-in input/output guardrails
  * Integrated tracing and observability
  * Automatic schema generation for tools
  * Support for the Responses API

===== Core Primitives =====

**Agents** are instruction-driven LLM instances with a name, system instructions, and a set of tools. Each agent encapsulates a specific role or capability.

**Handoffs** enable agents to delegate tasks to other agents. When an agent determines it cannot handle a request, it hands off to a more specialized agent along with a summary of context.

**Tools** are Python or TypeScript functions that agents can call. The SDK automatically generates JSON schemas from function signatures and handles validation.

**Guardrails** provide input and output validation to constrain agent behavior, reduce unsafe responses, and ensure compliance with application requirements.

===== Architecture =====

The SDK uses a minimalist, modular architecture:

  * **Agent Loop** — Manages the conversation cycle: receive input, reason, call tools or handoff, return output
  * **Tool Registry** — Automatic function-to-tool conversion with schema generation and validation
  * **Memory Manager** — Context persistence for multi-turn conversations
  * **Tracing** — Built-in observability for debugging execution paths
  * **Guardrail Layer** — Pre- and post-processing validation

This design avoids heavyweight abstractions like graphs or state machines, prioritizing low cognitive overhead and rapid prototyping.

===== Code Example =====

<code python>
from agents import Agent, Runner, tool, handoff

@tool
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"Weather in {city}: Sunny, 72F"

weather_agent = Agent(
    name="Weather Agent",
    instructions="You provide weather information using your tools.",
    tools=[get_weather]
)

triage_agent = Agent(
    name="Triage Agent",
    instructions="Route requests to the appropriate specialist agent.",
    handoffs=[handoff(weather_agent)]
)

result = Runner.run_sync(triage_agent, "What is the weather in Tokyo?")
print(result.final_output)
</code>

===== Key Design Decisions =====

  * **Minimalism over abstraction**: Four primitives cover most agentic patterns without complex graph definitions
  * **Convention over configuration**: Sensible defaults with escape hatches for advanced use
  * **Provider-agnostic**: Optimized for OpenAI models but works with 100+ LLMs via Chat Completions API
  * **Dual language support**: Feature parity between Python and TypeScript implementations

===== References =====

  * [[https://github.com/openai/openai-agents-python|OpenAI Agents SDK — Python GitHub]]
  * [[https://openai.github.io/openai-agents-python/|OpenAI Agents SDK Documentation]]
  * [[https://developers.openai.com/api/docs/guides/agents-sdk/|OpenAI Developer Guide — Agents SDK]]
  * [[https://mem0.ai/blog/openai-agents-sdk-review|OpenAI Agents SDK Review (2025)]]

===== See Also =====

  * [[claude_agent_sdk]] — Anthropic Claude Agent SDK
  * [[crewai]] — CrewAI multi-agent framework
  * [[autogen]] — Microsoft AutoGen/AG2
  * [[multi_agent_systems]] — Multi-agent system architectures