openai-agents-js

What it is

The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows in JavaScript/TypeScript. It is provider-agnostic, supporting OpenAI APIs and more.

How it works

The repository describes core concepts including Agents, Sandbox Agents, Realtime Agents, Tools, Guardrails, Human in the loop, Sessions, and Tracing. It provides examples and guides for building text agents, sandbox agents, and realtime agents, with integration patterns for tools and handoffs.

Getting started

Installation

npm install @openai/agents zod

### Build a text agent
```js
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);

Build a sandbox agent

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.5',
  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);

Build a realtime 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>' });

Set OPENAI_API_KEY in your server environment for text and sandbox agents. For browser-based realtime agents, use your server to create a short-lived ephemeral client token and pass it to session.connect(...).

Recent releases

• v0.14.2 (2026-08-01): feat: preserve sandbox environment secret references by @seratch; fix: preserve raw realtime transport event payloads by @
• v0.14.1 (2026-07-29): fix(core): export lifecycle and agent tool helper types by @seratch; fix(sandbox): support native Windows paths in path gr
• v0.14.0 (2026-07-28): Key Changes: Programmatic Tool Calling support
• v0.13.5 (2026-07-17): feat(ai-sdk): support provider-executed tool search by @seratch; fix: decode base64 without host globals by @seratch in ht
• v0.13.4 (2026-07-15): fix: preserve stream usage reported on non-final chunks by @sohumt123; fix: fail union/tuple schema conversion instead of

Traction

3528 stars, 888 forks, 35 open issues

Behind the repo

N/A

Caveats

License: MIT Created: 2025-05-31 Last push: 2026-08-04