Add realtime weather voice agent example

examples/realtime/weather_voice_agent/README.md

@@ -0,0 +1,50 @@
+# Realtime Weather Voice Agent
+
+This example shows how to build a realtime voice assistant with the OpenAI Agents SDK. The agent speaks with the `gpt-4o-realtime-preview` model, calls a mock `lookup_weather` tool, and streams responses into a Streamlit dashboard so you can watch events as they arrive.
+
+## Prerequisites
+
+- Python 3.9+
+- An `OPENAI_API_KEY` environment variable with access to the realtime API
+- A microphone and speakers so you can record and listen to audio replies
+
+## Setup
+
+Install the project dependencies from the repository root. All commands use `uv`, matching the rest of the realtime documentation (`docs/realtime`).
+
+```bash
+uv sync
+uv pip install streamlit sounddevice numpy
+```
+
+If you are running the example outside of this repository, install the SDK with voice support alongside Streamlit:
+
+```bash
+uv pip install "openai-agents[voice]" streamlit sounddevice numpy
+```
+
+## Run the demo
+
+Start the Streamlit UI without any command line arguments:
+
+```bash
+cd examples/realtime/weather_voice_agent
+export OPENAI_API_KEY=...  # replace with your key
+uv run streamlit run app.py
+```
+
+## How to use the UI
+
+1. Click **Connect** to open a realtime session using `RealtimeRunner`.
+2. When the status turns to `connected`, press **Record and send** to capture a short microphone clip (between two and six seconds) and send it to the agent.
+3. Ask for the weather in cities such as New York, San Francisco, Seattle, or Austin. The agent will call the mock `lookup_weather` tool before responding.
+4. Watch the **Conversation** pane for user transcripts, tool results, and assistant replies. The **Event log** shows each event that Streamlit receives from the session.
+5. Listen to the assistant's audio responses in the **Assistant audio replies** section, or use the optional text form if you do not want to record audio.
+6. Click **Disconnect** to end the session once you are finished.
+
+## Project files
+
+- `agent.py` creates the realtime agent and defines the mock weather tool and run configuration.
+- `app.py` contains the Streamlit UI that records audio, streams events, and renders the session state.
+
+The example mirrors the configuration described in `docs/realtime/quickstart.md` while remaining self-contained by using a local tool rather than a live weather API.

examples/realtime/weather_voice_agent/agent.py

@@ -0,0 +1,85 @@
+"""Realtime weather voice agent configuration."""
+
+from __future__ import annotations
+
+from typing import Any, Final
+
+from agents import function_tool
+from agents.realtime import RealtimeAgent, RealtimeRunConfig
+
+FORECASTS: Final[dict[str, dict[str, Any]]] = {
+    "new york": {
+        "name": "New York City",
+        "condition": "sunny with a light coastal breeze",
+        "high_f": 78,
+        "low_f": 65,
+        "tip": "A light jacket is handy for evening walks along the Hudson River.",
+    },
+    "san francisco": {
+        "name": "San Francisco",
+        "condition": "morning fog that burns off into a clear afternoon",
+        "high_f": 68,
+        "low_f": 56,
+        "tip": "Carry layers because neighborhoods like the Mission stay warmer than the Presidio.",
+    },
+    "seattle": {
+        "name": "Seattle",
+        "condition": "scattered clouds and a gentle drizzle",
+        "high_f": 64,
+        "low_f": 52,
+        "tip": "Waterproof shoes make downtown strolls more comfortable when sidewalks are damp.",
+    },
+    "austin": {
+        "name": "Austin",
+        "condition": "sunny skies with a late afternoon breeze",
+        "high_f": 92,
+        "low_f": 74,
+        "tip": "Stay hydrated and find shade during outdoor concerts.",
+    },
+}
+
+
+def _format_forecast(city: str, details: dict[str, Any]) -> str:
+    """Create a friendly weather summary from forecast details."""
+    return (
+        f"In {details['name']}, expect {details['condition']}. "
+        f"Temperatures range from about {details['low_f']}°F overnight to {details['high_f']}°F during the day. "
+        f"Tip: {details['tip']}"
+    )
+
+
+@function_tool
+def lookup_weather(city: str) -> str:
+    """Return a mock weather report for the requested city."""
+    normalized_city = city.strip().lower()
+    forecast = FORECASTS.get(normalized_city)
+    if forecast is None:
+        return (
+            "I do not have live data for that city, but typical weather is mild with occasional clouds. "
+            "Try asking about New York, San Francisco, Seattle, or Austin for a more specific report."
+        )
+
+    return _format_forecast(city=normalized_city, details=forecast)
+
+
+REALTIME_RUN_CONFIG: Final[RealtimeRunConfig] = {
+    "model_settings": {
+        "model_name": "gpt-4o-realtime-preview",
+        "voice": "alloy",
+        "modalities": ["text", "audio"],
+        "input_audio_transcription": {"model": "whisper-1"},
+    }
+}
+
+
+def create_weather_agent() -> RealtimeAgent[None]:
+    """Create the realtime agent used by the Streamlit demo."""
+    return RealtimeAgent(
+        name="Weather Buddy",
+        instructions=(
+            "You are a cheerful weather assistant that speaks naturally in short sentences. "
+            "When someone asks about the forecast you must call the `lookup_weather` tool before responding. "
+            "Answer with a friendly summary that is easy to hear aloud."
+        ),
+        tools=[lookup_weather],
+    )