Merge branch 'main' into log-tool-errors

Author: danilbogdan

.github/workflows/tests.yml

@@ -51,8 +51,7 @@ jobs:
           - "3.11"
           - "3.12"
           - "3.13"
-          # TODO: enable this https://github.com/openai/openai-agents-python/pull/1961/
-          # - "3.14"
+          - "3.14"
     env:
       OPENAI_API_KEY: fake-for-tests
     steps:

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/twilio_sip/README.md

@@ -0,0 +1,55 @@
+# Twilio SIP Realtime Example
+
+This example shows how to handle OpenAI Realtime SIP calls with the Agents SDK. Incoming calls are accepted through the Realtime Calls API, a triage agent answers with a fixed greeting, and handoffs route the caller to specialist agents (FAQ lookup and record updates) similar to the realtime UI demo.
+
+## Prerequisites
+
+- Python 3.9+
+- An OpenAI API key with Realtime API access
+- A configured webhook secret for your OpenAI project
+- A Twilio account with a phone number and Elastic SIP Trunking enabled
+- A public HTTPS endpoint for local development (for example, [ngrok](https://ngrok.com/))
+
+## Configure OpenAI
+
+1. In [platform settings](https://platform.openai.com/settings) select your project.
+2. Create a webhook pointing to `https://<your-public-host>/openai/webhook` with "realtime.call.incoming" event type and note the signing secret. The example verifies each webhook with `OPENAI_WEBHOOK_SECRET`.
+
+## Configure Twilio Elastic SIP Trunking
+
+1. Create (or edit) an Elastic SIP trunk.
+2. On the **Origination** tab, add an origination SIP URI of `sip:proj_<your_project_id>@sip.api.openai.com;transport=tls` so Twilio sends inbound calls to OpenAI. (The Termination tab always ends with `.pstn.twilio.com`, so leave it unchanged.)
+3. Add at least one phone number to the trunk so inbound calls are forwarded to OpenAI.
+
+## Setup
+
+1. Install dependencies:
+   ```bash
+   uv pip install -r examples/realtime/twilio-sip/requirements.txt
+   ```
+2. Export required environment variables:
+   ```bash
+   export OPENAI_API_KEY="sk-..."
+   export OPENAI_WEBHOOK_SECRET="whsec_..."
+   ```
+3. (Optional) Adjust the multi-agent logic in `examples/realtime/twilio_sip/agents.py` if you want
+   to change the specialist agents or tools.
+4. Run the FastAPI server:
+   ```bash
+   uv run uvicorn examples.realtime.twilio_sip.server:app --host 0.0.0.0 --port 8000
+   ```
+5. Expose the server publicly (example with ngrok):
+   ```bash
+   ngrok http 8000
+   ```
+
+## Test a Call
+
+1. Place a call to the Twilio number attached to the SIP trunk.
+2. Twilio sends the call to `sip.api.openai.com`; OpenAI fires `realtime.call.incoming`, which this example accepts.
+3. The triage agent greets the caller, then either keeps the conversation or hands off to:
+   - **FAQ Agent** – answers common questions via `faq_lookup_tool`.
+   - **Records Agent** – writes short notes using `update_customer_record`.
+4. The background task attaches to the call and logs transcripts plus basic events in the console.
+
+You can edit `server.py` to change instructions, add tools, or integrate with internal systems once the SIP session is active.

examples/realtime/twilio_sip/__init__.py

@@ -0,0 +1 @@
+"""OpenAI Realtime SIP example package."""

examples/realtime/twilio_sip/agents.py

@@ -0,0 +1,87 @@
+"""Realtime agent definitions shared by the Twilio SIP example."""
+
+from __future__ import annotations
+
+import asyncio
+
+from agents import function_tool
+from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX
+from agents.realtime import RealtimeAgent, realtime_handoff
+
+# --- Tools -----------------------------------------------------------------
+
+
+WELCOME_MESSAGE = "Hello, this is ABC customer service. How can I help you today?"
+
+
+@function_tool(
+    name_override="faq_lookup_tool", description_override="Lookup frequently asked questions."
+)
+async def faq_lookup_tool(question: str) -> str:
+    """Fetch FAQ answers for the caller."""
+
+    await asyncio.sleep(3)
+
+    q = question.lower()
+    if "plan" in q or "wifi" in q or "wi-fi" in q:
+        return "We provide complimentary Wi-Fi. Join the ABC-Customer network."  # demo data
+    if "billing" in q or "invoice" in q:
+        return "Your latest invoice is available in the ABC portal under Billing > History."
+    if "hours" in q or "support" in q:
+        return "Human support agents are available 24/7; transfer to the specialist if needed."
+    return "I'm not sure about that. Let me transfer you back to the triage agent."
+
+
+@function_tool
+async def update_customer_record(customer_id: str, note: str) -> str:
+    """Record a short note about the caller."""
+
+    await asyncio.sleep(1)
+    return f"Recorded note for {customer_id}: {note}"
+
+
+# --- Agents ----------------------------------------------------------------
+
+
+faq_agent = RealtimeAgent(
+    name="FAQ Agent",
+    handoff_description="Handles frequently asked questions and general account inquiries.",
+    instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
+    You are an FAQ specialist. Always rely on the faq_lookup_tool for answers and keep replies
+    concise. If the caller needs hands-on help, transfer back to the triage agent.
+    """,
+    tools=[faq_lookup_tool],
+)
+
+records_agent = RealtimeAgent(
+    name="Records Agent",
+    handoff_description="Updates customer records with brief notes and confirmation numbers.",
+    instructions=f"""{RECOMMENDED_PROMPT_PREFIX}
+    You handle structured updates. Confirm the customer's ID, capture their request in a short
+    note, and use the update_customer_record tool. For anything outside data updates, return to the
+    triage agent.
+    """,
+    tools=[update_customer_record],
+)
+
+triage_agent = RealtimeAgent(
+    name="Triage Agent",
+    handoff_description="Greets callers and routes them to the most appropriate specialist.",
+    instructions=(
+        f"{RECOMMENDED_PROMPT_PREFIX} "
+        "Always begin the call by saying exactly: '"
+        f"{WELCOME_MESSAGE}' "
+        "before collecting details. Once the greeting is complete, gather context and hand off to "
+        "the FAQ or Records agents when appropriate."
+    ),
+    handoffs=[faq_agent, realtime_handoff(records_agent)],
+)
+
+faq_agent.handoffs.append(triage_agent)
+records_agent.handoffs.append(triage_agent)
+
+
+def get_starting_agent() -> RealtimeAgent:
+    """Return the agent used to start each realtime call."""
+
+    return triage_agent

examples/realtime/twilio_sip/requirements.txt

@@ -0,0 +1,3 @@
+fastapi>=0.120.0
+openai>=2.2,<3
+uvicorn[standard]>=0.38.0