OpenAI Agents SDK TypeScript

Quickstart

Build your first agent in minutes.

Let’s build

Text Agent

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);

Voice Agent

import { RealtimeAgent, RealtimeSession } from '@openai/agents/realtime';

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

// Automatically connects your microphone and audio output in the browser via WebRTC.
const session = new RealtimeSession(agent);
await session.connect({
  apiKey: '<client-api-key>',
});

Overview

The OpenAI Agents SDK for TypeScript enables you to build agentic AI apps in a lightweight, easy-to-use package with very few abstractions. It’s a production-ready upgrade of our previous experimentation for agents, Swarm, that’s also available in Python. The Agents SDK has a very small set of primitives:

• Agents, which are LLMs equipped with instructions and tools
• Agents as tools / Handoffs, which allow agents to delegate to other agents for specific tasks
• Guardrails, which enable the inputs to agents to be validated

In combination with TypeScript, these primitives are powerful enough to express complex relationships between tools and agents, and allow you to build real-world applications without a steep learning curve. In addition, the SDK comes with built-in tracing that lets you visualize and debug your agentic flows, as well as evaluate them and even fine-tune models for your application.

Why use the Agents SDK

The SDK has two driving design principles:

1. Enough features to be worth using, but few enough primitives to make it quick to learn.
2. Works great out of the box, but you can customize exactly what happens.

Here are the main features of the SDK:

• Agent loop: A built-in agent loop that handles tool invocation, sends results back to the LLM, and continues until the task is complete.
• TypeScript-first: Orchestrate and chain agents using native TypeScript language features, without needing to learn new abstractions.
• Agents as tools / Handoffs: A powerful mechanism for coordinating and delegating work across multiple agents.
• Guardrails: Run input validation and safety checks in parallel with agent execution, and fail fast when checks do not pass.
• Function tools: Turn any TypeScript function into a tool with automatic schema generation and Zod-powered validation.
• MCP server tool calling: Built-in MCP server tool integration that works the same way as function tools.
• Sessions: A persistent memory layer for maintaining working context within an agent loop.
• Human in the loop: Built-in mechanisms for involving humans across agent runs.
• Tracing: Built-in tracing for visualizing, debugging, and monitoring workflows, with support for the OpenAI suite of evaluation, fine-tuning, and distillation tools.
• Realtime Agents: Build powerful voice agents with features such as automatic interruption detection, context management, guardrails, and more.

Installation

npm install @openai/agents zod@3

Hello world example

Hello World

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);

// Code within the code,
// Functions calling themselves,
// Infinite loop's dance.

(If running this, ensure you set the OPENAI_API_KEY environment variable)

export OPENAI_API_KEY=sk-...