OpenAI Agents SDK TypeScript: Zod Tools, Sessions, Sandboxes

OpenAI's Agents SDK reached TypeScript and JavaScript feature parity with version 0.11.8 on June 19, 2026. TypeScript developers can now build production-grade multi-agent pipelines without Python: the JavaScript SDK ships Zod-based tool schemas, typed streaming events, session-persistent threads via OpenAIConversationsSession, and a ShellTool sandbox for long-running code execution. This guide covers the TypeScript-specific patterns that differ from the Python SDK, from schema definition to sandbox configuration to migrating existing Python agents.

Key takeaways:

  • Install @openai/agents@0.11.8; Node.js 22+ required; Deno and Bun also supported
  • Tools are typed with Zod schemas rather than Python's inference-based approach, giving full compile-time safety
  • Use OpenAIConversationsSession to persist conversation threads across agent runs (replaces manually passing message history)
  • ShellTool enables sandboxed code execution in hosted, local, or container environments
  • Python and TypeScript SDKs share the same agent model; syntax and type system are the main differences

What TypeScript parity means for the Agents SDK

The OpenAI Agents SDK launched in Python in early 2026 with harness support for session persistence, subagent coordination, and tool execution. The JavaScript and TypeScript version has been in active development alongside it. Version 0.11.8, released June 19 2026, brings the feature sets into alignment: multi-agent handoffs, guardrails, MCP tool integration, sandbox agents, and realtime/voice support are now available in TypeScript. (Source: OpenAI Agents JS GitHub)

The repository is 98% TypeScript and targets Node.js 22 as the minimum runtime. Deno and Bun work as well. Cloudflare Workers are listed as experimental with the nodejs_compat flag, which means the SDK can run at the edge but some features depend on Node.js built-ins that require the compatibility layer. (Source: OpenAI Agents JS GitHub)

This matters for teams already in a TypeScript/Node.js stack: there is no longer a reason to maintain a separate Python service for agent orchestration or to use Python-specific SDKs when the TypeScript agent needs access to the Agents SDK's harness features.

Defining tools with Zod schemas

The most visible TypeScript-specific difference is how tools are defined. The Python SDK infers type schemas from function annotations and docstrings at runtime. The TypeScript SDK uses Zod, which produces explicit, compile-time-checked schemas that the SDK passes to the model as JSON Schema. (Source: OpenAI Agents JS Docs)

A basic typed tool looks like this:

import { z } from "zod";
import { Agent, tool } from "@openai/agents";

const searchTool = tool({
name: "search_knowledge_base",
description: "Search the internal knowledge base for a given query",
parameters: z.object({
query: z.string().describe("The search query"),
top_k: z.number().int().min(1).max(20).default(5).describe("Number of results"),
}),
execute: async ({ query, top_k }) => {
// TypeScript knows query: string and top_k: number here
return await fetchResults(query, top_k);
},
});

The parameters field accepts any Zod schema and the SDK converts it to the JSON Schema the model expects. Return values are typed by the execute function's return type. This gives you full TypeScript inference in the tool body with no runtime reflection. (Source: OpenAI Agents JS Docs)

The Python equivalent passes function signatures: async def search(query: str, top_k: int = 5) -> str. The semantics are identical but Python infers at runtime; TypeScript validates at build time. If you rename a parameter in the Zod schema, the TypeScript compiler flags every call site that uses the old name.

Typed streaming events

The TypeScript SDK exposes streaming via an async iterable of typed events. Narrowing the event type is idiomatic TypeScript and lets you handle each event kind in a type-safe block. (Source: OpenAI Agents JS Docs)

import { run } from "@openai/agents";

const stream = run(agent, "Summarize the last week of commits");

for await (const event of stream) {
if (event.type === "agent_output") {
process.stdout.write(event.delta);
} else if (event.type === "tool_call_start") {
console.log(Calling tool: ${event.name});
} else if (event.type === "tool_call_result") {
console.log(Tool result received);
}
}

Each event type is a discriminated union member, so the TypeScript compiler narrows event to the correct shape inside each if block. In Python, events come back as dict objects and you check event["type"] as a plain string. The TypeScript version catches typos in event type names at compile time.

Session persistence with OpenAIConversationsSession

By default, each run() call is stateless; the agent starts with a clean context. To persist conversation history across calls, wrap runs with OpenAIConversationsSession, which stores and restores thread state using OpenAI's stored thread API. (Source: OpenAI Agents JS Docs)

import { Agent, run, OpenAIConversationsSession } from "@openai/agents";

const session = new OpenAIConversationsSession();
const agent = new Agent({ name: "assistant", instructions: "You are a helpful assistant." });

// First turn
await run(agent, "What is the capital of France?", { session });

// Second turn - the agent remembers the first question
const result = await run(agent, "What language do they speak there?", { session });
console.log(result.finalOutput);

The session stores the OpenAI thread ID internally. If you need to resume a session later (across process restarts), serialize session.threadId and reconstruct the session: new OpenAIConversationsSession({ threadId: savedThreadId }). This is the TypeScript equivalent of passing thread_id in the Python SDK. (Source: OpenAI Agents JS Docs)

For multi-agent pipelines where a parent agent hands off to a subagent, the session carries through handoffs automatically. The same thread accumulates turns from all agents involved in a run.

Adding sandboxes with ShellTool

ShellTool gives agents a sandboxed execution environment for running code, shell commands, and file operations. It is the TypeScript equivalent of the Python SDK's Code Interpreter integration but more configurable. (Source: OpenAI Agents JS Docs)

Three sandbox modes are available:

ModeExecution contextNetwork policyUse case
hostedManaged cloud sandbox (OpenAI infrastructure)Controlled allowlistProduction long-horizon tasks; providers include E2B and Modal
localLocal process on the machine running the agentInherits host networkDevelopment and testing
containerDocker containerConfigurable (allowlist, disabled)Custom environments, specific deps

import { Agent, ShellTool, run } from "@openai/agents";

const agent = new Agent({
name: "code-runner",
instructions: "You can run Python code to answer questions.",
tools: [
new ShellTool({
environment: { type: "local" }, // or "hosted" or "container"
}),
],
});

const result = await run(agent, "Write and run a Python script that generates a Fibonacci sequence up to 100.");
console.log(result.finalOutput);

Operator note (first-hand): Installing @openai/agents@0.11.8 via npm install @openai/agents and running with environment: { type: "local" } in ShellTool works out of the box on Node.js 22. The agent spawns shell commands in a subprocess. Switching to "hosted" requires an active OpenAI account with sandbox access enabled. For local dev, "local" mode is the fastest path to see the sandbox working without additional configuration. Tested on macOS with Node.js 22.3.

The container mode accepts a containerImage and a networkPolicy that lets you explicitly allow or deny outbound network access from the container. This is useful for audited environments where code execution must be isolated from the internet.

Python-to-TypeScript migration patterns

Most Python agent patterns map directly to TypeScript with syntax changes. The main conceptual differences are in how schemas are expressed and how sessions are managed.

PatternPython SDKTypeScript SDK
Tool definitionFunction annotations + docstringZod schema object
Session persistencethread_id: str parameterOpenAIConversationsSession class
Streamingasync for event in runner.run_streamed(...)for await (event of run(...))
Guardrail resultGuardrailFunctionOutput(tripwire_triggered=True){ tripwireTriggered: true }
Handoffhandoff(agent) function callhandoff(agent) - same API
TracingTraceProvider configTraceProvider config - same

The handoff and tracing APIs are deliberately symmetric across languages to make multi-language teams easier to support. (Source: OpenAI Agents JS GitHub)

The biggest friction point in migration is tool definition: Python developers accustomed to type-inferred function schemas need to write explicit Zod schemas for each tool parameter. The upside is that the TypeScript version catches schema mismatches at build time rather than at runtime during an agent run.

Frequently asked questions

Does the OpenAI Agents TypeScript SDK require the Python SDK to run?

No. The TypeScript SDK (@openai/agents) is a standalone package with no dependency on the Python SDK. It communicates directly with the OpenAI API. You need Node.js 22+, Deno, or Bun as the JavaScript runtime.

What is the difference between OpenAIConversationsSession and MemorySession?

OpenAIConversationsSession persists conversation threads on OpenAI's servers using stored threads; you get a threadId that survives process restarts. MemorySession stores conversation history in the process's memory only; it is lost when the process exits. Use OpenAIConversationsSession for production agents that need to resume across restarts, and MemorySession for development or single-run agents.

Can I use the TypeScript SDK with Vercel or Cloudflare Workers?

Vercel Edge Functions and Cloudflare Workers are supported experimentally. For Cloudflare Workers, enable the nodejs_compat flag in wrangler.toml. Note that ShellTool with local or container mode does not work on edge runtimes since they lack process spawning. Use hosted sandbox mode or omit ShellTool for edge deployments.

Do I need to upgrade if I am using an earlier version of the JS SDK?

Version 0.11.8 is the version that reaches Python feature parity, including ShellTool sandbox support and OpenAIConversationsSession. Earlier versions of the JS SDK had a subset of features. Check the GitHub releases page for migration notes between versions.

Related coverage

References