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.

Core concepts

1. Agents: LLMs configured with instructions, tools, guardrails, and handoffs
2. Sandbox Agents: Agents paired with a filesystem workspace and sandbox environment for longer-running work
3. Agents as tools / Handoffs: Delegating to other agents for specific tasks
4. Tools: Various Tools let agents take actions (functions, MCP, hosted tools)
5. Guardrails: Configurable safety checks for input and output validation
6. Human in the loop: Built-in mechanisms for involving humans across agent runs
7. Sessions: Automatic conversation history management across agent runs
8. Tracing: Built-in tracking of agent runs, allowing you to view, debug and optimize your workflows
9. 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.