OpenAI Agents SDK TypeScript

OpenAI Agents SDK

Build text, sandbox, and realtime agents with a small set of primitives.

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

import { run } from '@openai/agents';
import { gitRepo, SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const agent = new SandboxAgent({
  name: 'Workspace Assistant',
  model: 'gpt-5.6-sol',
  instructions: 'Inspect the repo before changing files.',
  defaultManifest: {
    entries: { repo: gitRepo({ repo: 'openai/openai-agents-js' }) },
  },
});

const result = await run(
  agent,
  'Inspect the repo README and summarize what this project does.',
  { sandbox: { client: new UnixLocalSandboxClient() } },
);

console.log(result.finalOutput);

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
Sandbox agents, which pair agents with isolated filesystem workspaces, shell commands, file editing, snapshots, and sandbox session state
Realtime agents, which support low-latency spoken interactions with tools, guardrails, handoffs, and conversation history
Agents as tools and 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, give agents a real workspace when they need one, 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:

Enough features to be worth using, but few enough primitives to make it quick to learn.
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.
Sandbox execution: Run agents with isolated filesystem workspaces, shell commands, file editing, snapshots, and sandbox session state when the work needs a workspace.
Realtime Agents: Build low-latency spoken interactions with features such as automatic interruption detection, context management, guardrails, and more.
TypeScript-first: Orchestrate and chain agents using native TypeScript language features, without needing to learn new abstractions.
Agents as tools and 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 integration that exposes tools from MCP servers to agents alongside 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.

Installation

npm install @openai/agents zod

The SDK requires Zod v4; installing zod via npm will fetch the latest v4 release.

Choose your starting point

Most first-time users only need one of these entry points:

Start with	Use it when	Notes
`@openai/agents`	You are building most text, sandbox, or realtime applications.	Recommended default. It includes the OpenAI provider setup, sandbox agent APIs under `@openai/agents/sandbox`, and realtime APIs under `@openai/agents/realtime`.
`@openai/agents-realtime`	You only need the standalone Realtime package.	Useful for browser-only realtime apps or when you want a narrower package boundary.
Lower-level packages (`@openai/agents-core`, `@openai/agents-openai`, `@openai/agents-extensions`)	You need lower-level composition, custom provider wiring, or specific integrations.	Most new users can ignore these until they have a concrete need.

Hello world examples

Start with a regular Agent for text workflows. Use a sandbox agent when the agent should work in a filesystem or carry workspace state across longer tasks.

Text Agent
Sandbox 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);

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

import { run } from '@openai/agents';
import { gitRepo, SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const agent = new SandboxAgent({
  name: 'Workspace Assistant',
  model: 'gpt-5.6-sol',
  instructions: 'Inspect the repo before changing files.',
  defaultManifest: {
    entries: { repo: gitRepo({ repo: 'openai/openai-agents-js' }) },
  },
});

const result = await run(
  agent,
  'Inspect the repo README and summarize what this project does.',
  { sandbox: { client: new UnixLocalSandboxClient() } },
);

console.log(result.finalOutput);

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

export OPENAI_API_KEY=sk-...

Start here

Pick one path first, get it working end to end, then come back for the deeper guides.

Quickstart Build your first text-based agent and learn the core SDK workflow.

Sandbox agents Start a sandbox agent when the agent needs files, shell commands, patches, or resumable sandbox state.

Realtime Agents Quickstart Start with Realtime agents when you are building spoken interactions.

Choose your path

Use this table when you know the job you want to do, but not which page explains it.

Goal	Start here
Build the first text agent and see one complete run	Quickstart
Add function tools, hosted tools, or agents as tools	Tools
Give an agent an isolated filesystem and shell workspace	Sandbox agents
Decide between handoffs and manager-style orchestration	Agent orchestration
Keep memory across turns	Running agents and Sessions
Use OpenAI models, websocket transport, or non-OpenAI providers	Models
Review outputs, run items, interruptions, and resume state	Results
Build a low-latency realtime agent	Realtime Agents Quickstart