openai-agents 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

agents/realtime/config.py

@@ -9,6 +9,7 @@ from typing import (
 from typing_extensions import NotRequired, TypeAlias, TypedDict
 
 from ..guardrail import OutputGuardrail
+from ..handoffs import Handoff
 from ..model_settings import ToolChoice
 from ..tool import Tool
 
@@ -27,52 +28,95 @@ RealtimeModelName: TypeAlias = Union[
 
 
 RealtimeAudioFormat: TypeAlias = Union[Literal["pcm16", "g711_ulaw", "g711_alaw"], str]
+"""The audio format for realtime audio streams."""
 
 
 class RealtimeClientMessage(TypedDict):
     """A raw message to be sent to the model."""
 
     type: str  # explicitly required
+    """The type of the message."""
+
     other_data: NotRequired[dict[str, Any]]
     """Merged into the message body."""
 
 
 class RealtimeInputAudioTranscriptionConfig(TypedDict):
+    """Configuration for audio transcription in realtime sessions."""
+
     language: NotRequired[str]
+    """The language code for transcription."""
+
     model: NotRequired[Literal["gpt-4o-transcribe", "gpt-4o-mini-transcribe", "whisper-1"] | str]
+    """The transcription model to use."""
+
     prompt: NotRequired[str]
+    """An optional prompt to guide transcription."""
 
 
 class RealtimeTurnDetectionConfig(TypedDict):
     """Turn detection config. Allows extra vendor keys if needed."""
 
     type: NotRequired[Literal["semantic_vad", "server_vad"]]
+    """The type of voice activity detection to use."""
+
     create_response: NotRequired[bool]
+    """Whether to create a response when a turn is detected."""
+
     eagerness: NotRequired[Literal["auto", "low", "medium", "high"]]
+    """How eagerly to detect turn boundaries."""
+
     interrupt_response: NotRequired[bool]
+    """Whether to allow interrupting the assistant's response."""
+
     prefix_padding_ms: NotRequired[int]
+    """Padding time in milliseconds before turn detection."""
+
     silence_duration_ms: NotRequired[int]
+    """Duration of silence in milliseconds to trigger turn detection."""
+
     threshold: NotRequired[float]
+    """The threshold for voice activity detection."""
 
 
 class RealtimeSessionModelSettings(TypedDict):
     """Model settings for a realtime model session."""
 
     model_name: NotRequired[RealtimeModelName]
+    """The name of the realtime model to use."""
 
     instructions: NotRequired[str]
+    """System instructions for the model."""
+
     modalities: NotRequired[list[Literal["text", "audio"]]]
+    """The modalities the model should support."""
+
     voice: NotRequired[str]
+    """The voice to use for audio output."""
 
     input_audio_format: NotRequired[RealtimeAudioFormat]
+    """The format for input audio streams."""
+
     output_audio_format: NotRequired[RealtimeAudioFormat]
+    """The format for output audio streams."""
+
     input_audio_transcription: NotRequired[RealtimeInputAudioTranscriptionConfig]
+    """Configuration for transcribing input audio."""
+
     turn_detection: NotRequired[RealtimeTurnDetectionConfig]
+    """Configuration for detecting conversation turns."""
 
     tool_choice: NotRequired[ToolChoice]
+    """How the model should choose which tools to call."""
+
     tools: NotRequired[list[Tool]]
+    """List of tools available to the model."""
+
+    handoffs: NotRequired[list[Handoff]]
+    """List of handoff configurations."""
 
     tracing: NotRequired[RealtimeModelTracingConfig | None]
+    """Configuration for request tracing."""
 
 
 class RealtimeGuardrailsSettings(TypedDict):
@@ -100,7 +144,10 @@ class RealtimeModelTracingConfig(TypedDict):
 
 
 class RealtimeRunConfig(TypedDict):
+    """Configuration for running a realtime agent session."""
+
     model_settings: NotRequired[RealtimeSessionModelSettings]
+    """Settings for the realtime model session."""
 
     output_guardrails: NotRequired[list[OutputGuardrail[Any]]]
     """List of output guardrails to run on the agent's responses."""
@@ -115,14 +162,27 @@ class RealtimeRunConfig(TypedDict):
 
 
 class RealtimeUserInputText(TypedDict):
+    """A text input from the user."""
+
     type: Literal["input_text"]
+    """The type identifier for text input."""
+
     text: str
+    """The text content from the user."""
 
 
 class RealtimeUserInputMessage(TypedDict):
+    """A message input from the user."""
+
     type: Literal["message"]
+    """The type identifier for message inputs."""
+
     role: Literal["user"]
+    """The role identifier for user messages."""
+
     content: list[RealtimeUserInputText]
+    """List of text content items in the message."""
 
 
 RealtimeUserInput: TypeAlias = Union[str, RealtimeUserInputMessage]
+"""User input that can be a string or structured message."""

agents/realtime/handoffs.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import inspect
+from typing import TYPE_CHECKING, Any, Callable, cast, overload
+
+from pydantic import TypeAdapter
+from typing_extensions import TypeVar
+
+from ..exceptions import ModelBehaviorError, UserError
+from ..handoffs import Handoff
+from ..run_context import RunContextWrapper, TContext
+from ..strict_schema import ensure_strict_json_schema
+from ..tracing.spans import SpanError
+from ..util import _error_tracing, _json
+from ..util._types import MaybeAwaitable
+
+if TYPE_CHECKING:
+    from ..agent import AgentBase
+    from . import RealtimeAgent
+
+
+# The handoff input type is the type of data passed when the agent is called via a handoff.
+THandoffInput = TypeVar("THandoffInput", default=Any)
+
+OnHandoffWithInput = Callable[[RunContextWrapper[Any], THandoffInput], Any]
+OnHandoffWithoutInput = Callable[[RunContextWrapper[Any]], Any]
+
+
+@overload
+def realtime_handoff(
+    agent: RealtimeAgent[TContext],
+    *,
+    tool_name_override: str | None = None,
+    tool_description_override: str | None = None,
+    is_enabled: bool
+    | Callable[[RunContextWrapper[Any], RealtimeAgent[Any]], MaybeAwaitable[bool]] = True,
+) -> Handoff[TContext, RealtimeAgent[TContext]]: ...
+
+
+@overload
+def realtime_handoff(
+    agent: RealtimeAgent[TContext],
+    *,
+    on_handoff: OnHandoffWithInput[THandoffInput],
+    input_type: type[THandoffInput],
+    tool_description_override: str | None = None,
+    tool_name_override: str | None = None,
+    is_enabled: bool
+    | Callable[[RunContextWrapper[Any], RealtimeAgent[Any]], MaybeAwaitable[bool]] = True,
+) -> Handoff[TContext, RealtimeAgent[TContext]]: ...
+
+
+@overload
+def realtime_handoff(
+    agent: RealtimeAgent[TContext],
+    *,
+    on_handoff: OnHandoffWithoutInput,
+    tool_description_override: str | None = None,
+    tool_name_override: str | None = None,
+    is_enabled: bool
+    | Callable[[RunContextWrapper[Any], RealtimeAgent[Any]], MaybeAwaitable[bool]] = True,
+) -> Handoff[TContext, RealtimeAgent[TContext]]: ...
+
+
+def realtime_handoff(
+    agent: RealtimeAgent[TContext],
+    tool_name_override: str | None = None,
+    tool_description_override: str | None = None,
+    on_handoff: OnHandoffWithInput[THandoffInput] | OnHandoffWithoutInput | None = None,
+    input_type: type[THandoffInput] | None = None,
+    is_enabled: bool
+    | Callable[[RunContextWrapper[Any], RealtimeAgent[Any]], MaybeAwaitable[bool]] = True,
+) -> Handoff[TContext, RealtimeAgent[TContext]]:
+    """Create a handoff from a RealtimeAgent.
+
+    Args:
+        agent: The RealtimeAgent to handoff to, or a function that returns a RealtimeAgent.
+        tool_name_override: Optional override for the name of the tool that represents the handoff.
+        tool_description_override: Optional override for the description of the tool that
+            represents the handoff.
+        on_handoff: A function that runs when the handoff is invoked.
+        input_type: the type of the input to the handoff. If provided, the input will be validated
+            against this type. Only relevant if you pass a function that takes an input.
+        is_enabled: Whether the handoff is enabled. Can be a bool or a callable that takes the run
+            context and agent and returns whether the handoff is enabled. Disabled handoffs are
+            hidden from the LLM at runtime.
+
+    Note: input_filter is not supported for RealtimeAgent handoffs.
+    """
+    assert (on_handoff and input_type) or not (on_handoff and input_type), (
+        "You must provide either both on_handoff and input_type, or neither"
+    )
+    type_adapter: TypeAdapter[Any] | None
+    if input_type is not None:
+        assert callable(on_handoff), "on_handoff must be callable"
+        sig = inspect.signature(on_handoff)
+        if len(sig.parameters) != 2:
+            raise UserError("on_handoff must take two arguments: context and input")
+
+        type_adapter = TypeAdapter(input_type)
+        input_json_schema = type_adapter.json_schema()
+    else:
+        type_adapter = None
+        input_json_schema = {}
+        if on_handoff is not None:
+            sig = inspect.signature(on_handoff)
+            if len(sig.parameters) != 1:
+                raise UserError("on_handoff must take one argument: context")
+
+    async def _invoke_handoff(
+        ctx: RunContextWrapper[Any], input_json: str | None = None
+    ) -> RealtimeAgent[TContext]:
+        if input_type is not None and type_adapter is not None:
+            if input_json is None:
+                _error_tracing.attach_error_to_current_span(
+                    SpanError(
+                        message="Handoff function expected non-null input, but got None",
+                        data={"details": "input_json is None"},
+                    )
+                )
+                raise ModelBehaviorError("Handoff function expected non-null input, but got None")
+
+            validated_input = _json.validate_json(
+                json_str=input_json,
+                type_adapter=type_adapter,
+                partial=False,
+            )
+            input_func = cast(OnHandoffWithInput[THandoffInput], on_handoff)
+            if inspect.iscoroutinefunction(input_func):
+                await input_func(ctx, validated_input)
+            else:
+                input_func(ctx, validated_input)
+        elif on_handoff is not None:
+            no_input_func = cast(OnHandoffWithoutInput, on_handoff)
+            if inspect.iscoroutinefunction(no_input_func):
+                await no_input_func(ctx)
+            else:
+                no_input_func(ctx)
+
+        return agent
+
+    tool_name = tool_name_override or Handoff.default_tool_name(agent)
+    tool_description = tool_description_override or Handoff.default_tool_description(agent)
+
+    # Always ensure the input JSON schema is in strict mode
+    # If there is a need, we can make this configurable in the future
+    input_json_schema = ensure_strict_json_schema(input_json_schema)
+
+    async def _is_enabled(ctx: RunContextWrapper[Any], agent_base: AgentBase[Any]) -> bool:
+        assert callable(is_enabled), "is_enabled must be non-null here"
+        assert isinstance(agent_base, RealtimeAgent), "Can't handoff to a non-RealtimeAgent"
+        result = is_enabled(ctx, agent_base)
+        if inspect.isawaitable(result):
+            return await result
+        return result
+
+    return Handoff(
+        tool_name=tool_name,
+        tool_description=tool_description,
+        input_json_schema=input_json_schema,
+        on_invoke_handoff=_invoke_handoff,
+        input_filter=None,  # Not supported for RealtimeAgent handoffs
+        agent_name=agent.name,
+        is_enabled=_is_enabled if callable(is_enabled) else is_enabled,
+    )

agents/realtime/items.py

@@ -6,59 +6,127 @@ from pydantic import BaseModel, ConfigDict, Field
 
 
 class InputText(BaseModel):
+    """Text input content for realtime messages."""
+
     type: Literal["input_text"] = "input_text"
+    """The type identifier for text input."""
+
     text: str | None = None
+    """The text content."""
 
     # Allow extra data
     model_config = ConfigDict(extra="allow")
 
 
 class InputAudio(BaseModel):
+    """Audio input content for realtime messages."""
+
     type: Literal["input_audio"] = "input_audio"
+    """The type identifier for audio input."""
+
     audio: str | None = None
+    """The base64-encoded audio data."""
+
     transcript: str | None = None
+    """The transcript of the audio, if available."""
 
     # Allow extra data
     model_config = ConfigDict(extra="allow")
 
 
 class AssistantText(BaseModel):
+    """Text content from the assistant in realtime responses."""
+
     type: Literal["text"] = "text"
+    """The type identifier for text content."""
+
     text: str | None = None
+    """The text content from the assistant."""
+
+    # Allow extra data
+    model_config = ConfigDict(extra="allow")
+
+
+class AssistantAudio(BaseModel):
+    """Audio content from the assistant in realtime responses."""
+
+    type: Literal["audio"] = "audio"
+    """The type identifier for audio content."""
+
+    audio: str | None = None
+    """The base64-encoded audio data from the assistant."""
+
+    transcript: str | None = None
+    """The transcript of the audio response."""
 
     # Allow extra data
     model_config = ConfigDict(extra="allow")
 
 
 class SystemMessageItem(BaseModel):
+    """A system message item in realtime conversations."""
+
     item_id: str
+    """Unique identifier for this message item."""
+
     previous_item_id: str | None = None
+    """ID of the previous item in the conversation."""
+
     type: Literal["message"] = "message"
+    """The type identifier for message items."""
+
     role: Literal["system"] = "system"
+    """The role identifier for system messages."""
+
     content: list[InputText]
+    """List of text content for the system message."""
 
     # Allow extra data
     model_config = ConfigDict(extra="allow")
 
 
 class UserMessageItem(BaseModel):
+    """A user message item in realtime conversations."""
+
     item_id: str
+    """Unique identifier for this message item."""
+
     previous_item_id: str | None = None
+    """ID of the previous item in the conversation."""
+
     type: Literal["message"] = "message"
+    """The type identifier for message items."""
+
     role: Literal["user"] = "user"
+    """The role identifier for user messages."""
+
     content: list[Annotated[InputText | InputAudio, Field(discriminator="type")]]
+    """List of content items, can be text or audio."""
 
     # Allow extra data
     model_config = ConfigDict(extra="allow")
 
 
 class AssistantMessageItem(BaseModel):
+    """An assistant message item in realtime conversations."""
+
     item_id: str
+    """Unique identifier for this message item."""
+
     previous_item_id: str | None = None
+    """ID of the previous item in the conversation."""
+
     type: Literal["message"] = "message"
+    """The type identifier for message items."""
+
     role: Literal["assistant"] = "assistant"
+    """The role identifier for assistant messages."""
+
     status: Literal["in_progress", "completed", "incomplete"] | None = None
-    content: list[AssistantText]
+    """The status of the assistant's response."""
+
+    content: list[Annotated[AssistantText | AssistantAudio, Field(discriminator="type")]]
+    """List of content items from the assistant, can be text or audio."""
 
     # Allow extra data
     model_config = ConfigDict(extra="allow")
@@ -68,24 +136,49 @@ RealtimeMessageItem = Annotated[
     Union[SystemMessageItem, UserMessageItem, AssistantMessageItem],
     Field(discriminator="role"),
 ]
+"""A message item that can be from system, user, or assistant."""
 
 
 class RealtimeToolCallItem(BaseModel):
+    """A tool call item in realtime conversations."""
+
     item_id: str
+    """Unique identifier for this tool call item."""
+
     previous_item_id: str | None = None
+    """ID of the previous item in the conversation."""
+
+    call_id: str | None
+    """The call ID for this tool invocation."""
+
     type: Literal["function_call"] = "function_call"
+    """The type identifier for function call items."""
+
     status: Literal["in_progress", "completed"]
+    """The status of the tool call execution."""
+
     arguments: str
+    """The JSON string arguments passed to the tool."""
+
     name: str
+    """The name of the tool being called."""
+
     output: str | None = None
+    """The output result from the tool execution."""
 
     # Allow extra data
     model_config = ConfigDict(extra="allow")
 
 
 RealtimeItem = Union[RealtimeMessageItem, RealtimeToolCallItem]
+"""A realtime item that can be a message or tool call."""
 
 
 class RealtimeResponse(BaseModel):
+    """A response from the realtime model."""
+
     id: str
+    """Unique identifier for this response."""
+
     output: list[RealtimeMessageItem]
+    """List of message items in the response."""