OpenAI Agents JavaScript SDK
Official JavaScript and TypeScript framework for building multi-agent workflows with agents, tools, handoffs, guardrails, sessions, tracing, realtime voice agents, MCP tools, hosted tools, and sandbox agents.
Open the source and read safety notes before installing.
Safety notes
- Agents can call function tools, hosted tools, MCP tools, realtime tools, and sandbox agents; treat every tool as an API endpoint with explicit authorization, input validation, rate limits, and side-effect controls.
- Sandbox agents can inspect files, run commands, apply patches, and carry workspace state across longer tasks; restrict workspace scope and require human approval before destructive or high-impact actions.
- Cloudflare Workers support is described upstream as experimental; review runtime compatibility, secrets, outbound network access, logging, request limits, and `nodejs_compat` behavior before production use.
- Guardrails help validate inputs and outputs, but they do not replace permission checks, least-privilege credentials, audit logs, or human review for risky operations.
- Handoffs and agents-as-tools can delegate work across agents; document which agent owns each tool, decision, retry, rollback, and escalation path.
Privacy notes
- Prompts, instructions, tool arguments, tool outputs, session history, traces, realtime audio events, sandbox files, logs, provider responses, and errors may contain user or workspace data.
- Do not expose secrets, tokens, private file paths, customer records, credentials, internal identifiers, raw exceptions, or voice transcripts through traces, logs, prompts, tool schemas, or examples.
- When using MCP servers, hosted tools, session stores, worker logs, observability systems, or deployment platforms, review each service's retention, access control, and third-party data handling separately.
- If sandbox agents operate on repositories or user files, define which files can be mounted, modified, committed, uploaded, logged, or returned to the model.
Prerequisites
- Node.js 22 or later, Deno, Bun, or an explicitly reviewed Cloudflare Workers runtime with `nodejs_compat` enabled.
- OpenAI API credentials or another configured model provider supported through the SDK's provider-agnostic routes.
- A reviewed tool boundary for function tools, hosted tools, MCP tools, handoffs, sandbox agents, and any external systems the agent can call.
- A TypeScript schema strategy for `zod`, tool inputs, tool outputs, guardrails, and runtime validation.
- A tracing, logging, and retention policy for prompts, tool calls, sessions, provider responses, voice events, and run metadata.
Schema details
- Install type
- cli
- Troubleshooting
- No
- Scope
- Source repo
- Estimated setup
- 20 minutes
- Difficulty
- intermediate
- Pricing
- free
- Disclosure
- editorial
- Application category
- DeveloperApplication
- Operating system
- Cross-platform
Full copyable content
npm install @openai/agents zodAbout this resource
Overview
OpenAI Agents JavaScript SDK is OpenAI's official JavaScript and TypeScript
framework for building agentic applications and multi-agent workflows. It is
published as @openai/agents and supports agents with instructions, tools,
guardrails, handoffs, sessions, tracing, realtime voice agents, and sandbox
agents.
Use it when a Node, Deno, Bun, or carefully reviewed Workers project needs a code-first TypeScript agent runtime with inspectable traces, schema-backed tool inputs, delegated agents, MCP integration, human review, session state, or voice interaction.
Install
The upstream README documents this npm install path:
npm install @openai/agents zod
The package supports Node.js 22 or later, Deno, Bun, and experimental Cloudflare
Workers support with nodejs_compat enabled. Review the runtime target before
using filesystem, sandbox, realtime, or network-heavy capabilities.
Agent Capabilities
| Area | JavaScript SDK Coverage |
|---|---|
| Agents | Instructions, model configuration, tools, guardrails, handoffs, and run behavior |
| Tools | Function tools, hosted tools, MCP tools, agents-as-tools, and sandbox agents |
| Workflow Control | Handoffs, human-in-the-loop review, sessions, retries, and run configuration |
| Observability | Built-in tracing for debugging and optimizing agent runs |
| Realtime | Voice agent support through realtime agent APIs |
| Sandboxes | Agents paired with a filesystem workspace and sandbox environment |
| Runtime Targets | Node.js 22+, Deno, Bun, and experimental Cloudflare Workers support |
MCP Fit
The SDK matters for MCP and agent searches because its tools layer can use MCP tools alongside function tools and hosted tools. That makes it a practical choice for TypeScript agent apps that want to call existing MCP servers without rewriting every integration as a custom adapter.
Keep the trust boundary explicit: an MCP server can expose files, SaaS accounts, databases, browser automation, cloud infrastructure, or internal APIs. The agent SDK wires those capabilities into a workflow, but the application still owns authorization, schema validation, least privilege, audit logs, approval gates, and rollback behavior.
Use Cases
- Build TypeScript assistants that coordinate several specialized agents.
- Route work between agents with handoffs or agents-as-tools.
- Add MCP tools to a JavaScript or TypeScript OpenAI Agents workflow.
- Use guardrails and human review around higher-risk tool calls.
- Trace agent runs for debugging, evaluation, and release review.
- Build realtime voice agents with full agent workflow support.
- Run sandbox agents against controlled workspaces for longer coding or repository tasks.
- Prototype agent workflows in Node, Deno, Bun, or carefully reviewed Workers runtimes.
Source Review
Verified on 2026-06-18:
- The upstream README describes the OpenAI Agents SDK for JavaScript and TypeScript as a lightweight framework for multi-agent workflows.
- The README lists agents, sandbox agents, agents-as-tools, handoffs, tools, guardrails, human-in-the-loop flows, sessions, tracing, and realtime agents as core concepts.
- The README documents support for Node.js 22 or later, Deno, Bun, and
experimental Cloudflare Workers support with
nodejs_compat. - The README documents
npm install @openai/agents zodas the install path. packages/agents/package.jsondeclares the@openai/agentspackage, MIT licensing, repository URL, homepage URL, OpenAI package dependencies, andzodpeer dependency.- The npm registry resolves package metadata for
@openai/agentsversion0.11.7.
Safety and Privacy
The SDK's risk profile depends on the tools and systems attached to each agent. Treat function tools, MCP tools, hosted tools, realtime actions, sandbox agents, and delegated agents as separate trust boundaries with their own permissions, audit trail, and failure mode.
Tracing, session storage, voice events, sandbox files, tool results, provider responses, worker logs, and observability data can contain sensitive user or workspace data. Review what is stored, who can read it, how long it is retained, and whether data crosses OpenAI, other model providers, MCP servers, databases, logs, observability systems, or deployment platforms.
Duplicate Check
Checked current content/agents/, content/guides/, content/mcp/,
content/tools/, content/skills/, open pull requests, and repository-wide
content for openai/openai-agents-js, OpenAI Agents JavaScript SDK, OpenAI
Agents TypeScript SDK, @openai/agents, OpenAI Agents MCP tools, OpenAI Agents
tracing JavaScript, and OpenAI sandbox agents. Existing content cites the JS
tracing guide as a related source, but no dedicated installable JavaScript or
TypeScript SDK tools entry, exact source URL duplicate, target file, or open
duplicate PR was found.
Source citations
Add this badge to your README
Show that OpenAI Agents JavaScript SDK is listed on HeyClaude. Paste this Markdown into your README — it renders the badge and links back to this page.
[](https://heyclau.de/entry/tools/openai-agents-js-sdk)How it compares
OpenAI Agents JavaScript SDK side by side with 3 alternatives on trust, install, platform support, and disclosed safety notes — all from reviewed registry metadata.
| Field | OpenAI Agents JavaScript SDK Official JavaScript and TypeScript framework for building multi-agent workflows with agents, tools, handoffs, guardrails, sessions, tracing, realtime voice agents, MCP tools, hosted tools, and sandbox agents. Open dossier | OpenAI Agents Python SDK Official Python framework for building multi-agent workflows with agents, tools, handoffs, guardrails, sessions, tracing, realtime voice agents, MCP tools, hosted tools, human-in-the-loop flows, and sandbox agents. Open dossier | Mastra TypeScript agent framework for building AI agents, workflows, memory, tool calling, and evaluation-backed applications. Open dossier | Official MCP TypeScript SDK Official TypeScript SDK for Model Context Protocol clients and servers, with the production v1 `@modelcontextprotocol/sdk` package, active v2 server and client package work, Node.js, Bun, and Deno support, transports, OAuth helpers, tools, resources, prompts, examples, and API documentation. Open dossier |
|---|---|---|---|---|
| Trust | ||||
| Install risk | Review first | Review first | Review first | Review first |
| Notes | Safety ✓ Privacy ✓ | Safety ✓ Privacy ✓ | Safety · Privacy · | Safety ✓ Privacy ✓ |
| Category | tools | tools | tools | tools |
| Source | source-backed | source-backed | source-backed | source-backed |
| Author | OpenAI | OpenAI | Mastra | Model Context Protocol |
| Added | 2026-06-18 | 2026-06-18 | 2026-04-27 | 2026-06-18 |
| Platforms | CLI | CLI | CLI | CLI |
| Source repo | — | — | — | — |
| Safety notes | ✓Agents can call function tools, hosted tools, MCP tools, realtime tools, and sandbox agents; treat every tool as an API endpoint with explicit authorization, input validation, rate limits, and side-effect controls. Sandbox agents can inspect files, run commands, apply patches, and carry workspace state across longer tasks; restrict workspace scope and require human approval before destructive or high-impact actions. Cloudflare Workers support is described upstream as experimental; review runtime compatibility, secrets, outbound network access, logging, request limits, and `nodejs_compat` behavior before production use. Guardrails help validate inputs and outputs, but they do not replace permission checks, least-privilege credentials, audit logs, or human review for risky operations. Handoffs and agents-as-tools can delegate work across agents; document which agent owns each tool, decision, retry, rollback, and escalation path. | ✓Agents can call function tools, hosted tools, MCP tools, realtime tools, and sandbox agents; treat every tool as an API endpoint with explicit authorization, input validation, rate limits, and side-effect controls. Sandbox agents can inspect files, run commands, apply patches, and carry workspace state across longer tasks; restrict workspace scope and require human approval before destructive or high-impact actions. Guardrails are useful runtime checks, but they do not replace permission checks, least-privilege credentials, audit logs, or human review for risky operations. Handoffs and agents-as-tools can delegate work across agents; document which agent owns each tool, decision, retry, rollback, and escalation path. Realtime voice agents and human-in-the-loop flows need clear consent, interruption, recording, and operator takeover behavior. | — missing | ✓The official TypeScript SDK is a protocol library; your MCP server's tool handlers, resources, prompts, transports, and auth logic determine the real risk. Treat every registered tool as a model-callable API endpoint and validate inputs, enforce permissions, bound side effects, and sanitize failures. HTTP and framework middleware deployments need host validation, authentication, TLS, request limits, logging policy, and abuse controls. The upstream main branch documents v2 pre-alpha work; use the production v1 package for stable deployments unless you intentionally accept alpha API churn. |
| Privacy notes | ✓Prompts, instructions, tool arguments, tool outputs, session history, traces, realtime audio events, sandbox files, logs, provider responses, and errors may contain user or workspace data. Do not expose secrets, tokens, private file paths, customer records, credentials, internal identifiers, raw exceptions, or voice transcripts through traces, logs, prompts, tool schemas, or examples. When using MCP servers, hosted tools, session stores, worker logs, observability systems, or deployment platforms, review each service's retention, access control, and third-party data handling separately. If sandbox agents operate on repositories or user files, define which files can be mounted, modified, committed, uploaded, logged, or returned to the model. | ✓Prompts, instructions, tool arguments, tool outputs, session history, traces, realtime audio events, sandbox files, logs, provider responses, and errors may contain user or workspace data. Do not expose secrets, tokens, private file paths, customer records, credentials, internal identifiers, or raw exceptions through traces, logs, prompts, tool schemas, or examples. When using MCP servers, hosted tools, Redis sessions, SQL-backed sessions, or observability systems, review each service's retention, access control, and third-party data handling separately. If sandbox agents operate on repositories or user files, define which files can be mounted, modified, committed, uploaded, logged, or returned to the model. | — missing | ✓MCP clients and servers built with the SDK may expose tool arguments, tool results, resource contents, prompt templates, OAuth state, errors, traces, and logs. Avoid returning secrets, private file contents, customer data, privileged paths, internal identifiers, or operational metadata through schemas, examples, errors, or logs. Document which MCP client, server, model provider, transport, middleware layer, and logging system can observe each request. |
| Prerequisites |
|
| — none listed |
|
| Install | | | — | |
| Config | — | — | — | — |
| Citations | ||||
| Claim | Unclaimed | Unclaimed | Unclaimed | Unclaimed |
Featured in
Signals
Loading live community signals…
A short, calm digest of reviewed Claude resources. Unsubscribe any time.