Realtime sessions

Directory examples/python/features/realtime

Compare streaming WebSocket/WebRTC sessions with HTTP audio turns. These capabilities are tested against local protocol fixtures, not live model services:

Agent node label voice, version 1.0.0.

Capabilities

Capability	Kind	Signature	Module	Summary
`audio_turn`	traversal	`(text: Optional[str] = None, audio_b64: Optional[str] = None, audio_format: str = 'wav', voice: str = 'alloy', model: Optional[str] = None) -> dict`	`examples/python/features/realtime/agent.py`	One OpenRouter audio turn: optional text and/or encoded audio in, text plus spoken audio out.
`listen`	traversal	`(audio_b64: str, transport: str = 'websocket', model: Optional[str] = None) -> dict`	`examples/python/features/realtime/agent.py`	PCM16 (24 kHz mono) audio in; the model's text, transcript and audio out.
`say`	traversal	`(text: str, transport: str = 'websocket', voice: Optional[str] = None, model: Optional[str] = None) -> dict`	`examples/python/features/realtime/agent.py`	One text turn with the OpenAI realtime model over ``websocket`` or ``webrtc``.

Commands

Taken from this example's own README and module docstrings.

python -m atfgraph.worker --module examples.python.features.realtime.agent:app

Files

examples/python/features/realtime/README.md
examples/python/features/realtime/__init__.py
examples/python/features/realtime/agent.py
examples/python/features/realtime/agentnode.yaml

README

Rendered from examples/python/features/realtime/README.md; the source file is not modified.

Compare streaming WebSocket/WebRTC sessions with HTTP audio turns. These capabilities are tested against local protocol fixtures, not live model services:

Traversal	Pair	Transport detail	Fixture test
`say(text, transport="websocket")`	`openai` / `websocket`	pure-Python RFC 6455 client, `session.update` → `response.done`, deltas collected, `usage` recorded	`tests/test_media_parity.py` (local WebSocket server)
`say(text, transport="webrtc")`	`openai` / `webrtc`	SDP offer (`m=audio` + `oai-events` data channel) POSTed as `application/sdp` to `/v1/realtime/calls?model=…`, answer applied, events on the data channel, model audio decoded from the media track into PCM16, PCM16 in via `append_audio` onto the outgoing track; optional `aiortc`, no audio device	`tests/test_realtime_extended.py` (aiortc answering peer over loopback)
`listen(audio_b64, transport)`	same two	PCM16 in, `commit_audio`, text/transcript/audio out	same
`audio_turn(text, audio_b64)`	`openrouter` / `audio_turns`	one `/chat/completions` request per turn: `input_audio` parts in, `modalities: ["text","audio"]` + `audio: {voice, format}` out, `usage: {include: true}` so `usage.cost` is the recorded price; history replayed each turn	`tests/test_realtime_extended.py` (scripted HTTP endpoint)

python -m atfgraph.worker --module examples.python.features.realtime.agent:app

The session's on_usage hook records completed-turn usage in the execution tracker, progress events and server usage store. Cost depends on provider billing data and any configured table support; unknown charges stay None. Check price source and completeness before using totals.

Honest limits

Missing OPENAI_API_KEY or OPENROUTER_API_KEY produces realtime_error; the node does not substitute speech.
Live provider behavior is unverified. Override ATFGRAPH_REALTIME_URL, ATFGRAPH_REALTIME_CALLS_URL or ATFGRAPH_OPENROUTER_CHAT_URL for fixtures or compatible endpoints.
WebRTC audio arrives asynchronously on the media track. The turn collects audio between response creation/completion and resamples it to PCM16 mono at 24 kHz; boundaries are not frame-exact.
HTTP audio turns retain assistant transcript text by default. history_mode="audio_id" instead replays the provider's audio reference.