OpenAI Agents SDK (JavaScript/TypeScript)

Overview#

OpenAI Agents SDK (JavaScript/TypeScript) is a lightweight, powerful framework for multi-agent workflows and voice agents officially released by OpenAI. The project aims to solve core engineering challenges including multi-agent collaboration, tool call orchestration, input/output security validation, and voice interaction integration.

Core Features#

Agent Capabilities#

• Agents: LLM entities with configurable instructions, tools, handoffs, and guardrails
• Handoffs: Specialized tool call mechanism for dynamically transferring control between agents
• Parallelization: Parallel execution of multiple agents or tools with result aggregation

Security & Compliance#

• Guardrails: Configurable input/output security and validation checks running parallel to agent execution
• Human-in-the-Loop: Built-in mechanism for introducing human approval or intervention in workflows

Tools & Extensions#

• Tool Integration: Convert functions to tools with Zod-based parameter validation and automatic schema generation
• MCP Support: Integration with MCP server tools
• Model Flexibility: Support for non-OpenAI models via Vercel AI SDK adapters
• Long-running Functions: Support for suspend and resume of long-running functions

Data Processing#

• Structured Output: Support for plain text and schema-based structured output
• Streaming: Real-time streaming output and events

Voice Capabilities#

• Realtime Voice Agents: Build realtime voice agents via WebRTC or WebSocket
• Voice Pipeline: Link text agents to voice agents via STT/TTS

Observability#

• Tracing: Built-in runtime tracing for visualization, debugging, and optimization

Architecture#

Module Structure#

Monorepo structure (pnpm workspace):

• packages/agents: Main package @openai/agents, aggregating core functionality
• packages/agents-core: Core logic and abstract definitions
• packages/agents-openai: OpenAI API integration layer
• packages/agents-realtime: Realtime voice agent capabilities
• packages/agents-extensions: Extension modules

Runtime Environment#

• Node.js ≥22, Deno, Bun
• Experimental support for Cloudflare Workers (requires nodejs_compat flag)
• Browser-optimized package available

Dependencies#

• Package name: @openai/agents
• Current version: v0.5.1
• Peer dependency: zod ^4.0.0
• License: MIT

Core Mechanisms#

Agent Loop#

1. Call run() to start the loop
2. If response contains handoff, switch to target agent and continue
3. If tool call exists, execute tool and append result to message history
4. Limit maximum turns via maxTurns

Final Output Determination#

• Structured mode (with outputType): Must return data matching the Schema
• Text mode (without outputType): First message without tool call or handoff ends the loop

Guardrails Execution#

Input validation runs parallel to agent logic; triggers GuardrailTripwireTriggered exception on violation

Quick Start#

# Installation
npm install @openai/agents zod

# Environment variable
export OPENAI_API_KEY=sk-...

import { Agent, run } from '@openai/agents';

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are a helpful assistant.'
});

const result = await run(agent, 'Write a haiku about recursion in programming.');
console.log(result.finalOutput);

Use Cases#

• Multi-agent orchestration and collaboration systems
• Tool-calling workflows (weather queries, web search, file search)
• Production applications requiring input/output security validation and compliance guardrails
• Realtime voice agents (browser or server-side)
• Human approval/intervention workflows (high-risk operations requiring human confirmation)
• Observability and debugging of complex processes