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

agents/realtime/config.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+from typing import (
+    Any,
+    Literal,
+    Union,
+)
+
+from typing_extensions import NotRequired, TypeAlias, TypedDict
+
+from ..guardrail import OutputGuardrail
+from ..handoffs import Handoff
+from ..model_settings import ToolChoice
+from ..tool import Tool
+
+RealtimeModelName: TypeAlias = Union[
+    Literal[
+        "gpt-4o-realtime-preview",
+        "gpt-4o-mini-realtime-preview",
+        "gpt-4o-realtime-preview-2025-06-03",
+        "gpt-4o-realtime-preview-2024-12-17",
+        "gpt-4o-realtime-preview-2024-10-01",
+        "gpt-4o-mini-realtime-preview-2024-12-17",
+    ],
+    str,
+]
+"""The name of a realtime model."""
+
+
+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):
+    """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):
+    """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."""
+
+    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
+
+
+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/events.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Union
+
+from typing_extensions import TypeAlias
+
+from ..guardrail import OutputGuardrailResult
+from ..run_context import RunContextWrapper
+from ..tool import Tool
+from .agent import RealtimeAgent
+from .items import RealtimeItem
+from .model_events import RealtimeModelAudioEvent, RealtimeModelEvent
+
+
+@dataclass
+class RealtimeEventInfo:
+    context: RunContextWrapper
+    """The context for the event."""
+
+
+@dataclass
+class RealtimeAgentStartEvent:
+    """A new agent has started."""
+
+    agent: RealtimeAgent
+    """The new agent."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["agent_start"] = "agent_start"
+
+
+@dataclass
+class RealtimeAgentEndEvent:
+    """An agent has ended."""
+
+    agent: RealtimeAgent
+    """The agent that ended."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["agent_end"] = "agent_end"
+
+
+@dataclass
+class RealtimeHandoffEvent:
+    """An agent has handed off to another agent."""
+
+    from_agent: RealtimeAgent
+    """The agent that handed off."""
+
+    to_agent: RealtimeAgent
+    """The agent that was handed off to."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["handoff"] = "handoff"
+
+
+@dataclass
+class RealtimeToolStart:
+    """An agent is starting a tool call."""
+
+    agent: RealtimeAgent
+    """The agent that updated."""
+
+    tool: Tool
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["tool_start"] = "tool_start"
+
+
+@dataclass
+class RealtimeToolEnd:
+    """An agent has ended a tool call."""
+
+    agent: RealtimeAgent
+    """The agent that ended the tool call."""
+
+    tool: Tool
+    """The tool that was called."""
+
+    output: Any
+    """The output of the tool call."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["tool_end"] = "tool_end"
+
+
+@dataclass
+class RealtimeRawModelEvent:
+    """Forwards raw events from the model layer."""
+
+    data: RealtimeModelEvent
+    """The raw data from the model layer."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["raw_model_event"] = "raw_model_event"
+
+
+@dataclass
+class RealtimeAudioEnd:
+    """Triggered when the agent stops generating audio."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["audio_end"] = "audio_end"
+
+
+@dataclass
+class RealtimeAudio:
+    """Triggered when the agent generates new audio to be played."""
+
+    audio: RealtimeModelAudioEvent
+    """The audio event from the model layer."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["audio"] = "audio"
+
+
+@dataclass
+class RealtimeAudioInterrupted:
+    """Triggered when the agent is interrupted. Can be listened to by the user to stop audio
+    playback or give visual indicators to the user.
+    """
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["audio_interrupted"] = "audio_interrupted"
+
+
+@dataclass
+class RealtimeError:
+    """An error has occurred."""
+
+    error: Any
+    """The error that occurred."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["error"] = "error"
+
+
+@dataclass
+class RealtimeHistoryUpdated:
+    """The history has been updated. Contains the full history of the session."""
+
+    history: list[RealtimeItem]
+    """The full history of the session."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["history_updated"] = "history_updated"
+
+
+@dataclass
+class RealtimeHistoryAdded:
+    """A new item has been added to the history."""
+
+    item: RealtimeItem
+    """The new item that was added to the history."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["history_added"] = "history_added"
+
+
+@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,
+    RealtimeAgentEndEvent,
+    RealtimeHandoffEvent,
+    RealtimeToolStart,
+    RealtimeToolEnd,
+    RealtimeRawModelEvent,
+    RealtimeAudioEnd,
+    RealtimeAudio,
+    RealtimeAudioInterrupted,
+    RealtimeError,
+    RealtimeHistoryUpdated,
+    RealtimeHistoryAdded,
+    RealtimeGuardrailTripped,
+]
+"""An event emitted by the realtime session."""

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,
+    )