Merge branch 'main' into update-docs-job

Author: seratch

pyproject.toml

@@ -7,7 +7,7 @@ requires-python = ">=3.9"
 license = "MIT"
 authors = [{ name = "OpenAI", email = "support@openai.com" }]
 dependencies = [
-    "openai>=1.87.0",
+    "openai>=1.93.1, <2",
     "pydantic>=2.10, <3",
     "griffe>=1.5.6, <2",
     "typing-extensions>=4.12.2, <5",

src/agents/model_settings.py

@@ -42,11 +42,14 @@ def validate_from_none(value: None) -> _Omit:
             serialization=core_schema.plain_serializer_function_ser_schema(lambda instance: None),
         )
 
+@dataclass
+class MCPToolChoice:
+    server_label: str
+    name: str
 
 Omit = Annotated[_Omit, _OmitTypeAnnotation]
 Headers: TypeAlias = Mapping[str, Union[str, Omit]]
-ToolChoice: TypeAlias = Union[Literal["auto", "required", "none"], str, None]
-
+ToolChoice: TypeAlias = Union[Literal["auto", "required", "none"], str, MCPToolChoice, None]
 
 @dataclass
 class ModelSettings:

src/agents/models/chatcmpl_converter.py

@@ -44,17 +44,20 @@
 from ..exceptions import AgentsException, UserError
 from ..handoffs import Handoff
 from ..items import TResponseInputItem, TResponseOutputItem
+from ..model_settings import MCPToolChoice
 from ..tool import FunctionTool, Tool
 from .fake_id import FAKE_RESPONSES_ID
 
 
 class Converter:
     @classmethod
     def convert_tool_choice(
-        cls, tool_choice: Literal["auto", "required", "none"] | str | None
+        cls, tool_choice: Literal["auto", "required", "none"] | str | MCPToolChoice | None
     ) -> ChatCompletionToolChoiceOptionParam | NotGiven:
         if tool_choice is None:
             return NOT_GIVEN
+        elif isinstance(tool_choice, MCPToolChoice):
+            raise UserError("MCPToolChoice is not supported for Chat Completions models")
         elif tool_choice == "auto":
             return "auto"
         elif tool_choice == "required":

src/agents/models/openai_responses.py

@@ -25,6 +25,7 @@
 from ..handoffs import Handoff
 from ..items import ItemHelpers, ModelResponse, TResponseInputItem
 from ..logger import logger
+from ..model_settings import MCPToolChoice
 from ..tool import (
     CodeInterpreterTool,
     ComputerTool,
@@ -303,10 +304,16 @@ class ConvertedTools:
 class Converter:
     @classmethod
     def convert_tool_choice(
-        cls, tool_choice: Literal["auto", "required", "none"] | str | None
+        cls, tool_choice: Literal["auto", "required", "none"] | str | MCPToolChoice | None
     ) -> response_create_params.ToolChoice | NotGiven:
         if tool_choice is None:
             return NOT_GIVEN
+        elif isinstance(tool_choice, MCPToolChoice):
+            return {
+                "server_label": tool_choice.server_label,
+                "type": "mcp",
+                "name": tool_choice.name,
+            }
         elif tool_choice == "required":
             return "required"
         elif tool_choice == "auto":
@@ -334,9 +341,9 @@ def convert_tool_choice(
                 "type": "code_interpreter",
             }
         elif tool_choice == "mcp":
-            return {
-                "type": "mcp",
-            }
+            # Note that this is still here for backwards compatibility,
+            # but migrating to MCPToolChoice is recommended.
+            return { "type": "mcp" }  # type: ignore [typeddict-item]
         else:
             return {
                 "type": "function",

src/agents/realtime/config.py

@@ -8,6 +8,7 @@
 
 from typing_extensions import NotRequired, TypeAlias, TypedDict
 
+from ..guardrail import OutputGuardrail
 from ..model_settings import ToolChoice
 from ..tool import Tool
 
@@ -82,11 +83,43 @@ class RealtimeSessionModelSettings(TypedDict):
     tool_choice: NotRequired[ToolChoice]
     tools: NotRequired[list[Tool]]
 
+    tracing: NotRequired[RealtimeModelTracingConfig | None]
+
+
+class RealtimeGuardrailsSettings(TypedDict):
+    """Settings for output guardrails in realtime sessions."""
+
+    debounce_text_length: NotRequired[int]
+    """
+    The minimum number of characters to accumulate before running guardrails on transcript
+    deltas. Defaults to 100. Guardrails run every time the accumulated text reaches
+    1x, 2x, 3x, etc. times this threshold.
+    """
+
+
+class RealtimeModelTracingConfig(TypedDict):
+    """Configuration for tracing in realtime model sessions."""
+
+    workflow_name: NotRequired[str]
+    """The workflow name to use for tracing."""
+
+    group_id: NotRequired[str]
+    """A group identifier to use for tracing, to link multiple traces together."""
+
+    metadata: NotRequired[dict[str, Any]]
+    """Additional metadata to include with the trace."""
+
 
 class RealtimeRunConfig(TypedDict):
     model_settings: NotRequired[RealtimeSessionModelSettings]
 
-    # TODO (rm) Add tracing support
-    # tracing: NotRequired[RealtimeTracingConfig | None]
-    # TODO (rm) Add guardrail support
+    output_guardrails: NotRequired[list[OutputGuardrail[Any]]]
+    """List of output guardrails to run on the agent's responses."""
+
+    guardrails_settings: NotRequired[RealtimeGuardrailsSettings]
+    """Settings for guardrail execution."""
+
+    tracing_disabled: NotRequired[bool]
+    """Whether tracing is disabled for this run."""
+
     # TODO (rm) Add history audio storage config

src/agents/realtime/events.py

@@ -5,6 +5,7 @@
 
 from typing_extensions import TypeAlias
 
+from ..guardrail import OutputGuardrailResult
 from ..run_context import RunContextWrapper
 from ..tool import Tool
 from .agent import RealtimeAgent
@@ -181,7 +182,20 @@ class RealtimeHistoryAdded:
     type: Literal["history_added"] = "history_added"
 
 
-# TODO (rm) Add guardrails
+@dataclass
+class RealtimeGuardrailTripped:
+    """A guardrail has been tripped and the agent has been interrupted."""
+
+    guardrail_results: list[OutputGuardrailResult]
+    """The results from all triggered guardrails."""
+
+    message: str
+    """The message that was being generated when the guardrail was triggered."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["guardrail_tripped"] = "guardrail_tripped"
 
 RealtimeSessionEvent: TypeAlias = Union[
     RealtimeAgentStartEvent,
@@ -196,5 +210,6 @@ class RealtimeHistoryAdded:
     RealtimeError,
     RealtimeHistoryUpdated,
     RealtimeHistoryAdded,
+    RealtimeGuardrailTripped,
 ]
 """An event emitted by the realtime session."""

src/agents/realtime/model.py

@@ -38,6 +38,7 @@ class RealtimeModelConfig(TypedDict):
     """
 
     initial_model_settings: NotRequired[RealtimeSessionModelSettings]
+    """The initial model settings to use when connecting."""
 
 
 class RealtimeModel(abc.ABC):

src/agents/realtime/openai_realtime.py

@@ -6,7 +6,7 @@
 import json
 import os
 from datetime import datetime
-from typing import Any, Callable
+from typing import Any, Callable, Literal
 
 import websockets
 from openai.types.beta.realtime.conversation_item import ConversationItem
@@ -23,6 +23,7 @@
 from ..logger import logger
 from .config import (
     RealtimeClientMessage,
+    RealtimeModelTracingConfig,
     RealtimeSessionModelSettings,
     RealtimeUserInput,
 )
@@ -73,6 +74,7 @@ def __init__(self) -> None:
         self._audio_length_ms: float = 0.0
         self._ongoing_response: bool = False
         self._current_audio_content_index: int | None = None
+        self._tracing_config: RealtimeModelTracingConfig | Literal["auto"] | None = None
 
     async def connect(self, options: RealtimeModelConfig) -> None:
         """Establish a connection to the model and keep it alive."""
@@ -84,6 +86,11 @@ async def connect(self, options: RealtimeModelConfig) -> None:
         self.model = model_settings.get("model_name", self.model)
         api_key = await get_api_key(options.get("api_key"))
 
+        if "tracing" in model_settings:
+            self._tracing_config = model_settings["tracing"]
+        else:
+            self._tracing_config = "auto"
+
         if not api_key:
             raise UserError("API key is required but was not provided.")
 
@@ -96,6 +103,15 @@ async def connect(self, options: RealtimeModelConfig) -> None:
         self._websocket = await websockets.connect(url, additional_headers=headers)
         self._websocket_task = asyncio.create_task(self._listen_for_messages())
 
+    async def _send_tracing_config(
+        self, tracing_config: RealtimeModelTracingConfig | Literal["auto"] | None
+    ) -> None:
+        """Update tracing configuration via session.update event."""
+        if tracing_config is not None:
+            await self.send_event(
+                {"type": "session.update", "other_data": {"session": {"tracing": tracing_config}}}
+            )
+
     def add_listener(self, listener: RealtimeModelListener) -> None:
         """Add a listener to the model."""
         self._listeners.append(listener)
@@ -343,8 +359,7 @@ async def _handle_ws_event(self, event: dict[str, Any]):
             self._ongoing_response = False
             await self._emit_event(RealtimeModelTurnEndedEvent())
         elif parsed.type == "session.created":
-            # TODO (rm) tracing stuff here
-            pass
+            await self._send_tracing_config(self._tracing_config)
         elif parsed.type == "error":
             await self._emit_event(RealtimeModelErrorEvent(error=parsed.error))
         elif parsed.type == "conversation.item.deleted":

src/agents/realtime/runner.py

@@ -69,6 +69,7 @@ async def run(
         """
         model_settings = await self._get_model_settings(
             agent=self._starting_agent,
+            disable_tracing=self._config.get("tracing_disabled", False) if self._config else False,
             initial_settings=model_config.get("initial_model_settings") if model_config else None,
             overrides=self._config.get("model_settings") if self._config else None,
         )
@@ -82,13 +83,15 @@ async def run(
             agent=self._starting_agent,
             context=context,
             model_config=model_config,
+            run_config=self._config,
         )
 
         return session
 
     async def _get_model_settings(
         self,
         agent: RealtimeAgent,
+        disable_tracing: bool,
         context: TContext | None = None,
         initial_settings: RealtimeSessionModelSettings | None = None,
         overrides: RealtimeSessionModelSettings | None = None,
@@ -109,4 +112,7 @@ async def _get_model_settings(
         if overrides:
             model_settings.update(overrides)
 
+        if disable_tracing:
+            model_settings["tracing"] = None
+
         return model_settings