Merge branch 'main' into python-3.14

Author: seratch

.github/workflows/tests.yml

@@ -22,6 +22,8 @@ jobs:
           enable-cache: true
       - name: Install dependencies
         run: make sync
+      - name: Verify formatting
+        run: make format-check
       - name: Run lint
         run: make lint
 

README.md

@@ -1,4 +1,4 @@
-# OpenAI Agents SDK
+# OpenAI Agents SDK [![PyPI](https://img.shields.io/pypi/v/openai-agents?label=pypi%20package)](https://pypi.org/project/openai-agents/)
 
 The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows. It is provider-agnostic, supporting the OpenAI Responses and Chat Completions APIs, as well as 100+ other LLMs.
 

examples/basic/lifecycle_example.py

@@ -1,6 +1,6 @@
 import asyncio
 import random
-from typing import Any, Optional
+from typing import Any, Optional, cast
 
 from pydantic import BaseModel
 
@@ -15,6 +15,7 @@
     function_tool,
 )
 from agents.items import ModelResponse, TResponseInputItem
+from agents.tool_context import ToolContext
 
 
 class LoggingHooks(AgentHooks[Any]):
@@ -71,16 +72,22 @@ async def on_agent_end(self, context: RunContextWrapper, agent: Agent, output: A
 
     async def on_tool_start(self, context: RunContextWrapper, agent: Agent, tool: Tool) -> None:
         self.event_counter += 1
+        # While this type cast is not ideal,
+        # we don't plan to change the context arg type in the near future for backwards compatibility.
+        tool_context = cast(ToolContext[Any], context)
         print(
-            f"### {self.event_counter}: Tool {tool.name} started. name={context.tool_name}, call_id={context.tool_call_id}, args={context.tool_arguments}. Usage: {self._usage_to_str(context.usage)}"  # type: ignore[attr-defined]
+            f"### {self.event_counter}: Tool {tool.name} started. name={tool_context.tool_name}, call_id={tool_context.tool_call_id}, args={tool_context.tool_arguments}. Usage: {self._usage_to_str(tool_context.usage)}"
         )
 
     async def on_tool_end(
         self, context: RunContextWrapper, agent: Agent, tool: Tool, result: str
     ) -> None:
         self.event_counter += 1
+        # While this type cast is not ideal,
+        # we don't plan to change the context arg type in the near future for backwards compatibility.
+        tool_context = cast(ToolContext[Any], context)
         print(
-            f"### {self.event_counter}: Tool {tool.name} finished. result={result}, name={context.tool_name}, call_id={context.tool_call_id}, args={context.tool_arguments}. Usage: {self._usage_to_str(context.usage)}"  # type: ignore[attr-defined]
+            f"### {self.event_counter}: Tool {tool.name} finished. result={result}, name={tool_context.tool_name}, call_id={tool_context.tool_call_id}, args={tool_context.tool_arguments}. Usage: {self._usage_to_str(tool_context.usage)}"
         )
 
     async def on_handoff(

examples/realtime/app/agent.py

@@ -1,3 +1,5 @@
+import asyncio
+
 from agents import function_tool
 from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX
 from agents.realtime import RealtimeAgent, realtime_handoff
@@ -13,20 +15,26 @@
     name_override="faq_lookup_tool", description_override="Lookup frequently asked questions."
 )
 async def faq_lookup_tool(question: str) -> str:
-    if "bag" in question or "baggage" in question:
+    print("faq_lookup_tool called with question:", question)
+
+    # Simulate a slow API call
+    await asyncio.sleep(3)
+
+    q = question.lower()
+    if "wifi" in q or "wi-fi" in q:
+        return "We have free wifi on the plane, join Airline-Wifi"
+    elif "bag" in q or "baggage" in q:
         return (
             "You are allowed to bring one bag on the plane. "
             "It must be under 50 pounds and 22 inches x 14 inches x 9 inches."
         )
-    elif "seats" in question or "plane" in question:
+    elif "seats" in q or "plane" in q:
         return (
             "There are 120 seats on the plane. "
             "There are 22 business class seats and 98 economy seats. "
             "Exit rows are rows 4 and 16. "
             "Rows 5-8 are Economy Plus, with extra legroom. "
         )
-    elif "wifi" in question:
-        return "We have free wifi on the plane, join Airline-Wifi"
     return "I'm sorry, I don't know the answer to that question."
 
 

examples/realtime/app/server.py

@@ -47,6 +47,9 @@ async def connect(self, websocket: WebSocket, session_id: str):
 
         agent = get_starting_agent()
         runner = RealtimeRunner(agent)
+        # If you want to customize the runner behavior, you can pass options:
+        # runner_config = RealtimeRunConfig(async_tool_calls=False)
+        # runner = RealtimeRunner(agent, config=runner_config)
         model_config: RealtimeModelConfig = {
             "initial_model_settings": {
                 "turn_detection": {

examples/realtime/cli/ui.py

@@ -1,6 +1,6 @@
 [project]
 name = "openai-agents"
-version = "0.4.0"
+version = "0.4.2"
 description = "OpenAI Agents SDK"
 readme = "README.md"
 requires-python = ">=3.9"

pyproject.toml

@@ -319,3 +319,16 @@ async def clear_session(self) -> None:
                 await sess.execute(
                     delete(self._sessions).where(self._sessions.c.session_id == self.session_id)
                 )
+
+    @property
+    def engine(self) -> AsyncEngine:
+        """Access the underlying SQLAlchemy AsyncEngine.
+
+        This property provides direct access to the engine for advanced use cases,
+        such as checking connection pool status, configuring engine settings,
+        or manually disposing the engine when needed.
+
+        Returns:
+            AsyncEngine: The SQLAlchemy async engine instance.
+        """
+        return self._engine