How openai/openai-realtime-agents works
This is a Next.js demo for realtime voice agents, centered on a browser conversation that connects to a selected agent scenario, streams a session, and presents its transcript and events. It demonstrates two major patterns: a realtime chat agent delegating complex work to a text supervisor, and customer-service specialists handing off by intent. The graph also includes session history, moderation, and audio export. Some runtime wiring is unsampled; dashed handoff links are documented patterns, not verified call sites.
Main entry points: App.tsx Conversation app · useRealtimeSession.ts Realtime session hook · authentication.ts Retail authentication · useHandleSessionHistory.ts Session history handlers
Components 20
Browser experience
- Conversation app
src/app/App.tsx - Transcript view
src/app/components/Transcript.tsx - Event view
src/app/components/Events.tsx - Session toolbar
src/app/components/BottomToolbar.tsx
Realtime session
- Realtime session hook
src/app/hooks/useRealtimeSession.ts - Responses API route
src/app/api/responses/route.ts
Agent scenarios
- Chat supervisor scenario
src/app/agentConfigs/chatSupervisor/index.ts - Text supervisor
src/app/agentConfigs/chatSupervisor/supervisorAgent.ts - Retail authentication
src/app/agentConfigs/customerServiceRetail/authentication.ts - Retail returns
src/app/agentConfigs/customerServiceRetail/returns.ts - Retail sales
src/app/agentConfigs/customerServiceRetail/sales.ts - Simple handoff
src/app/agentConfigs/simpleHandoff.ts - Moderation guardrail
src/app/agentConfigs/guardrails.ts
Session support
- Session history handlers
src/app/hooks/useHandleSessionHistory.ts - Transcript state
src/app/contexts/TranscriptContext.tsx - Event state
src/app/contexts/EventContext.tsx - Audio export
src/app/hooks/useAudioDownload.ts - Audio conversion
src/app/lib/audioUtils.ts
Other components
- User
- Agents SDK
Connections 21
- User → Conversation app: starts conversation
README.md - Conversation app → Realtime session hook: connects session
src/app/App.tsx - Conversation app → Chat supervisor scenario: selects scenario
src/app/App.tsx - Conversation app → Retail authentication: selects scenario
src/app/App.tsx - Conversation app → Simple handoff: selects scenario
src/app/App.tsx - Conversation app → Moderation guardrail: creates moderation
src/app/App.tsx - Conversation app → Transcript view: renders
src/app/App.tsx - Conversation app → Event view: renders
src/app/App.tsx - Conversation app → Session toolbar: renders
src/app/App.tsx - Realtime session hook → Agents SDK: uses session SDK
src/app/hooks/useRealtimeSession.ts - Chat supervisor scenario → Text supervisor: delegates decisions
src/app/agentConfigs/chatSupervisor/index.ts - Text supervisor → Responses API route: requests completion
src/app/agentConfigs/chatSupervisor/supervisorAgent.ts - Retail authentication → Retail returns: hands off by intent
README.md - Retail authentication → Retail sales: hands off by intent
README.md - Session history handlers → Transcript state: updates transcript
src/app/hooks/useHandleSessionHistory.ts - Session history handlers → Event state: logs server events
src/app/hooks/useHandleSessionHistory.ts - Realtime session hook → Session history handlers: registers history handlers
src/app/hooks/useRealtimeSession.ts - Transcript view → Transcript state: reads transcript
src/app/components/Transcript.tsx - Event view → Event state: reads events
src/app/components/Events.tsx - Audio export → Audio conversion: converts recording
src/app/hooks/useAudioDownload.ts - Conversation app → Audio export: offers audio export
src/app/App.tsx