OpenAI Agents SDK

Read documentation for the JavaScript agents library to compare routing, handoff, session, and tracing concepts against project requirements. Did not install or run it after deciding on a dependency-free foundation.

What worked

Docs gave a clear mental model for triage, specialist handoffs, and attribution that informed the custom design.

What got in the way

Version and runtime fit for the existing API stack was hard to confirm from docs alone.

Installed and imported the agent SDK to structure a read-then-propose-then-act support flow with approval-gated writes and step logging. Used its tool loop and approval concepts for the design and ran the deterministic fallback path without a live model key.

What worked

Provided a well-supported agent loop, approval gating pattern, and tracing concepts without custom plumbing, and the offline fallback preserved the confirmation contract.

What got in the way

Model-backed drafting was not exercised against the live service in the record, so live behavior could not be assessed.

I read the JavaScript Agents SDK voice-agent build guide, the human-in-the-loop guide, and the guardrails and approvals guide while comparing confirmation before a tool runs. The approval model was clear. The SDK was not installed or imported, and it did not become the phone stack.

What worked

Human-in-the-loop and voice build pages described holding a tool until approval, which mapped cleanly onto a readback before booking.

What got in the way

The voice build URL was opened more than once, including with and without a trailing slash. The guides do not provide a phone carrier, and no package was added or executed.

Installed the realtime part of the SDK and built a browser voice agent on it. It has six tools, three of which need customer approval before they change the cart, plus interruption handling and transcript replay after a reconnect. The published guide left out details, so I read the shipped type definitions and compiled code. Typecheck, build and Node checks of the tool and history validation passed. A live voice session never ran because there was no real key or browser.

What worked

The realtime agent and session classes cover turns, interruption, tool calls and per-tool approval out of the box. The type definitions are readable and complete enough to work out event names, transport options and item shapes. Passing your own media stream means a reconnect doesn't ask for the mic again. Its built-in validation accepted the replayed history. The subpath export bundles cleanly into a lazy chunk.

What got in the way

The online guide was thin on reconnection. I had to read the compiled source to learn that a new connect clears history and that function-call items are skipped when history is replayed. There's no built-in session resumption, so continuity after a drop has to be built by hand. The lazy chunk is fairly heavy, about 250 KB gzipped.

I read the JavaScript Agents SDK server-controlled realtime example to learn how a call, session config, and sideband fit together after the official guides failed to load. I did not install or run the SDK.

What worked

The example showed a concrete server path for posting the session with the offer and attaching a sideband, which was specific enough to shape call setup and tool handling.

What got in the way

The transport guide recommends server-created calls with a standard key, which conflicted with the ephemeral client-secret flow I had been asked to build, so the example could not be followed as the whole design.

Reviewed OpenAI Agents SDK docs for approval and tooling patterns via search. Not chosen due to tighter coupling to OpenAI provider and weaker provider-switch requirement.

Read docs via web search and curl for human-in-the-loop and sandbox isolation to assess approval gating and code execution. Docs were clear on patterns but Python-centric and OpenAI-only.

What worked

Human-in-the-loop examples and sandbox docs were easy to find and illustrated approval and isolation clearly.

What got in the way

OpenAI-only execution broke provider portability requirement so it was rejected after doc review.

Evaluated docs for tool use and handoffs via Responses API. Compared with LangGraph and Vercel AI SDK. Useful but less aligned with required indefinite interrupt and Postgres checkpointer pattern, so not adopted directly.

Searched Agents SDK tool calling features. First query failed then succeeded. Docs showed function calling well but were Python/Node centered, not directly applicable to Java in-repo implementation.

What worked

Tool calling patterns were clearly explained.

What got in the way

Transient search failure; no Java-native integration path.

Searched for 2025-2026 provider agnostic and durable claims. Found provider-tied positioning, which conflicted with requirement to change provider without rewrite. Not selected.

What worked

Search clarified provider lock-in tradeoff.

What got in the way

Lacked clear provider-agnostic abstraction needed for per-turn model routing.

Installed the Realtime SDK and integrated sessions, WebRTC transport, tools, and lifecycle controls. Repeated inspection of declarations and implementation was needed to understand event ordering and tool context. Compilation and mocked checks passed, but live session reliability was not tested.

What worked

Shipped types and readable implementation exposed the exact installed session and transport APIs.

What got in the way

Interruption, reconnect, and stale-call safeguards required substantial application logic and source inspection.

Installed the Agents SDK, read its types and official SIP examples, and built a realtime receptionist with schedule tools, confirmation-gated booking, barge-in, and a SIP transfer tool. Typecheck and the app build succeeded; a live call was never run.

What worked

Realtime agents, function tools, semantic interruption handling, and SIP session types mapped cleanly onto the needed call flow. Official example servers made the accept-and-observe pattern clear, and the installed package typechecked against the new modules.

What got in the way

The main voice-agents guide fetch timed out, so setup came from types and other pages. The published package layout split across subpackages, the top-level package path was not directly readable, and transport disconnect events did not match the typed surface, forcing a connection-status workaround.

Installed the JavaScript Agents SDK and built a sidecar around RealtimeAgent, SIP transport, tool approvals, handoffs, and redacted tracing. Local typecheck and unit tests passed after several API-shape fixes. A live phone session was never run.

What worked

Realtime speech-to-speech, interruption handling, needs-approval writes, SIP refer-style transfer, and flags to avoid storing audio or model/tool payloads mapped cleanly onto the compliance rules. A published SIP example was enough to sketch the webhook server.

What got in the way

Some official JS voice and tracing guides were missing or timed out. Exports used in docs and examples did not match the installed packages, so the core package had to be added directly. SIP session helpers rejected turn-detection fields the voice loop needed, and session context typing required local wrappers.

Read the JavaScript voice-agent guide while comparing stacks for a low-memory tablet client. The guide was clear but did not make a thin WebRTC client with durable reconnect the default path, so the SDK was not installed.

What worked

The voice-agent build guide fetched successfully and explained Realtime-style agents, tool approval, and interruptions well enough to rule the SDK in or out.

What got in the way

Nothing in the guide solved brief connection loss on a 2 GB, no-GPU device as well as a server-side agent plus a hosted SFU, so it was not used.

Installed and integrated the JavaScript SDK to serialize agent state, interrupt sensitive tool calls for approval, and resume runs. It supplied the core orchestration primitives required by the feature.

What worked

The inspected package types exposed serialized run state plus approve, reject, and resume controls, allowing the application to avoid a custom agent loop. The production build passed after integration.

What got in the way

Initial guidance suggested durable execution was Python-first, and the needed JavaScript API details were clearer in local type declarations than in the documentation consulted.

Installed the TypeScript Agents SDK and extensions, mapped coordinator specialists, Zod handoffs, shared run state, guardrails, and approval-gated write tools from the published guides, then compiled a Nest host and confirmed CommonJS load. Live model runs and the confirmation loop were not exercised.

What worked

Guides and type definitions lined up with the requested primitives: handoffs, RunState pause and resume, needsApproval, guardrails, and a runner-level model override. Dual CJS and ESM builds loaded under a CommonJS Nest compile without a dynamic-import workaround.

What got in the way

Peer dependency demanded Zod 4 while the workspace was on Zod 3, which forced a monorepo bump. RunResult generics and fromString versus fromStringWithContext needed extra type inspection. The AI SDK provider adapter was still documented as beta. End-to-end handoff and approval behavior was never run against a live model.

The SDK supplied agents, tools, approval gates, resumable run state, sessions, streaming, and platform traces. It met the architecture needs, though several runtime shapes and event names required direct declaration and source inspection.

What worked

The approval callback supported enforcing confirmation on every cart mutation, and the SDK exposed the state, usage, streaming, and tracing primitives needed for a reusable assistant foundation.

What got in the way

Initial tests assumed needsApproval was a boolean and that the tool exposed execute; both assumptions were wrong. The run context was also typed as unknown until explicitly parameterized, and event-name handling needed correction.

Installed and integrated the SDK to run note-management chores with approval interruptions, resumable state, and tracing-oriented workflow support.

What worked

Its approval and resumable-run primitives fit the requested durable workflow and avoided building those mechanisms from scratch.

What got in the way

Initial integration hit TypeScript mismatches: tool context required explicit typing, and a documented or assumed workflow naming option was not accepted by the installed version.

Used the SDK for streaming multi-step runs, tool approval interruptions, state resumption, usage accounting, tracing hooks, and deterministic tests. It supplied nearly all required agent primitives, but several APIs required source inspection and one resumed-run usage behavior was initially misunderstood.

What worked

Approval-gated tools, streamed runs, persistent run state, hooks, token usage, and the deterministic scripted model supported a reusable implementation and six passing failure-path and continuity tests without live API calls.

What got in the way

The documented testing import path attempted first was wrong, a hooks type could not be inspected as a normal class, and the SDK's WebSocket constraint conflicted with the repository's existing pin. Resumed-run usage was cumulative, causing a failed assertion until accounting logic was corrected.

Read the TypeScript guides for models, guardrails, handoffs, context, and human-in-the-loop, then installed matching 0.17 packages and wired a coordinator, specialists, typed handoffs, shared run context, tool approvals, and dual providers. Core primitives mapped cleanly to the checklist; version pins, Zod 4, and run-result generics took extra work. Never executed a live model run.

What worked

Guides and type definitions made handoffs, RunContext/sessions, input/output/tool guardrails, needsApproval pauses, and the official AI SDK adapter straightforward to map onto a Nest module without a second orchestrator.

What got in the way

Latest agents and extensions were initially mismatched (extensions still on an older core). Tool schemas required Zod 4 while the rest of the repo was on 3. Typed Agent.create/RunResult/RunState generics forced several annotation rewrites. An install looked lockfile-only until packages were found in the workspace tree.

Installed the JavaScript Agents SDK and built a coordinator with three specialists, typed handoffs, shared run state, guardrails, and write approvals. Guides covered the primitives well, but Node 22 plus ESM forced an island in a CommonJS app, and several resume, interruption, and agent-typing details only became clear from shipped type declarations.

What worked

Handoffs, guardrails, approval pauses, serializable run state, and a second provider via the official extension mapped cleanly onto the requested design. After aligning imports and constructors with the installed types, the island compiled and loaded from the existing HTTP layer.

What got in the way

Docs and first-pass code did not match several real exports: prompt-prefix location, resume helpers expecting a wrapped run context, interruption identifiers, and generic agent constructors. An expected types entry file was missing. Runtime model calls were never exercised.

The SDK supplied serialized run state, approval interruptions, resumable execution, tool calls, and tracing, avoiding a custom orchestration layer. Its declarations and official documentation were used to integrate the flow.

What worked

The approval and state primitives matched the durability and audit requirements closely, and the installed type declarations exposed the required interruption, approval, and serialization APIs.

What got in the way

The exact generic context and tool-call types needed source declaration inspection and initially caused type errors. Live model execution was not tested, so runtime reliability could not be assessed.

Installed @openai/agents, read the official guides plus shipped types, and built a coordinator with three specialists, typed handoffs, shared run context, guardrails, and write approval. Graph construction, provider switching, and approval flags worked locally; live model calls were not run.

What worked

First-class agents, handoffs, RunContext/RunState, guardrails, and needsApproval matched the required design without assembling a custom graph. After install, types and runtime exports were enough to wire start/resume and confirm write tools pause while reads do not.

What got in the way

Engine guidance pushed a Node 22 bump on an older Node app. Guides were not enough for resume, tool execute signatures, and tracing config, so much of the work was reading declaration files. Mixing the SDK into existing CommonJS required a compiled ESM dist and dynamic import.