Realtime Session Lifecycle

Use this reference for RealtimeSession changes involving entry, exit, listeners, connections, background tasks, approvals, handoffs, event iteration, tracing context, or cleanup.

Resource Ownership

Treat the session as the owner of these resources once they are acquired:

Resource	Acquisition	Required release or terminal state
Model listener	`add_listener()` during entry	`remove_listener()`
Model connection	`model.connect()`	`model.close()`
Event iterators	Waiting on the event queue	Wake or terminate every waiter on close
Guardrail tasks	Created during output processing	Complete, or cancel and account for completion
Tool-call tasks	Created when `async_tool_calls=True`	Complete, or cancel and account for completion
Pending approvals and outputs	Added during tool execution	Resolve, retain for retry, or clear during terminal cleanup
Agent and model settings	Updated on handoff or `update_agent()`	Keep runtime state and model configuration aligned

Do not add a new side effect before a failure point without defining who releases it.

Entry and Exit

Python does not call __aexit__ when __aenter__ raises. Any listener, connection, task, tracing scope, or other resource acquired before the exception needs explicit failure cleanup.
Keep construction free of external side effects. Acquire listeners and connections during entry where failures can be handled coherently.
close() and internal cleanup must be idempotent. Repeated close paths should still wake event iterators without closing the model twice.
Mark the session closed only after the cleanup state is coherent. If model close fails, decide deliberately whether retry is possible and which resources remain owned.

Async Task and Context Rules

asyncio tasks inherit a snapshot of the creator's context. A background task cannot update the caller task's ContextVar state.
A ContextVar token must be reset in the same context that created it. Never pass a token to a different task and assume cleanup can reset it safely.
Shared session fields can be mutated by the listener path, tool-call tasks, close(), update_agent(), and handoff handling. Review ordering and races whenever one of those paths changes.
Calling task.cancel() requests cancellation; it does not prove the task has finished its finally blocks or released resources. Await cancelled tasks when completion matters, or document and test why dropping them is safe.
Background-task exceptions must reach a deterministic owner. They must not silently disappear or leave event consumers blocked.

Agent Transitions

Handoffs and the public update_agent() API are equivalent agent-transition surfaces. Keep their model settings, tool and handoff resolution, emitted events, and tracing metadata aligned unless a difference is intentional and documented.
Resolve dynamic tools and enabled handoffs once per transition when possible, then reuse the exact resolved values for model settings and metadata.
With concurrent tool calls, capture the agent snapshot associated with each call. Do not route a call through whichever agent happens to be current when the task eventually runs.

Guardrails and Response Ordering

Realtime output guardrails inspect accumulated transcript text at configured debounce thresholds, not each token and not a final Runner output object. They emit guardrail_tripped instead of raising a normal Runner tripwire exception.
A tripped output guardrail marks the response interrupted before awaiting transport work, emits one trip event per response, forces response cancellation, and sends safe follow-up input naming the guardrail. Concurrent guardrail tasks must not interrupt or message the same response twice.
Guardrail callbacks can run after audio has already been buffered or played. Consumers must treat audio_interrupted as the signal to stop local playback; text rejection alone cannot retract audio already delivered.
An exception from one output guardrail is logged and skipped so it does not silently terminate the live session. Exceptions that escape the background guardrail task must become a RealtimeError event rather than disappearing.
Realtime function-tool input guardrails follow the same optional pre-approval and mandatory post-approval ordering as standard function tools, but their rejection is returned through Realtime tool output and events.
Follow-up response.create work triggered by tools, handoffs, or guardrails must respect the active response lifecycle. Wait for response.done or the model layer's equivalent gate before starting a conflicting response.

Failure-Path Tests

Add focused tests for affected phases:

Instruction, tool, or handoff resolution fails during entry.
Model connection fails after listener registration.
A background tool or guardrail task raises or is cancelled.
Cleanup runs while event iterators are waiting.
close() is called repeatedly or from another task.
A handoff or update_agent() fails partway through model-settings application.
Tool output sending fails after local execution and must be retried without running the tool twice.
Concurrent guardrail tasks trip once, cancel playback, and do not overlap follow-up responses.

Verify lifecycle changes with the real public path where feasible; helper-only tests are insufficient when task ownership or context propagation determines the result.

Sources

src/agents/realtime/session.py
src/agents/realtime/model.py
src/agents/realtime/openai_realtime.py
tests/realtime/test_session.py
tests/realtime/test_session_exceptions.py
docs/realtime/guide.md

5.6 KiB Raw Permalink Blame History