openai/openai-agents-js

openai/openai-agents-js

Description: A lightweight, powerful framework for multi-agent workflows and voice agents

Language: TypeScript

License: MIT

Stars: 3194

Forks: 809

Open issues: 61

Created: 2025-05-31T00:08:49Z

Pushed: 2026-06-09T03:29:22Z

Default branch: main

Fork: no

Archived: no

README:

OpenAI Agents SDK (JavaScript/TypeScript)

 

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.

> [!NOTE] > Looking for the Python version? Check out OpenAI Agents SDK Python.

Core concepts

1. **Agents**: LLMs configured with instructions, tools, guardrails, and handoffs 1. **Sandbox Agents**: Agents paired with a filesystem workspace and sandbox environment for longer-running work 1. [Agents as tools](https://openai.github.io/openai-agents-js/guides/tools/#4-agents-as-tools) / [Handoffs](https://openai.github.io/openai-agents-js/guides/handoffs/): Delegating to other agents for specific tasks 1. **Tools**: Various Tools let agents take actions (functions, MCP, hosted tools) 1. **Guardrails**: Configurable safety checks for input and output validation 1. **Human in the loop**: Built-in mechanisms for involving humans across agent runs 1. **Sessions**: Automatic conversation history management across agent runs 1. **Tracing**: Built-in tracking of agent runs, allowing you to view, debug and optimize your workflows 1. **Realtime Agents**: Build powerful voice agents with full features

Explore the `examples/` directory to see the SDK in action.

Get started

Supported environments

• Node.js 22 or later
• Deno
• Bun

Experimental support:

• Cloudflare Workers with nodejs_compat enabled

Check out the documentation for more detailed information.

Installation

npm install @openai/agents zod

Run your first Sandbox Agent

Sandbox Agents are in beta. A sandbox agent can inspect files, run commands, apply patches, and carry workspace state across longer tasks.

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',
instructions: 'Inspect the sandbox workspace before answering.',
defaultManifest: {
entries: {
repo: gitRepo({
repo: 'openai/openai-agents-js',
ref: 'main',
}),
},
},
});

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

console.log(result.finalOutput);
// This project provides a JavaScript/TypeScript SDK for building agent workflows.

(_If running this, ensure you set the OPENAI_API_KEY environment variable_)

Run an agent without a sandbox

You can still use a regular Agent when your workflow does not need a filesystem workspace or sandbox lifecycle.

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.

Explore the `examples/` directory to see the SDK in action.

Acknowledgements

We'd like to acknowledge the excellent work of the open-source community, especially:

• zod (schema validation)
• Starlight
• vite and vitest
• pnpm
• Next.js

We're committed to building the Agents SDK as an open source framework so others in the community can expand on our approach.

For more details, see the documentation or explore the `examples/` directory.