# openai/openai-realtime-agents architecture

> Architecture diagram of the GitHub repository openai/openai-realtime-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openai/openai-realtime-agents
- Repository: https://github.com/openai/openai-realtime-agents

## Overview

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: [`src/app/App.tsx`](https://github.com/openai/openai-realtime-agents/blob/main/src/app/App.tsx) (Conversation app), [`src/app/hooks/useRealtimeSession.ts`](https://github.com/openai/openai-realtime-agents/blob/main/src/app/hooks/useRealtimeSession.ts) (Realtime session hook), [`src/app/agentConfigs/customerServiceRetail/authentication.ts`](https://github.com/openai/openai-realtime-agents/blob/main/src/app/agentConfigs/customerServiceRetail/authentication.ts) (Retail authentication), [`src/app/hooks/useHandleSessionHistory.ts`](https://github.com/openai/openai-realtime-agents/blob/main/src/app/hooks/useHandleSessionHistory.ts) (Session history handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Browser experience"]
  node_app["Conversation app<br/>[App.tsx]"]
  node_transcript_ui["Transcript view<br/>[Transcript.tsx]"]
  node_event_ui["Event view<br/>[Events.tsx]"]
  node_toolbar["Session toolbar<br/>[BottomToolbar.tsx]"]
end

subgraph group_session["Realtime session"]
  node_realtime_hook["Realtime session hook"]
  node_responses_api["Responses API route<br/>[route.ts]"]
end

subgraph group_agents["Agent scenarios"]
  node_chat_agent["Chat supervisor scenario<br/>[index.ts]"]
  node_supervisor["Text supervisor<br/>[supervisorAgent.ts]"]
  node_retail_auth["Retail authentication<br/>[authentication.ts]"]
  node_retail_returns["Retail returns<br/>[returns.ts]"]
  node_retail_sales["Retail sales<br/>[sales.ts]"]
  node_simple_handoff["Simple handoff<br/>[simpleHandoff.ts]"]
  node_guardrails["Moderation guardrail<br/>[guardrails.ts]"]
end

subgraph group_support["Session support"]
  node_history["Session history handlers"]
  node_transcript_state["Transcript state"]
  node_event_state["Event state<br/>[EventContext.tsx]"]
  node_audio_download["Audio export"]
  node_audio_utils["Audio conversion<br/>[audioUtils.ts]"]
end

node_user(("User"))
node_agents_sdk["Agents SDK"]

node_user -->|"starts conversation"| node_app
node_app -->|"connects session"| node_realtime_hook
node_app -->|"selects scenario"| node_chat_agent
node_app -->|"selects scenario"| node_retail_auth
node_app -->|"selects scenario"| node_simple_handoff
node_app -->|"creates moderation"| node_guardrails
node_app -->|"renders"| node_transcript_ui
node_app -->|"renders"| node_event_ui
node_app -->|"renders"| node_toolbar
node_realtime_hook -->|"uses session SDK"| node_agents_sdk
node_chat_agent -->|"delegates decisions"| node_supervisor
node_supervisor -->|"requests completion"| node_responses_api
node_retail_auth -.->|"hands off by intent"| node_retail_returns
node_retail_auth -.->|"hands off by intent"| node_retail_sales
node_history -->|"updates transcript"| node_transcript_state
node_history -->|"logs server events"| node_event_state
node_realtime_hook -->|"registers history handlers"| node_history
node_transcript_ui -->|"reads transcript"| node_transcript_state
node_event_ui -->|"reads events"| node_event_state
node_audio_download -->|"converts recording"| node_audio_utils
node_app -->|"offers audio export"| node_audio_download

click node_app "https://github.com/openai/openai-realtime-agents/blob/main/src/app/App.tsx"
click node_transcript_ui "https://github.com/openai/openai-realtime-agents/blob/main/src/app/components/Transcript.tsx"
click node_event_ui "https://github.com/openai/openai-realtime-agents/blob/main/src/app/components/Events.tsx"
click node_toolbar "https://github.com/openai/openai-realtime-agents/blob/main/src/app/components/BottomToolbar.tsx"
click node_realtime_hook "https://github.com/openai/openai-realtime-agents/blob/main/src/app/hooks/useRealtimeSession.ts"
click node_chat_agent "https://github.com/openai/openai-realtime-agents/blob/main/src/app/agentConfigs/chatSupervisor/index.ts"
click node_supervisor "https://github.com/openai/openai-realtime-agents/blob/main/src/app/agentConfigs/chatSupervisor/supervisorAgent.ts"
click node_retail_auth "https://github.com/openai/openai-realtime-agents/blob/main/src/app/agentConfigs/customerServiceRetail/authentication.ts"
click node_retail_returns "https://github.com/openai/openai-realtime-agents/blob/main/src/app/agentConfigs/customerServiceRetail/returns.ts"
click node_retail_sales "https://github.com/openai/openai-realtime-agents/blob/main/src/app/agentConfigs/customerServiceRetail/sales.ts"
click node_simple_handoff "https://github.com/openai/openai-realtime-agents/blob/main/src/app/agentConfigs/simpleHandoff.ts"
click node_guardrails "https://github.com/openai/openai-realtime-agents/blob/main/src/app/agentConfigs/guardrails.ts"
click node_responses_api "https://github.com/openai/openai-realtime-agents/blob/main/src/app/api/responses/route.ts"
click node_history "https://github.com/openai/openai-realtime-agents/blob/main/src/app/hooks/useHandleSessionHistory.ts"
click node_transcript_state "https://github.com/openai/openai-realtime-agents/blob/main/src/app/contexts/TranscriptContext.tsx"
click node_event_state "https://github.com/openai/openai-realtime-agents/blob/main/src/app/contexts/EventContext.tsx"
click node_audio_download "https://github.com/openai/openai-realtime-agents/blob/main/src/app/hooks/useAudioDownload.ts"
click node_audio_utils "https://github.com/openai/openai-realtime-agents/blob/main/src/app/lib/audioUtils.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_transcript_ui,node_event_ui,node_toolbar,node_user toneBlue
class node_realtime_hook,node_responses_api toneAmber
class node_chat_agent,node_supervisor,node_retail_auth,node_retail_returns,node_retail_sales,node_simple_handoff,node_guardrails toneMint
class node_history,node_transcript_state,node_event_state,node_audio_download,node_audio_utils toneRose
class node_agents_sdk toneIndigo
```

## Components

### Browser experience

- [Conversation app](https://github.com/openai/openai-realtime-agents/blob/main/src/app/App.tsx): `src/app/App.tsx`
- [Transcript view](https://github.com/openai/openai-realtime-agents/blob/main/src/app/components/Transcript.tsx): `src/app/components/Transcript.tsx`
- [Event view](https://github.com/openai/openai-realtime-agents/blob/main/src/app/components/Events.tsx): `src/app/components/Events.tsx`
- [Session toolbar](https://github.com/openai/openai-realtime-agents/blob/main/src/app/components/BottomToolbar.tsx): `src/app/components/BottomToolbar.tsx`

### Realtime session

- [Realtime session hook](https://github.com/openai/openai-realtime-agents/blob/main/src/app/hooks/useRealtimeSession.ts): `src/app/hooks/useRealtimeSession.ts`
- [Responses API route](https://github.com/openai/openai-realtime-agents/blob/main/src/app/api/responses/route.ts): `src/app/api/responses/route.ts`

### Agent scenarios

- [Chat supervisor scenario](https://github.com/openai/openai-realtime-agents/blob/main/src/app/agentConfigs/chatSupervisor/index.ts): `src/app/agentConfigs/chatSupervisor/index.ts`
- [Text supervisor](https://github.com/openai/openai-realtime-agents/blob/main/src/app/agentConfigs/chatSupervisor/supervisorAgent.ts): `src/app/agentConfigs/chatSupervisor/supervisorAgent.ts`
- [Retail authentication](https://github.com/openai/openai-realtime-agents/blob/main/src/app/agentConfigs/customerServiceRetail/authentication.ts): `src/app/agentConfigs/customerServiceRetail/authentication.ts`
- [Retail returns](https://github.com/openai/openai-realtime-agents/blob/main/src/app/agentConfigs/customerServiceRetail/returns.ts): `src/app/agentConfigs/customerServiceRetail/returns.ts`
- [Retail sales](https://github.com/openai/openai-realtime-agents/blob/main/src/app/agentConfigs/customerServiceRetail/sales.ts): `src/app/agentConfigs/customerServiceRetail/sales.ts`
- [Simple handoff](https://github.com/openai/openai-realtime-agents/blob/main/src/app/agentConfigs/simpleHandoff.ts): `src/app/agentConfigs/simpleHandoff.ts`
- [Moderation guardrail](https://github.com/openai/openai-realtime-agents/blob/main/src/app/agentConfigs/guardrails.ts): `src/app/agentConfigs/guardrails.ts`

### Session support

- [Session history handlers](https://github.com/openai/openai-realtime-agents/blob/main/src/app/hooks/useHandleSessionHistory.ts): `src/app/hooks/useHandleSessionHistory.ts`
- [Transcript state](https://github.com/openai/openai-realtime-agents/blob/main/src/app/contexts/TranscriptContext.tsx): `src/app/contexts/TranscriptContext.tsx`
- [Event state](https://github.com/openai/openai-realtime-agents/blob/main/src/app/contexts/EventContext.tsx): `src/app/contexts/EventContext.tsx`
- [Audio export](https://github.com/openai/openai-realtime-agents/blob/main/src/app/hooks/useAudioDownload.ts): `src/app/hooks/useAudioDownload.ts`
- [Audio conversion](https://github.com/openai/openai-realtime-agents/blob/main/src/app/lib/audioUtils.ts): `src/app/lib/audioUtils.ts`

### Other components

- **User**
- **Agents SDK**

## Connections

- User → Conversation app: starts conversation (evidence: `README.md`)
- Conversation app → Realtime session hook: connects session (evidence: `src/app/App.tsx`)
- Conversation app → Chat supervisor scenario: selects scenario (evidence: `src/app/App.tsx`)
- Conversation app → Retail authentication: selects scenario (evidence: `src/app/App.tsx`)
- Conversation app → Simple handoff: selects scenario (evidence: `src/app/App.tsx`)
- Conversation app → Moderation guardrail: creates moderation (evidence: `src/app/App.tsx`)
- Conversation app → Transcript view: renders (evidence: `src/app/App.tsx`)
- Conversation app → Event view: renders (evidence: `src/app/App.tsx`)
- Conversation app → Session toolbar: renders (evidence: `src/app/App.tsx`)
- Realtime session hook → Agents SDK: uses session SDK (evidence: `src/app/hooks/useRealtimeSession.ts`)
- Chat supervisor scenario → Text supervisor: delegates decisions (evidence: `src/app/agentConfigs/chatSupervisor/index.ts`)
- Text supervisor → Responses API route: requests completion (evidence: `src/app/agentConfigs/chatSupervisor/supervisorAgent.ts`)
- Retail authentication → Retail returns: hands off by intent (evidence: `README.md`)
- Retail authentication → Retail sales: hands off by intent (evidence: `README.md`)
- Session history handlers → Transcript state: updates transcript (evidence: `src/app/hooks/useHandleSessionHistory.ts`)
- Session history handlers → Event state: logs server events (evidence: `src/app/hooks/useHandleSessionHistory.ts`)
- Realtime session hook → Session history handlers: registers history handlers (evidence: `src/app/hooks/useRealtimeSession.ts`)
- Transcript view → Transcript state: reads transcript (evidence: `src/app/components/Transcript.tsx`)
- Event view → Event state: reads events (evidence: `src/app/components/Events.tsx`)
- Audio export → Audio conversion: converts recording (evidence: `src/app/hooks/useAudioDownload.ts`)
- Conversation app → Audio export: offers audio export (evidence: `src/app/App.tsx`)