Runtime architecture · product judgment · interview preparation

The OpenAI Agents SDK, from the inside out.

A PM-oriented field guide to the runtime wrapped around the Responses API—what it abstracts, what developers control, and which product tensions matter.

9 CHAPTERS
07:43 VIDEO
PM EDITION
01

The model call is the small part.
The SDK’s product value is reliable execution around intelligence: dispatch, state, specialization, safety, approvals, debugging, and cost visibility.

00 · FILM

The complete walkthrough

The video is generated as a deterministic HTML composition in HyperFrames. It mirrors this guide’s architecture language and uses nine measured narration chapters as the timing authority.

07:43 · 1920×1080 · narrated · music bed · generated from HTML · open standalone player
01 · ARCHITECTURE

SDK above, Responses below

The Responses API is the model-facing substrate. The SDK’s default model adapter speaks that API, while Runner provides the client-side control loop and the rest of the package supplies reusable application and production primitives.

PRODUCTION PLANETracing · usage · approvals · durable execution · realtime
APPLICATIONAgent · tools · handoffs · guardrails · sessions
RUNNERTurns · dispatch · result injection · stop conditions
MODEL ADAPTEROpenAIResponsesModel translates SDK concepts into API objects
RESPONSES APIInput items · output items · hosted tools · streaming events
FIG. 1 — The wrapper adds orchestration and operations; it does not hide the underlying execution primitive.

Use Responses directly

OWN THE LOOP
  • Short-lived workflows
  • Maximum control over dispatch and state
  • Custom orchestration is the product

Use the Agents SDK

MANAGED RUNTIME
  • Multiple turns and tool actions
  • Guardrails, handoffs, sessions or approvals
  • Tracing and production operations matter
02 · RUNNER

The control loop

Every entry point—async, synchronous, or streamed—feeds the same core state machine. Final output ends a run; tool calls and handoffs create another turn.

STARTAgent + inputCALL MODELResponses by defaultINSPECT ITEMSfinal · tool · handoffEXECUTEor transferAPPEND + REPEATuntil complete or max turns
FIG. 2 — Tracing and usage instrumentation attach across the loop, not only to the final response.
03 · COMPONENTS

The developer surface

The SDK remains approachable because most developers begin with Agent, a tool, and Runner. Additional surfaces appear as the workflow takes on production responsibilities.

DEFINE

Agent

Instructions, prompt templates, model settings, tools, handoffs, guardrails, hooks and structured output.

ACT

Tools

Hosted OpenAI tools, local runtimes, Python functions, MCP, and agents exposed as callable tools.

COORDINATE

Runner + results

Turns, streaming, tool execution, handoffs, interruptions, raw response items and resumable state.

REMEMBER

Sessions

Client-managed history storage. An alternative to server-side conversation and response continuation.

CONTROL

Guardrails + HITL

Input, tool and output checks; approval interruptions that can be serialized and resumed.

OPERATE

Tracing + usage

Generations, tool calls, handoffs, custom spans, tokens, latency and cost instrumentation.

04 · ORCHESTRATION

Manager or handoff?

A manager calls specialists as tools and keeps authority. A handoff changes the active agent and conversation owner. The difference affects policy, context, latency and evaluation—not just code organization.

Manager pattern

CENTRAL CONTROL

One agent synthesizes specialist results and owns the final response.

  • Coherent output
  • Central policy enforcement
  • More context returns to manager

Handoff pattern

DISTRIBUTED OWNERSHIP

A routing decision transfers the conversation to a domain specialist.

  • Natural support routing
  • Specialist owns subsequent turns
  • History filtering becomes important
05 · STATE & SAFETY

Explicit ownership

Memory, safety and approvals are separate concerns. The architecture is strongest when the team chooses each intentionally rather than treating “agent state” as one undifferentiated blob.

CLIENT SESSION
LOADRUNPERSIST ITEMS
SERVER CONTINUATION
conversation_idORprevious_response_id
GUARDRAILS
INPUTTOOLOUTPUT
HUMAN
INTERRUPTAPPROVE / REJECTRESUME
FIG. 3 — Sessions and server continuation are alternative memory ownership models; human approval is a state transition.
06 · OPERATIONS

From demo to product

Tracing is a debugging interface and a product feedback loop. Usage turns architectural choices—more agents, more tools, longer histories—into measurable cost and latency.

RELIABILITYCompletion

Tool failure, retry, guardrail and resume rates.

EFFICIENCYCost / task

Calls, tokens, cached share and latency.

DXTrace → fix

How quickly developers diagnose and correct failures.

07 · PM INTERVIEW

Turn architecture into judgment

Strong PM answers connect developer friction, design principles, metrics and tensions. Avoid a feature-tour answer; explain why the runtime boundary exists and what good product outcomes look like.

User problem

  • Orchestration tax
  • Unreliable action loops
  • Slow debugging and evaluation

Design principles

  • Few composable primitives
  • Strong defaults plus escape hatches
  • Safety and observability in the runtime

Metrics hierarchy

  • Time to first successful tool run
  • Completion, retry and resume rates
  • Latency and cost per completed task

Strategic tensions

  • Minimal abstraction vs completeness
  • Hosted capability vs local control
  • Provider breadth vs consistent semantics
  • Rich traces vs privacy
The sharp product question: which repeated failure mode should the runtime make impossible—or at least obvious?
08 · SOURCES

Official reading path

SDK overview · Agents · Running agents · Tools · Handoffs · Sessions · Tracing · Models

The companion ANALYSIS.md in the project contains the fuller written synthesis and metric framework.