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

openai_agents-0.2.1/.vscode/launch.json

@@ -0,0 +1,14 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python Debugger: Python File",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}"
+        }
+    ]
+}

{openai_agents-0.1.0 → openai_agents-0.2.1}/Makefile

@@ -7,6 +7,10 @@ format:
 	uv run ruff format
 	uv run ruff check --fix
 
+.PHONY: format-check
+format-check:
+	uv run ruff format --check
+
 .PHONY: lint
 lint: 
 	uv run ruff check
@@ -55,5 +59,5 @@ serve-docs:
 deploy-docs:
 	uv run mkdocs gh-deploy --force --verbose
 
-	
-	
+.PHONY: check
+check: format-check lint mypy tests

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-agents
-Version: 0.1.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,14 +20,16 @@ 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>=1.87.0
+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
 Requires-Dist: typing-extensions<5,>=4.12.2
 Provides-Extra: litellm
 Requires-Dist: litellm<2,>=1.67.4.post1; extra == 'litellm'
+Provides-Extra: realtime
+Requires-Dist: websockets<16,>=15.0; extra == 'realtime'
 Provides-Extra: viz
 Requires-Dist: graphviz>=0.17; extra == 'viz'
 Provides-Extra: voice
@@ -49,10 +51,119 @@ The OpenAI Agents SDK is a lightweight yet powerful framework for building multi
 1. [**Agents**](https://openai.github.io/openai-agents-python/agents): LLMs configured with instructions, tools, guardrails, and handoffs
 2. [**Handoffs**](https://openai.github.io/openai-agents-python/handoffs/): A specialized tool call used by the Agents SDK for transferring control between agents
 3. [**Guardrails**](https://openai.github.io/openai-agents-python/guardrails/): Configurable safety checks for input and output validation
-4. [**Tracing**](https://openai.github.io/openai-agents-python/tracing/): Built-in tracking of agent runs, allowing you to view, debug and optimize your workflows
+4. [**Sessions**](#sessions): Automatic conversation history management across agent runs
+5. [**Tracing**](https://openai.github.io/openai-agents-python/tracing/): Built-in tracking of agent runs, allowing you to view, debug and optimize your workflows
 
 Explore the [examples](examples) directory to see the SDK in action, and read our [documentation](https://openai.github.io/openai-agents-python/) for more details.
 
+## Sessions
+
+The Agents SDK provides built-in session memory to automatically maintain conversation history across multiple agent runs, eliminating the need to manually handle `.to_input_list()` between turns.
+
+### Quick start
+
+```python
+from agents import Agent, Runner, SQLiteSession
+
+# Create agent
+agent = Agent(
+    name="Assistant",
+    instructions="Reply very concisely.",
+)
+
+# Create a session instance
+session = SQLiteSession("conversation_123")
+
+# First turn
+result = await Runner.run(
+    agent,
+    "What city is the Golden Gate Bridge in?",
+    session=session
+)
+print(result.final_output)  # "San Francisco"
+
+# Second turn - agent automatically remembers previous context
+result = await Runner.run(
+    agent,
+    "What state is it in?",
+    session=session
+)
+print(result.final_output)  # "California"
+
+# Also works with synchronous runner
+result = Runner.run_sync(
+    agent,
+    "What's the population?",
+    session=session
+)
+print(result.final_output)  # "Approximately 39 million"
+```
+
+### Session options
+
+-   **No memory** (default): No session memory when session parameter is omitted
+-   **`session: Session = DatabaseSession(...)`**: Use a Session instance to manage conversation history
+
+```python
+from agents import Agent, Runner, SQLiteSession
+
+# Custom SQLite database file
+session = SQLiteSession("user_123", "conversations.db")
+agent = Agent(name="Assistant")
+
+# Different session IDs maintain separate conversation histories
+result1 = await Runner.run(
+    agent,
+    "Hello",
+    session=session
+)
+result2 = await Runner.run(
+    agent,
+    "Hello",
+    session=SQLiteSession("user_456", "conversations.db")
+)
+```
+
+### Custom session implementations
+
+You can implement your own session memory by creating a class that follows the `Session` protocol:
+
+```python
+from agents.memory import Session
+from typing import List
+
+class MyCustomSession:
+    """Custom session implementation following the Session protocol."""
+
+    def __init__(self, session_id: str):
+        self.session_id = session_id
+        # Your initialization here
+
+    async def get_items(self, limit: int | None = None) -> List[dict]:
+        # Retrieve conversation history for the session
+        pass
+
+    async def add_items(self, items: List[dict]) -> None:
+        # Store new items for the session
+        pass
+
+    async def pop_item(self) -> dict | None:
+        # Remove and return the most recent item from the session
+        pass
+
+    async def clear_session(self) -> None:
+        # Clear all items for the session
+        pass
+
+# Use your custom session
+agent = Agent(name="Assistant")
+result = await Runner.run(
+    agent,
+    "Hello",
+    session=MyCustomSession("my_session")
+)
+```
+
 ## Get started
 
 1. Set up your Python environment
@@ -207,10 +318,16 @@ make sync
 
 2. (After making changes) lint/test
 
+```
+make check # run tests linter and typechecker
+```
+
+Or to run them individually:
 ```
 make tests  # run tests
 make mypy   # run typechecker
 make lint   # run linter
+make format-check # run style checker
 ```
 
 ## Acknowledgements

{openai_agents-0.1.0 → openai_agents-0.2.1}/README.md

@@ -12,10 +12,119 @@ The OpenAI Agents SDK is a lightweight yet powerful framework for building multi
 1. [**Agents**](https://openai.github.io/openai-agents-python/agents): LLMs configured with instructions, tools, guardrails, and handoffs
 2. [**Handoffs**](https://openai.github.io/openai-agents-python/handoffs/): A specialized tool call used by the Agents SDK for transferring control between agents
 3. [**Guardrails**](https://openai.github.io/openai-agents-python/guardrails/): Configurable safety checks for input and output validation
-4. [**Tracing**](https://openai.github.io/openai-agents-python/tracing/): Built-in tracking of agent runs, allowing you to view, debug and optimize your workflows
+4. [**Sessions**](#sessions): Automatic conversation history management across agent runs
+5. [**Tracing**](https://openai.github.io/openai-agents-python/tracing/): Built-in tracking of agent runs, allowing you to view, debug and optimize your workflows
 
 Explore the [examples](examples) directory to see the SDK in action, and read our [documentation](https://openai.github.io/openai-agents-python/) for more details.
 
+## Sessions
+
+The Agents SDK provides built-in session memory to automatically maintain conversation history across multiple agent runs, eliminating the need to manually handle `.to_input_list()` between turns.
+
+### Quick start
+
+```python
+from agents import Agent, Runner, SQLiteSession
+
+# Create agent
+agent = Agent(
+    name="Assistant",
+    instructions="Reply very concisely.",
+)
+
+# Create a session instance
+session = SQLiteSession("conversation_123")
+
+# First turn
+result = await Runner.run(
+    agent,
+    "What city is the Golden Gate Bridge in?",
+    session=session
+)
+print(result.final_output)  # "San Francisco"
+
+# Second turn - agent automatically remembers previous context
+result = await Runner.run(
+    agent,
+    "What state is it in?",
+    session=session
+)
+print(result.final_output)  # "California"
+
+# Also works with synchronous runner
+result = Runner.run_sync(
+    agent,
+    "What's the population?",
+    session=session
+)
+print(result.final_output)  # "Approximately 39 million"
+```
+
+### Session options
+
+-   **No memory** (default): No session memory when session parameter is omitted
+-   **`session: Session = DatabaseSession(...)`**: Use a Session instance to manage conversation history
+
+```python
+from agents import Agent, Runner, SQLiteSession
+
+# Custom SQLite database file
+session = SQLiteSession("user_123", "conversations.db")
+agent = Agent(name="Assistant")
+
+# Different session IDs maintain separate conversation histories
+result1 = await Runner.run(
+    agent,
+    "Hello",
+    session=session
+)
+result2 = await Runner.run(
+    agent,
+    "Hello",
+    session=SQLiteSession("user_456", "conversations.db")
+)
+```
+
+### Custom session implementations
+
+You can implement your own session memory by creating a class that follows the `Session` protocol:
+
+```python
+from agents.memory import Session
+from typing import List
+
+class MyCustomSession:
+    """Custom session implementation following the Session protocol."""
+
+    def __init__(self, session_id: str):
+        self.session_id = session_id
+        # Your initialization here
+
+    async def get_items(self, limit: int | None = None) -> List[dict]:
+        # Retrieve conversation history for the session
+        pass
+
+    async def add_items(self, items: List[dict]) -> None:
+        # Store new items for the session
+        pass
+
+    async def pop_item(self) -> dict | None:
+        # Remove and return the most recent item from the session
+        pass
+
+    async def clear_session(self) -> None:
+        # Clear all items for the session
+        pass
+
+# Use your custom session
+agent = Agent(name="Assistant")
+result = await Runner.run(
+    agent,
+    "Hello",
+    session=MyCustomSession("my_session")
+)
+```
+
 ## Get started
 
 1. Set up your Python environment
@@ -170,10 +279,16 @@ make sync
 
 2. (After making changes) lint/test
 
+```
+make check # run tests linter and typechecker
+```
+
+Or to run them individually:
 ```
 make tests  # run tests
 make mypy   # run typechecker
 make lint   # run linter
+make format-check # run style checker
 ```
 
 ## Acknowledgements

{openai_agents-0.1.0 → openai_agents-0.2.1}/docs/agents.md

@@ -6,6 +6,7 @@ Agents are the core building block in your apps. An agent is a large language mo
 
 The most common properties of an agent you'll configure are:
 
+-   `name`: A required string that identifies your agent.
 -   `instructions`: also known as a developer message or system prompt.
 -   `model`: which LLM to use, and optional `model_settings` to configure model tuning parameters like temperature, top_p, etc.
 -   `tools`: Tools that the agent can use to achieve its tasks.

{openai_agents-0.1.0 → openai_agents-0.2.1}/docs/examples.md

@@ -40,3 +40,6 @@ Check out a variety of sample implementations of the SDK in the examples section
 
 - **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):**
   See examples of voice agents, using our TTS and STT models.
+
+- **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):**
+  Examples showing how to build realtime experiences using the SDK.

{openai_agents-0.1.0 → openai_agents-0.2.1}/docs/index.md

@@ -5,6 +5,7 @@ The [OpenAI Agents SDK](https://github.com/openai/openai-agents-python) enables
 -   **Agents**, which are LLMs equipped with instructions and tools
 -   **Handoffs**, which allow agents to delegate to other agents for specific tasks
 -   **Guardrails**, which enable the inputs to agents to be validated
+-   **Sessions**, which automatically maintains conversation history across agent runs
 
 In combination with Python, these primitives are powerful enough to express complex relationships between tools and agents, and allow you to build real-world applications without a steep learning curve. In addition, the SDK comes with built-in **tracing** that lets you visualize and debug your agentic flows, as well as evaluate them and even fine-tune models for your application.
 
@@ -21,6 +22,7 @@ Here are the main features of the SDK:
 -   Python-first: Use built-in language features to orchestrate and chain agents, rather than needing to learn new abstractions.
 -   Handoffs: A powerful feature to coordinate and delegate between multiple agents.
 -   Guardrails: Run input validations and checks in parallel to your agents, breaking early if the checks fail.
+-   Sessions: Automatic conversation history management across agent runs, eliminating manual state handling.
 -   Function tools: Turn any Python function into a tool, with automatic schema generation and Pydantic-powered validation.
 -   Tracing: Built-in tracing that lets you visualize, debug and monitor your workflows, as well as use the OpenAI suite of evaluation, fine-tuning and distillation tools.
 

{openai_agents-0.1.0 → openai_agents-0.2.1}/docs/mcp.md

@@ -4,7 +4,7 @@ The [Model context protocol](https://modelcontextprotocol.io/introduction) (aka
 
 > MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools.
 
-The Agents SDK has support for MCP. This enables you to use a wide range of MCP servers to provide tools to your Agents.
+The Agents SDK has support for MCP. This enables you to use a wide range of MCP servers to provide tools and prompts to your Agents.
 
 ## MCP servers
 
@@ -135,6 +135,38 @@ The `ToolFilterContext` provides access to:
 - `agent`: The agent requesting the tools 
 - `server_name`: The name of the MCP server
 
+## Prompts
+
+MCP servers can also provide prompts that can be used to dynamically generate agent instructions. This allows you to create reusable instruction templates that can be customized with parameters.
+
+### Using prompts
+
+MCP servers that support prompts provide two key methods:
+
+- `list_prompts()`: Lists all available prompts on the server
+- `get_prompt(name, arguments)`: Gets a specific prompt with optional parameters
+
+```python
+# List available prompts
+prompts_result = await server.list_prompts()
+for prompt in prompts_result.prompts:
+    print(f"Prompt: {prompt.name} - {prompt.description}")
+
+# Get a specific prompt with parameters
+prompt_result = await server.get_prompt(
+    "generate_code_review_instructions",
+    {"focus": "security vulnerabilities", "language": "python"}
+)
+instructions = prompt_result.messages[0].content.text
+
+# Use the prompt-generated instructions with an Agent
+agent = Agent(
+    name="Code Reviewer",
+    instructions=instructions,  # Instructions from MCP prompt
+    mcp_servers=[server]
+)
+```
+
 ## Caching
 
 Every time an Agent runs, it calls `list_tools()` on the MCP server. This can be a latency hit, especially if the server is a remote server. To automatically cache the list of tools, you can pass `cache_tools_list=True` to [`MCPServerStdio`][agents.mcp.server.MCPServerStdio], [`MCPServerSse`][agents.mcp.server.MCPServerSse], and [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]. You should only do this if you're certain the tool list will not change.

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.