OpenAI Agents SDK for JavaScript: three runtimes, three agent types, one truncated example
A lightweight, powerful framework for multi-agent workflows and voice agents
At a glance
- What is it?
- A provider agnostic TypeScript framework for agent workflows, read through what its own files show: a root package version of 0.0.1 beside published tags at v0.18.0, a sandbox example that stops mid statement, and a browser token path that never touches your server key.
- Who is it for?
- This SDK fits a TypeScript team that wants agent loops, handoffs, guardrails, and tracing in one package with realtime and sandbox agents alongside the plain one, and it does not fit a deployment that cannot add zod to its dependency list or that needs a Windows host to run a local sandbox.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- openai/openai-agents-js4,020 ★ · +198
| Repository | 2026-09-15 | 2026-11-15 |
|---|---|---|
| openai/openai-agents-js | 3.8k | 4k |
198 Stars in the last 61 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The root package version reads 0.0.1 while releases are at v0.18.0
The package.json at the repository root is marked private and carries version 0.0.1, which is not a released version of anything. The published tags tell a different story: v0.18.0 released on 2026-09-10, preceded by v0.17.2 and v0.17.1 both on 2026-09-08. That gap is ordinary for a pnpm workspace, since the root is a private container for scripts and never published, and pnpm-workspace.yaml sits beside pnpm-lock.yaml to make the arrangement explicit. It matters in one specific way: anyone reading version from the root manifest to find out what they are running will get a number that means nothing. The install command does not use the root package either. It installs the published package by name, with a second package pulled in beside it:
npm install @openai/agents zodSo the dependency a new project declares is zod, not something transitive, and the framework's own schema handling is a peer of your application rather than an implementation detail.
zod is a declared dependency, not an implementation detail
The install line is the first place the design becomes visible: npm install @openai/agents zod lists both packages because schema validation is a separate concern the framework expects the application to bring. That shows up again in the acknowledgements, where zod is credited first for schema validation, before the build tooling. The examples directory carries an examples/standard-schema/ entry alongside the others, so the schema layer is treated as a swappable piece rather than a fixed one. For a team already using zod, nothing changes. For a team that picked a different validator, or one that has a policy against adding validation libraries, the SDK arrives with an assumption baked into its install instructions. It also means the package graph is not self contained: a mismatch between the zod version you install and the one the SDK was built against is a failure mode the install command gives you no way to detect.
Three runtimes are supported and one is experimental
The supported environment list is short and specific: Node.js 22 or later, Deno, and Bun. Below that sits a separate heading for experimental support, and the single entry there is Cloudflare Workers with nodejs_compat enabled. The split matters because the flag is the condition, not the runtime: Workers without that compatibility mode is not on the list at all. Node 22 as a floor also means the framework is not usable on the Node versions still common in deployed applications, which is a constraint on the host rather than on the code. The troubleshooting page is pointed to for detail, so the specifics of what works on each runtime live outside the README. The three named runtimes share one further requirement visible in the same document: the server side key is read from OPENAI_API_KEY in the environment, which is what ties text and sandbox agents to a backend process rather than to a browser.
The sandbox example stops in the middle of a console call
The second code sample is the one to be careful with. It builds a SandboxAgent named Workspace Assistant on model gpt-5.5, gives it a manifest with a single entry built by gitRepo against openai/openai-agents-js, and passes a sandbox client as the third argument to run. The sample then ends at:
const result = await run(
agent,
'Inspect the repo README and summarize what this project does.',
{ sandbox: { client: new UnixLocalSandboxClient() } },
);
console.log(reThe final line is half written. There is no closing statement, no semicolon, and no output for the text agent case either. Everything above that point is complete and runnable, so the manifest shape and the run options are readable from it, but the code as printed will not parse. Copying it verbatim produces a syntax error at the last line rather than a missing feature, which is at least a loud failure. The instructions given with it are also the part that carries the real constraint, and they are stated in prose rather than in the code.
Windows has no local sandbox client in this example
The sandbox section states the platform boundary directly. The sample uses UnixLocalSandboxClient, which is supported on macOS and Linux. On Windows the instruction is to use DockerSandboxClient or a hosted sandbox client instead, with setup details on a separate sandbox clients page. That means the three agent shapes are not equally portable: the plain Agent needs nothing but a key, the Realtime agent needs a browser and a token, and the Sandbox agent needs a host that can give it a filesystem workspace and run commands. A team standardising on Windows machines does not get a local path for the third one, and the manifest abstraction in the sample does not change that, since the manifest describes what goes into the workspace while the client decides where the workspace exists. The commit history position here is recent, dated 2026-10-02, so these client options reflect current work rather than a settled historical decision.
Browser realtime agents never see the server key
The key handling splits by agent type and the split is explicit. Text and sandbox agents read OPENAI_API_KEY from the server environment. For a browser based realtime agent the instruction is different: the server creates a short-lived ephemeral client token and passes it into session.connect(...), and the placeholder in the sample is written as the client-api-key argument rather than the server key.
const session = new RealtimeSession(agent);
await session.connect({ apiKey: '<client-api-key>' });The comment above the constructor notes that it connects the microphone and audio output automatically in the browser over WebRTC, which is why the token has to be minted server side in the first place: a browser session cannot read an environment variable on your server. Anyone wiring this up has to build that one endpoint themselves, since no route for minting the token appears in any of the samples. The realtime entry point is a separate subpath, @openai/agents/realtime, so the voice surface is an opt in import rather than part of the main package.
Pull requests are closed to anyone outside the collaborator list
The contributing section is where the project's own policy is stated, and it is narrower than the rest of the document's openness. Bug reports and feature requests go through GitHub issues, which anyone can file. Pull requests are limited to repository collaborators, and the text says explicitly that pull requests from non collaborators are not accepted, with the policy and development guide left to CONTRIBUTING.md and vulnerabilities routed through SECURITY.md. The repository layout backs that up: pull request checks live in .github/, changes are managed through .changeset/, and there are hooks under .husky/ alongside .prettierrc and .prettierignore for formatting. AGENTS.md and CLAUDE.md sit at the root next to PLANS.md and CONTRIBUTING.md, and the presence of .agents/ suggests agent facing instructions are part of the repository rather than an afterthought. So a bug found in the SDK is reported, not patched, unless you are already on the collaborator list.
Editorial conclusion
This SDK fits a TypeScript team that wants agent loops, handoffs, guardrails, and tracing in one package with realtime and sandbox agents alongside the plain one, and it does not fit a deployment that cannot add zod to its dependency list or that needs a Windows host to run a local sandbox. Before building on it, read the sandbox client choice carefully, since UnixLocalSandboxClient is macOS and Linux only and Windows means a Docker client or a hosted one, and check the sandbox example against your own editor because the version on the page stops in the middle of a console call. Keep the browser token server side, and do not read the root package version as the released version.
Frequently asked questions
How do I install the OpenAI Agents SDK for JavaScript?
The install command is npm install @openai/agents zod, with zod listed as a separate package rather than a transitive dependency. Node.js 22 or later is required, with Deno and Bun also supported and Cloudflare Workers under experimental support when nodejs_compat is enabled.
What kinds of agents does the OpenAI Agents SDK support?
Four kinds are described: regular Agents configured with instructions, tools, guardrails, and handoffs; Sandbox Agents paired with a filesystem workspace; Realtime Agents for low latency spoken interaction; and agents treated as tools or reached through handoffs. Around those sit tools, guardrails, human in the loop mechanisms, sessions for history, and tracing.
Can I run the OpenAI Agents SDK sandbox agent on Windows?
Not with the client used in the sample. UnixLocalSandboxClient is supported on macOS and Linux, and on Windows the guidance is to use DockerSandboxClient or a hosted sandbox client instead, with setup details on the sandbox clients page.
Where does the OpenAI Agents SDK get the API key for browser realtime agents?
Text and sandbox agents read OPENAI_API_KEY from the server environment. A browser based realtime agent instead needs a short-lived ephemeral client token created by your server and passed to session.connect(...), which is why the sample shows a client-api-key placeholder rather than the server key.
Can I send a pull request to the OpenAI Agents SDK?
Only if you are a repository collaborator. Pull requests are limited to collaborators and are not accepted from non collaborators, while bug reports and feature requests are welcome through GitHub issues. Vulnerabilities go through SECURITY.md instead.
Official sources
Where developers are discussing it
Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 1 in the last 30 days; newest first.
- State of AI Instruction Quality: Coding Agent Comparisondev.to · Oct 21, 2026 · 6 points · 0 comments
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/openai-openai-agents-js)Star history chart for your README
[](https://hysenlabs.com/projects/openai-openai-agents-js)Was this useful?