Building Multi-Agent Workflows in TypeScript Without the Headaches

You've probably felt it—that moment when a single LLM call isn't enough, and you need an agent that can delegate, use tools, and maybe even talk to a user in real time. Coordinating all of that by hand gets messy fast. That's exactly where the OpenAI Agents SDK for JavaScript and TypeScript comes in. It's a lightweight framework for building multi-agent systems that handles the orchestration boilerplate so you don't have to.

What It Does

The OpenAI Agents SDK is a provider-agnostic framework for building multi-agent workflows in JavaScript and TypeScript. It runs on Node.js 22 or later, Deno, and Bun, with experimental support for Cloudflare Workers (assuming you enable nodejs_compat).

At its core, the SDK is built around a few key concepts. You've got Agents—LLMs configured with instructions, tools, guardrails, and handoffs. Then there are Sandbox Agents, which pair an agent with a filesystem workspace for longer-running tasks that need to execute commands or maintain state. Realtime Agents handle low-latency spoken interactions with the same tooling and guardrails you'd use for text.

The SDK also includes Agents as Tools and Handoffs for delegation, Tools for letting agents take actions (including MCP and hosted tools), Guardrails for input and output validation, Human in the Loop mechanisms, Sessions for automatic conversation history management, and Tracing to track and debug agent runs.

The design philosophy here is interesting: instead of forcing you into one pattern, it gives you building blocks that compose together. You can start with a simple text agent and scale up to sandboxed, voice-enabled, multi-agent systems as your needs grow.

Why It's Cool

What makes this SDK stand out isn't any single feature—it's how the pieces fit together. Here's what caught my attention:

• Provider-agnostic by design. You're not locked into OpenAI's models exclusively. The SDK supports OpenAI APIs and more, which is a refreshing stance for a framework coming from OpenAI itself.

• Sandbox Agents are genuinely useful. The ability to pair an agent with a filesystem workspace and let it run commands is huge for real-world tasks. Think code review, repo inspection, or any workflow where an agent needs to actually do things, not just generate text. The beta status is worth noting, but the concept is solid.

• Voice support baked in. Realtime Agents for spoken interactions with the full toolset—tools, guardrails, handoffs, conversation history—means you don't need a separate voice stack. It's all in one SDK.

• Traceability is a first-class citizen. Built-in tracing lets you view, debug, and optimize your workflows. When you're orchestrating multiple agents, being able to see exactly what happened in a run is invaluable. That's the kind of thing you don't realize you need until you're staring at a confusing multi-agent failure.

• Sessions handle the conversation state. Automatic history management across agent runs removes a whole class of bugs where you forget to pass context along. It's a small thing, but it's exactly the kind of boilerplate that eats up your time.

The examples directory is worth exploring too—it shows the SDK in action rather than just describing what it can do.

How to Try It

Getting started is straightforward. Install the package and its peer dependency:

npm install @openai/agents zod

Then build a basic text agent with just a few lines:

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);

If you want to try a sandbox agent, the setup is a bit more involved. The example uses UnixLocalSandboxClient, which works on macOS and Linux. On Windows, you'll need DockerSandboxClient or a hosted sandbox client instead. Here's a taste:

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

You can check out the full documentation and the repository at github.com/openai/openai-agents-js to dig into the details and explore the examples.

Final Thoughts

This SDK is best for developers who are building production-grade agent systems in TypeScript and want structure without a heavyweight framework. It's not trying to be the simplest possible wrapper—it's aiming to be a complete toolkit for real workflows, which means there's a learning curve around concepts like sandboxes, sessions, and handoffs. But if you're past the toy stage and need things like tracing, guardrails, and human-in-the-loop mechanisms, this gives you a solid foundation. The provider-agnostic approach and the fact that it's from OpenAI itself (so it stays aligned with the latest model capabilities) make it a strong bet for your next agent project.

Follow @githubprojects for more developer tools and open source projects.