openai-agents 0.2.0__tar.gz → 0.2.1__tar.gz

{openai_agents-0.2.0 → openai_agents-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-agents
-Version: 0.2.0
+Version: 0.2.1
 Summary: OpenAI Agents SDK
 Project-URL: Homepage, https://openai.github.io/openai-agents-python/
 Project-URL: Repository, https://github.com/openai/openai-agents-python
@@ -20,8 +20,8 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Requires-Dist: griffe<2,>=1.5.6
-Requires-Dist: mcp<2,>=1.9.4; python_version >= '3.10'
-Requires-Dist: openai<2,>=1.93.1
+Requires-Dist: mcp<2,>=1.11.0; python_version >= '3.10'
+Requires-Dist: openai<2,>=1.96.1
 Requires-Dist: pydantic<3,>=2.10
 Requires-Dist: requests<3,>=2.0
 Requires-Dist: types-requests<3,>=2.0

openai_agents-0.2.1/docs/realtime/guide.md

@@ -0,0 +1,143 @@
+# Guide
+
+This guide provides an in-depth look at building voice-enabled AI agents using the OpenAI Agents SDK's realtime capabilities.
+
+!!! warning "Beta feature"
+Realtime agents are in beta. Expect some breaking changes as we improve the implementation.
+
+## Overview
+
+Realtime agents allow for conversational flows, processing audio and text inputs in real time and responding with realtime audio. They maintain persistent connections with OpenAI's Realtime API, enabling natural voice conversations with low latency and the ability to handle interruptions gracefully.
+
+## Architecture
+
+### Core Components
+
+The realtime system consists of several key components:
+
+-   **RealtimeAgent**: An agent, configured wiht instructions, tools and handoffs.
+-   **RealtimeRunner**: Manages configuration. You can call `runner.run()` to get a session.
+-   **RealtimeSession**: A single interaction session. You typically create one each time a user starts a conversation, and keep it alive until the conversation is done.
+-   **RealtimeModel**: The underlying model interface (typically OpenAI's WebSocket implementation)
+
+### Session flow
+
+A typical realtime session follows this flow:
+
+1. **Create your RealtimeAgent(s)** with instructions, tools and handoffs.
+2. **Set up a RealtimeRunner** with the agent and configuration options
+3. **Start the session** using `await runner.run()` which returns a RealtimeSession.
+4. **Send audio or text messages** to the session using `send_audio()` or `send_message()`
+5. **Listen for events** by iterating over the session - events include audio output, transcripts, tool calls, handoffs, and errors
+6. **Handle interruptions** when users speak over the agent, which automatically stops current audio generation
+
+The session maintains the conversation history and manages the persistent connection with the realtime model.
+
+## Agent configuration
+
+RealtimeAgent works similarly to the regular Agent class with some key differences. For full API details, see the [`RealtimeAgent`][agents.realtime.agent.RealtimeAgent] API reference.
+
+Key differences from regular agents:
+
+-   Model choice is configured at the session level, not the agent level.
+-   No structured output support (`outputType` is not supported).
+-   Voice can be configured per agent but cannot be changed after the first agent speaks.
+-   All other features like tools, handoffs, and instructions work the same way.
+
+## Session configuration
+
+### Model settings
+
+The session configuration allows you to control the underlying realtime model behavior. You can configure the model name (such as `gpt-4o-realtime-preview`), voice selection (alloy, echo, fable, onyx, nova, shimmer), and supported modalities (text and/or audio). Audio formats can be set for both input and output, with PCM16 being the default.
+
+### Audio configuration
+
+Audio settings control how the session handles voice input and output. You can configure input audio transcription using models like Whisper, set language preferences, and provide transcription prompts to improve accuracy for domain-specific terms. Turn detection settings control when the agent should start and stop responding, with options for voice activity detection thresholds, silence duration, and padding around detected speech.
+
+## Tools and Functions
+
+### Adding Tools
+
+Just like regular agents, realtime agents support function tools that execute during conversations:
+
+```python
+from agents import function_tool
+
+@function_tool
+def get_weather(city: str) -> str:
+    """Get current weather for a city."""
+    # Your weather API logic here
+    return f"The weather in {city} is sunny, 72°F"
+
+@function_tool
+def book_appointment(date: str, time: str, service: str) -> str:
+    """Book an appointment."""
+    # Your booking logic here
+    return f"Appointment booked for {service} on {date} at {time}"
+
+agent = RealtimeAgent(
+    name="Assistant",
+    instructions="You can help with weather and appointments.",
+    tools=[get_weather, book_appointment],
+)
+```
+
+## Handoffs
+
+### Creating Handoffs
+
+Handoffs allow transferring conversations between specialized agents.
+
+```python
+from agents.realtime import realtime_handoff
+
+# Specialized agents
+billing_agent = RealtimeAgent(
+    name="Billing Support",
+    instructions="You specialize in billing and payment issues.",
+)
+
+technical_agent = RealtimeAgent(
+    name="Technical Support",
+    instructions="You handle technical troubleshooting.",
+)
+
+# Main agent with handoffs
+main_agent = RealtimeAgent(
+    name="Customer Service",
+    instructions="You are the main customer service agent. Hand off to specialists when needed.",
+    handoffs=[
+        realtime_handoff(billing_agent, tool_description="Transfer to billing support"),
+        realtime_handoff(technical_agent, tool_description="Transfer to technical support"),
+    ]
+)
+```
+
+## Event handling
+
+The session streams events that you can listen to by iterating over the session object. Events include audio output chunks, transcription results, tool execution start and end, agent handoffs, and errors. Key events to handle include:
+
+-   **audio**: Raw audio data from the agent's response
+-   **audio_end**: Agent finished speaking
+-   **audio_interrupted**: User interrupted the agent
+-   **tool_start/tool_end**: Tool execution lifecycle
+-   **handoff**: Agent handoff occurred
+-   **error**: Error occurred during processing
+
+For complete event details, see [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent].
+
+## Guardrails
+
+Only output guardrails are supported for realtime agents. These guardrails are debounced and run periodically (not on every word) to avoid performance issues during real-time generation. The default debounce length is 100 characters, but this is configurable.
+
+When a guardrail is triggered, it generates a `guardrail_tripped` event and can interrupt the agent's current response. The debounce behavior helps balance safety with real-time performance requirements. Unlike text agents, realtime agents do **not** raise an Exception when guardrails are tripped.
+
+## Audio processing
+
+Send audio to the session using [`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] or send text using [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message].
+
+For audio output, listen for `audio` events and play the audio data through your preferred audio library. Make sure to listen for `audio_interrupted` events to stop playback immediately and clear any queued audio when the user interrupts the agent.
+
+## Examples
+
+For complete working examples, check out the [examples/realtime directory](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) which includes demos with and without UI components.

openai_agents-0.2.1/docs/realtime/quickstart.md

@@ -0,0 +1,175 @@
+# Quickstart
+
+Realtime agents enable voice conversations with your AI agents using OpenAI's Realtime API. This guide walks you through creating your first realtime voice agent.
+
+!!! warning "Beta feature"
+Realtime agents are in beta. Expect some breaking changes as we improve the implementation.
+
+## Prerequisites
+
+-   Python 3.9 or higher
+-   OpenAI API key
+-   Basic familiarity with the OpenAI Agents SDK
+
+## Installation
+
+If you haven't already, install the OpenAI Agents SDK:
+
+```bash
+pip install openai-agents
+```
+
+## Creating your first realtime agent
+
+### 1. Import required components
+
+```python
+import asyncio
+from agents.realtime import RealtimeAgent, RealtimeRunner
+```
+
+### 2. Create a realtime agent
+
+```python
+agent = RealtimeAgent(
+    name="Assistant",
+    instructions="You are a helpful voice assistant. Keep your responses conversational and friendly.",
+)
+```
+
+### 3. Set up the runner
+
+```python
+runner = RealtimeRunner(
+    starting_agent=agent,
+    config={
+        "model_settings": {
+            "model_name": "gpt-4o-realtime-preview",
+            "voice": "alloy",
+            "modalities": ["text", "audio"],
+        }
+    }
+)
+```
+
+### 4. Start a session
+
+```python
+async def main():
+    # Start the realtime session
+    session = await runner.run()
+
+    async with session:
+        # Send a text message to start the conversation
+        await session.send_message("Hello! How are you today?")
+
+        # The agent will stream back audio in real-time (not shown in this example)
+        # Listen for events from the session
+        async for event in session:
+            if event.type == "response.audio_transcript.done":
+                print(f"Assistant: {event.transcript}")
+            elif event.type == "conversation.item.input_audio_transcription.completed":
+                print(f"User: {event.transcript}")
+
+# Run the session
+asyncio.run(main())
+```
+
+## Complete example
+
+Here's a complete working example:
+
+```python
+import asyncio
+from agents.realtime import RealtimeAgent, RealtimeRunner
+
+async def main():
+    # Create the agent
+    agent = RealtimeAgent(
+        name="Assistant",
+        instructions="You are a helpful voice assistant. Keep responses brief and conversational.",
+    )
+
+    # Set up the runner with configuration
+    runner = RealtimeRunner(
+        starting_agent=agent,
+        config={
+            "model_settings": {
+                "model_name": "gpt-4o-realtime-preview",
+                "voice": "alloy",
+                "modalities": ["text", "audio"],
+                "input_audio_transcription": {
+                    "model": "whisper-1"
+                },
+                "turn_detection": {
+                    "type": "server_vad",
+                    "threshold": 0.5,
+                    "prefix_padding_ms": 300,
+                    "silence_duration_ms": 200
+                }
+            }
+        }
+    )
+
+    # Start the session
+    session = await runner.run()
+
+    async with session:
+        print("Session started! The agent will stream audio responses in real-time.")
+
+        # Process events
+        async for event in session:
+            if event.type == "response.audio_transcript.done":
+                print(f"Assistant: {event.transcript}")
+            elif event.type == "conversation.item.input_audio_transcription.completed":
+                print(f"User: {event.transcript}")
+            elif event.type == "error":
+                print(f"Error: {event.error}")
+                break
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Configuration options
+
+### Model settings
+
+-   `model_name`: Choose from available realtime models (e.g., `gpt-4o-realtime-preview`)
+-   `voice`: Select voice (`alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`)
+-   `modalities`: Enable text and/or audio (`["text", "audio"]`)
+
+### Audio settings
+
+-   `input_audio_format`: Format for input audio (`pcm16`, `g711_ulaw`, `g711_alaw`)
+-   `output_audio_format`: Format for output audio
+-   `input_audio_transcription`: Transcription configuration
+
+### Turn detection
+
+-   `type`: Detection method (`server_vad`, `semantic_vad`)
+-   `threshold`: Voice activity threshold (0.0-1.0)
+-   `silence_duration_ms`: Silence duration to detect turn end
+-   `prefix_padding_ms`: Audio padding before speech
+
+## Next steps
+
+-   [Learn more about realtime agents](guide.md)
+-   Check out working examples in the [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) folder
+-   Add tools to your agent
+-   Implement handoffs between agents
+-   Set up guardrails for safety
+
+## Authentication
+
+Make sure your OpenAI API key is set in your environment:
+
+```bash
+export OPENAI_API_KEY="your-api-key-here"
+```
+
+Or pass it directly when creating the session:
+
+```python
+session = await runner.run(model_config={"api_key": "your-api-key"})
+```

openai_agents-0.2.1/docs/ref/realtime/agent.md

@@ -0,0 +1,3 @@
+# `RealtimeAgent`
+
+::: agents.realtime.agent.RealtimeAgent

openai_agents-0.2.1/docs/ref/realtime/config.md

@@ -0,0 +1,41 @@
+# Realtime Configuration
+
+## Run Configuration
+
+::: agents.realtime.config.RealtimeRunConfig
+
+## Model Settings
+
+::: agents.realtime.config.RealtimeSessionModelSettings
+
+## Audio Configuration
+
+::: agents.realtime.config.RealtimeInputAudioTranscriptionConfig
+::: agents.realtime.config.RealtimeTurnDetectionConfig
+
+## Guardrails Settings
+
+::: agents.realtime.config.RealtimeGuardrailsSettings
+
+## Model Configuration
+
+::: agents.realtime.model.RealtimeModelConfig
+
+## Tracing Configuration
+
+::: agents.realtime.config.RealtimeModelTracingConfig
+
+## User Input Types
+
+::: agents.realtime.config.RealtimeUserInput
+::: agents.realtime.config.RealtimeUserInputText
+::: agents.realtime.config.RealtimeUserInputMessage
+
+## Client Messages
+
+::: agents.realtime.config.RealtimeClientMessage
+
+## Type Aliases
+
+::: agents.realtime.config.RealtimeModelName
+::: agents.realtime.config.RealtimeAudioFormat

openai_agents-0.2.1/docs/ref/realtime/events.md

@@ -0,0 +1,36 @@
+# Realtime Events
+
+## Session Events
+
+::: agents.realtime.events.RealtimeSessionEvent
+
+## Event Types
+
+### Agent Events
+::: agents.realtime.events.RealtimeAgentStartEvent
+::: agents.realtime.events.RealtimeAgentEndEvent
+
+### Audio Events
+::: agents.realtime.events.RealtimeAudio
+::: agents.realtime.events.RealtimeAudioEnd
+::: agents.realtime.events.RealtimeAudioInterrupted
+
+### Tool Events
+::: agents.realtime.events.RealtimeToolStart
+::: agents.realtime.events.RealtimeToolEnd
+
+### Handoff Events
+::: agents.realtime.events.RealtimeHandoffEvent
+
+### Guardrail Events
+::: agents.realtime.events.RealtimeGuardrailTripped
+
+### History Events
+::: agents.realtime.events.RealtimeHistoryAdded
+::: agents.realtime.events.RealtimeHistoryUpdated
+
+### Error Events
+::: agents.realtime.events.RealtimeError
+
+### Raw Model Events
+::: agents.realtime.events.RealtimeRawModelEvent

openai_agents-0.2.1/docs/ref/realtime/runner.md

@@ -0,0 +1,3 @@
+# `RealtimeRunner`
+
+::: agents.realtime.runner.RealtimeRunner

openai_agents-0.2.1/docs/ref/realtime/session.md

@@ -0,0 +1,3 @@
+# `RealtimeSession`
+
+::: agents.realtime.session.RealtimeSession

openai_agents-0.2.1/examples/realtime/app/README.md

@@ -0,0 +1,40 @@
+# Realtime Demo App
+
+A web-based realtime voice assistant demo with a FastAPI backend and HTML/JS frontend.
+
+## Installation
+
+Install the required dependencies:
+
+```bash
+uv add fastapi uvicorn websockets
+```
+
+## Usage
+
+Start the application with a single command:
+
+```bash
+cd examples/realtime/app && uv run python server.py
+```
+
+Then open your browser to: http://localhost:8000
+
+## How to Use
+
+1. Click **Connect** to establish a realtime session
+2. Audio capture starts automatically - just speak naturally
+3. Click the **Mic On/Off** button to mute/unmute your microphone
+4. Watch the conversation unfold in the left pane
+5. Monitor raw events in the right pane (click to expand/collapse)
+6. Click **Disconnect** when done
+
+## Architecture
+
+-   **Backend**: FastAPI server with WebSocket connections for real-time communication
+-   **Session Management**: Each connection gets a unique session with the OpenAI Realtime API
+-   **Audio Processing**: 24kHz mono audio capture and playback
+-   **Event Handling**: Full event stream processing with transcript generation
+-   **Frontend**: Vanilla JavaScript with clean, responsive CSS
+
+The demo showcases the core patterns for building realtime voice applications with the OpenAI Agents SDK.

openai_agents-0.2.1/examples/realtime/app/server.py

@@ -0,0 +1,172 @@
+import asyncio
+import base64
+import json
+import logging
+import struct
+from contextlib import asynccontextmanager
+from typing import Any, assert_never
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from agents import function_tool
+from agents.realtime import RealtimeAgent, RealtimeRunner, RealtimeSession, RealtimeSessionEvent
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+@function_tool
+def get_weather(city: str) -> str:
+    """Get the weather in a city."""
+    return f"The weather in {city} is sunny."
+
+
+@function_tool
+def get_secret_number() -> int:
+    """Returns the secret number, if the user asks for it."""
+    return 71
+
+
+haiku_agent = RealtimeAgent(
+    name="Haiku Agent",
+    instructions="You are a haiku poet. You must respond ONLY in traditional haiku format (5-7-5 syllables). Every response should be a proper haiku about the topic. Do not break character.",
+    tools=[],
+)
+
+agent = RealtimeAgent(
+    name="Assistant",
+    instructions="If the user wants poetry or haikus, you can hand them off to the haiku agent via the transfer_to_haiku_agent tool.",
+    tools=[get_weather, get_secret_number],
+    handoffs=[haiku_agent],
+)
+
+
+class RealtimeWebSocketManager:
+    def __init__(self):
+        self.active_sessions: dict[str, RealtimeSession] = {}
+        self.session_contexts: dict[str, Any] = {}
+        self.websockets: dict[str, WebSocket] = {}
+
+    async def connect(self, websocket: WebSocket, session_id: str):
+        await websocket.accept()
+        self.websockets[session_id] = websocket
+
+        runner = RealtimeRunner(agent)
+        session_context = await runner.run()
+        session = await session_context.__aenter__()
+        self.active_sessions[session_id] = session
+        self.session_contexts[session_id] = session_context
+
+        # Start event processing task
+        asyncio.create_task(self._process_events(session_id))
+
+    async def disconnect(self, session_id: str):
+        if session_id in self.session_contexts:
+            await self.session_contexts[session_id].__aexit__(None, None, None)
+            del self.session_contexts[session_id]
+        if session_id in self.active_sessions:
+            del self.active_sessions[session_id]
+        if session_id in self.websockets:
+            del self.websockets[session_id]
+
+    async def send_audio(self, session_id: str, audio_bytes: bytes):
+        if session_id in self.active_sessions:
+            await self.active_sessions[session_id].send_audio(audio_bytes)
+
+    async def _process_events(self, session_id: str):
+        try:
+            session = self.active_sessions[session_id]
+            websocket = self.websockets[session_id]
+
+            async for event in session:
+                event_data = await self._serialize_event(event)
+                await websocket.send_text(json.dumps(event_data))
+        except Exception as e:
+            logger.error(f"Error processing events for session {session_id}: {e}")
+
+    async def _serialize_event(self, event: RealtimeSessionEvent) -> dict[str, Any]:
+        base_event: dict[str, Any] = {
+            "type": event.type,
+        }
+
+        if event.type == "agent_start":
+            base_event["agent"] = event.agent.name
+        elif event.type == "agent_end":
+            base_event["agent"] = event.agent.name
+        elif event.type == "handoff":
+            base_event["from"] = event.from_agent.name
+            base_event["to"] = event.to_agent.name
+        elif event.type == "tool_start":
+            base_event["tool"] = event.tool.name
+        elif event.type == "tool_end":
+            base_event["tool"] = event.tool.name
+            base_event["output"] = str(event.output)
+        elif event.type == "audio":
+            base_event["audio"] = base64.b64encode(event.audio.data).decode("utf-8")
+        elif event.type == "audio_interrupted":
+            pass
+        elif event.type == "audio_end":
+            pass
+        elif event.type == "history_updated":
+            base_event["history"] = [item.model_dump(mode="json") for item in event.history]
+        elif event.type == "history_added":
+            pass
+        elif event.type == "guardrail_tripped":
+            base_event["guardrail_results"] = [
+                {"name": result.guardrail.name} for result in event.guardrail_results
+            ]
+        elif event.type == "raw_model_event":
+            base_event["raw_model_event"] = {
+                "type": event.data.type,
+            }
+        elif event.type == "error":
+            base_event["error"] = str(event.error) if hasattr(event, "error") else "Unknown error"
+        else:
+            assert_never(event)
+
+        return base_event
+
+
+manager = RealtimeWebSocketManager()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    yield
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.websocket("/ws/{session_id}")
+async def websocket_endpoint(websocket: WebSocket, session_id: str):
+    await manager.connect(websocket, session_id)
+    try:
+        while True:
+            data = await websocket.receive_text()
+            message = json.loads(data)
+
+            if message["type"] == "audio":
+                # Convert int16 array to bytes
+                int16_data = message["data"]
+                audio_bytes = struct.pack(f"{len(int16_data)}h", *int16_data)
+                await manager.send_audio(session_id, audio_bytes)
+
+    except WebSocketDisconnect:
+        await manager.disconnect(session_id)
+
+
+app.mount("/", StaticFiles(directory="static", html=True), name="static")
+
+
+@app.get("/")
+async def read_index():
+    return FileResponse("static/index.html")
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)