openai-agents 0.2.8__py3-none-any.whl → 0.6.8__py3-none-any.whl

agents/models/openai_responses.py

@@ -2,10 +2,11 @@ from __future__ import annotations
 
 import json
 from collections.abc import AsyncIterator
+from contextvars import ContextVar
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Literal, cast, overload
+from typing import TYPE_CHECKING, Any, Literal, Union, cast, overload
 
-from openai import NOT_GIVEN, APIStatusError, AsyncOpenAI, AsyncStream, NotGiven
+from openai import APIStatusError, AsyncOpenAI, AsyncStream, Omit, omit
 from openai.types import ChatModel
 from openai.types.responses import (
     Response,
@@ -14,19 +15,20 @@ from openai.types.responses import (
     ResponseStreamEvent,
     ResponseTextConfigParam,
     ToolParam,
-    WebSearchToolParam,
     response_create_params,
 )
 from openai.types.responses.response_prompt_param import ResponsePromptParam
 
 from .. import _debug
 from ..agent_output import AgentOutputSchemaBase
+from ..computer import AsyncComputer, Computer
 from ..exceptions import UserError
 from ..handoffs import Handoff
 from ..items import ItemHelpers, ModelResponse, TResponseInputItem
 from ..logger import logger
 from ..model_settings import MCPToolChoice
 from ..tool import (
+    ApplyPatchTool,
     CodeInterpreterTool,
     ComputerTool,
     FileSearchTool,
@@ -34,12 +36,15 @@ from ..tool import (
     HostedMCPTool,
     ImageGenerationTool,
     LocalShellTool,
+    ShellTool,
     Tool,
     WebSearchTool,
 )
 from ..tracing import SpanError, response_span
 from ..usage import Usage
+from ..util._json import _to_dump_compatible
 from ..version import __version__
+from .fake_id import FAKE_RESPONSES_ID
 from .interface import Model, ModelTracing
 
 if TYPE_CHECKING:
@@ -49,6 +54,11 @@ if TYPE_CHECKING:
 _USER_AGENT = f"Agents/Python {__version__}"
 _HEADERS = {"User-Agent": _USER_AGENT}
 
+# Override headers used by the Responses API.
+_HEADERS_OVERRIDE: ContextVar[dict[str, str] | None] = ContextVar(
+    "openai_responses_headers_override", default=None
+)
+
 
 class OpenAIResponsesModel(Model):
     """
@@ -59,12 +69,15 @@ class OpenAIResponsesModel(Model):
         self,
         model: str | ChatModel,
         openai_client: AsyncOpenAI,
+        *,
+        model_is_explicit: bool = True,
     ) -> None:
         self.model = model
+        self._model_is_explicit = model_is_explicit
         self._client = openai_client
 
-    def _non_null_or_not_given(self, value: Any) -> Any:
-        return value if value is not None else NOT_GIVEN
+    def _non_null_or_omit(self, value: Any) -> Any:
+        return value if value is not None else omit
 
     async def get_response(
         self,
@@ -75,7 +88,8 @@ class OpenAIResponsesModel(Model):
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         tracing: ModelTracing,
-        previous_response_id: str | None,
+        previous_response_id: str | None = None,
+        conversation_id: str | None = None,
         prompt: ResponsePromptParam | None = None,
     ) -> ModelResponse:
         with response_span(disabled=tracing.is_disabled()) as span_response:
@@ -87,7 +101,8 @@ class OpenAIResponsesModel(Model):
                     tools,
                     output_schema,
                     handoffs,
-                    previous_response_id,
+                    previous_response_id=previous_response_id,
+                    conversation_id=conversation_id,
                     stream=False,
                     prompt=prompt,
                 )
@@ -150,7 +165,8 @@ class OpenAIResponsesModel(Model):
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         tracing: ModelTracing,
-        previous_response_id: str | None,
+        previous_response_id: str | None = None,
+        conversation_id: str | None = None,
         prompt: ResponsePromptParam | None = None,
     ) -> AsyncIterator[ResponseStreamEvent]:
         """
@@ -165,7 +181,8 @@ class OpenAIResponsesModel(Model):
                     tools,
                     output_schema,
                     handoffs,
-                    previous_response_id,
+                    previous_response_id=previous_response_id,
+                    conversation_id=conversation_id,
                     stream=True,
                     prompt=prompt,
                 )
@@ -203,6 +220,7 @@ class OpenAIResponsesModel(Model):
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         previous_response_id: str | None,
+        conversation_id: str | None,
         stream: Literal[True],
         prompt: ResponsePromptParam | None = None,
     ) -> AsyncStream[ResponseStreamEvent]: ...
@@ -217,6 +235,7 @@ class OpenAIResponsesModel(Model):
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         previous_response_id: str | None,
+        conversation_id: str | None,
         stream: Literal[False],
         prompt: ResponsePromptParam | None = None,
     ) -> Response: ...
@@ -229,23 +248,32 @@ class OpenAIResponsesModel(Model):
         tools: list[Tool],
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
-        previous_response_id: str | None,
+        previous_response_id: str | None = None,
+        conversation_id: str | None = None,
         stream: Literal[True] | Literal[False] = False,
         prompt: ResponsePromptParam | None = None,
     ) -> Response | AsyncStream[ResponseStreamEvent]:
         list_input = ItemHelpers.input_to_new_input_list(input)
+        list_input = _to_dump_compatible(list_input)
+        list_input = self._remove_openai_responses_api_incompatible_fields(list_input)
 
-        parallel_tool_calls = (
-            True
-            if model_settings.parallel_tool_calls and tools and len(tools) > 0
-            else False
-            if model_settings.parallel_tool_calls is False
-            else NOT_GIVEN
-        )
+        if model_settings.parallel_tool_calls and tools:
+            parallel_tool_calls: bool | Omit = True
+        elif model_settings.parallel_tool_calls is False:
+            parallel_tool_calls = False
+        else:
+            parallel_tool_calls = omit
 
         tool_choice = Converter.convert_tool_choice(model_settings.tool_choice)
         converted_tools = Converter.convert_tools(tools, handoffs)
+        converted_tools_payload = _to_dump_compatible(converted_tools.tools)
         response_format = Converter.get_response_format(output_schema)
+        should_omit_model = prompt is not None and not self._model_is_explicit
+        model_param: str | ChatModel | Omit = self.model if not should_omit_model else omit
+        should_omit_tools = prompt is not None and len(converted_tools_payload) == 0
+        tools_param: list[ToolParam] | Omit = (
+            converted_tools_payload if not should_omit_tools else omit
+        )
 
         include_set: set[str] = set(converted_tools.includes)
         if model_settings.response_include is not None:
@@ -257,55 +285,124 @@ class OpenAIResponsesModel(Model):
         if _debug.DONT_LOG_MODEL_DATA:
             logger.debug("Calling LLM")
         else:
+            input_json = json.dumps(
+                list_input,
+                indent=2,
+                ensure_ascii=False,
+            )
+            tools_json = json.dumps(
+                converted_tools_payload,
+                indent=2,
+                ensure_ascii=False,
+            )
             logger.debug(
                 f"Calling LLM {self.model} with input:\n"
-                f"{json.dumps(list_input, indent=2, ensure_ascii=False)}\n"
-                f"Tools:\n{json.dumps(converted_tools.tools, indent=2, ensure_ascii=False)}\n"
+                f"{input_json}\n"
+                f"Tools:\n{tools_json}\n"
                 f"Stream: {stream}\n"
                 f"Tool choice: {tool_choice}\n"
                 f"Response format: {response_format}\n"
                 f"Previous response id: {previous_response_id}\n"
+                f"Conversation id: {conversation_id}\n"
             )
 
         extra_args = dict(model_settings.extra_args or {})
         if model_settings.top_logprobs is not None:
             extra_args["top_logprobs"] = model_settings.top_logprobs
         if model_settings.verbosity is not None:
-            if response_format != NOT_GIVEN:
+            if response_format is not omit:
                 response_format["verbosity"] = model_settings.verbosity  # type: ignore [index]
             else:
                 response_format = {"verbosity": model_settings.verbosity}
 
-        return await self._client.responses.create(
-            previous_response_id=self._non_null_or_not_given(previous_response_id),
-            instructions=self._non_null_or_not_given(system_instructions),
-            model=self.model,
+        stream_param: Literal[True] | Omit = True if stream else omit
+
+        response = await self._client.responses.create(
+            previous_response_id=self._non_null_or_omit(previous_response_id),
+            conversation=self._non_null_or_omit(conversation_id),
+            instructions=self._non_null_or_omit(system_instructions),
+            model=model_param,
             input=list_input,
             include=include,
-            tools=converted_tools.tools,
-            prompt=self._non_null_or_not_given(prompt),
-            temperature=self._non_null_or_not_given(model_settings.temperature),
-            top_p=self._non_null_or_not_given(model_settings.top_p),
-            truncation=self._non_null_or_not_given(model_settings.truncation),
-            max_output_tokens=self._non_null_or_not_given(model_settings.max_tokens),
+            tools=tools_param,
+            prompt=self._non_null_or_omit(prompt),
+            temperature=self._non_null_or_omit(model_settings.temperature),
+            top_p=self._non_null_or_omit(model_settings.top_p),
+            truncation=self._non_null_or_omit(model_settings.truncation),
+            max_output_tokens=self._non_null_or_omit(model_settings.max_tokens),
             tool_choice=tool_choice,
             parallel_tool_calls=parallel_tool_calls,
-            stream=stream,
-            extra_headers={**_HEADERS, **(model_settings.extra_headers or {})},
+            stream=cast(Any, stream_param),
+            extra_headers=self._merge_headers(model_settings),
             extra_query=model_settings.extra_query,
             extra_body=model_settings.extra_body,
             text=response_format,
-            store=self._non_null_or_not_given(model_settings.store),
-            reasoning=self._non_null_or_not_given(model_settings.reasoning),
-            metadata=self._non_null_or_not_given(model_settings.metadata),
+            store=self._non_null_or_omit(model_settings.store),
+            prompt_cache_retention=self._non_null_or_omit(model_settings.prompt_cache_retention),
+            reasoning=self._non_null_or_omit(model_settings.reasoning),
+            metadata=self._non_null_or_omit(model_settings.metadata),
             **extra_args,
         )
+        return cast(Union[Response, AsyncStream[ResponseStreamEvent]], response)
+
+    def _remove_openai_responses_api_incompatible_fields(self, list_input: list[Any]) -> list[Any]:
+        """
+        Remove or transform input items that are incompatible with the OpenAI Responses API.
+
+        This data transformation does not always guarantee that items from other provider
+        interactions are accepted by the OpenAI Responses API.
+
+        Only items with truthy provider_data are processed.
+        This function handles the following incompatibilities:
+        - provider_data: Removes fields specific to other providers (e.g., Gemini, Claude).
+        - Fake IDs: Removes temporary IDs (FAKE_RESPONSES_ID) that should not be sent to OpenAI.
+        - Reasoning items: Filters out provider-specific reasoning items entirely.
+        """
+        # Early return optimization: if no item has provider_data, return unchanged.
+        has_provider_data = any(
+            isinstance(item, dict) and item.get("provider_data") for item in list_input
+        )
+        if not has_provider_data:
+            return list_input
+
+        result = []
+        for item in list_input:
+            cleaned = self._clean_item_for_openai(item)
+            if cleaned is not None:
+                result.append(cleaned)
+        return result
+
+    def _clean_item_for_openai(self, item: Any) -> Any | None:
+        # Only process dict items
+        if not isinstance(item, dict):
+            return item
+
+        # Filter out reasoning items with provider_data (provider-specific reasoning).
+        if item.get("type") == "reasoning" and item.get("provider_data"):
+            return None
+
+        # Remove fake response ID.
+        if item.get("id") == FAKE_RESPONSES_ID:
+            del item["id"]
+
+        # Remove provider_data field.
+        if "provider_data" in item:
+            del item["provider_data"]
+
+        return item
 
     def _get_client(self) -> AsyncOpenAI:
         if self._client is None:
             self._client = AsyncOpenAI()
         return self._client
 
+    def _merge_headers(self, model_settings: ModelSettings):
+        return {
+            **_HEADERS,
+            **(model_settings.extra_headers or {}),
+            **(_HEADERS_OVERRIDE.get() or {}),
+        }
+
 
 @dataclass
 class ConvertedTools:
@@ -317,9 +414,9 @@ class Converter:
     @classmethod
     def convert_tool_choice(
         cls, tool_choice: Literal["auto", "required", "none"] | str | MCPToolChoice | None
-    ) -> response_create_params.ToolChoice | NotGiven:
+    ) -> response_create_params.ToolChoice | Omit:
         if tool_choice is None:
-            return NOT_GIVEN
+            return omit
         elif isinstance(tool_choice, MCPToolChoice):
             return {
                 "server_label": tool_choice.server_label,
@@ -336,6 +433,11 @@ class Converter:
             return {
                 "type": "file_search",
             }
+        elif tool_choice == "web_search":
+            return {
+                # TODO: revist the type: ignore comment when ToolChoice is updated in the future
+                "type": "web_search",  # type: ignore[misc, return-value]
+            }
         elif tool_choice == "web_search_preview":
             return {
                 "type": "web_search_preview",
@@ -355,7 +457,7 @@ class Converter:
         elif tool_choice == "mcp":
             # Note that this is still here for backwards compatibility,
             # but migrating to MCPToolChoice is recommended.
-            return {"type": "mcp"}  # type: ignore [typeddict-item]
+            return {"type": "mcp"}  # type: ignore[misc, return-value]
         else:
             return {
                 "type": "function",
@@ -365,9 +467,9 @@ class Converter:
     @classmethod
     def get_response_format(
         cls, output_schema: AgentOutputSchemaBase | None
-    ) -> ResponseTextConfigParam | NotGiven:
+    ) -> ResponseTextConfigParam | Omit:
         if output_schema is None or output_schema.is_plain_text():
-            return NOT_GIVEN
+            return omit
         else:
             return {
                 "format": {
@@ -416,12 +518,13 @@ class Converter:
             }
             includes: ResponseIncludable | None = None
         elif isinstance(tool, WebSearchTool):
-            ws: WebSearchToolParam = {
-                "type": "web_search_preview",
+            # TODO: revist the type: ignore comment when ToolParam is updated in the future
+            converted_tool = {
+                "type": "web_search",
+                "filters": tool.filters.model_dump() if tool.filters is not None else None,  # type: ignore [typeddict-item]
                 "user_location": tool.user_location,
                 "search_context_size": tool.search_context_size,
             }
-            converted_tool = ws
             includes = None
         elif isinstance(tool, FileSearchTool):
             converted_tool = {
@@ -437,16 +540,29 @@ class Converter:
 
             includes = "file_search_call.results" if tool.include_search_results else None
         elif isinstance(tool, ComputerTool):
+            computer = tool.computer
+            if not isinstance(computer, (Computer, AsyncComputer)):
+                raise UserError(
+                    "Computer tool is not initialized for serialization. Call "
+                    "resolve_computer({ tool, run_context }) with a run context first "
+                    "when building payloads manually."
+                )
             converted_tool = {
                 "type": "computer_use_preview",
-                "environment": tool.computer.environment,
-                "display_width": tool.computer.dimensions[0],
-                "display_height": tool.computer.dimensions[1],
+                "environment": computer.environment,
+                "display_width": computer.dimensions[0],
+                "display_height": computer.dimensions[1],
             }
             includes = None
         elif isinstance(tool, HostedMCPTool):
             converted_tool = tool.tool_config
             includes = None
+        elif isinstance(tool, ApplyPatchTool):
+            converted_tool = cast(ToolParam, {"type": "apply_patch"})
+            includes = None
+        elif isinstance(tool, ShellTool):
+            converted_tool = cast(ToolParam, {"type": "shell"})
+            includes = None
         elif isinstance(tool, ImageGenerationTool):
             converted_tool = tool.tool_config
             includes = None

agents/realtime/__init__.py

@@ -3,6 +3,7 @@ from .config import (
     RealtimeAudioFormat,
     RealtimeClientMessage,
     RealtimeGuardrailsSettings,
+    RealtimeInputAudioNoiseReductionConfig,
     RealtimeInputAudioTranscriptionConfig,
     RealtimeModelName,
     RealtimeModelTracingConfig,
@@ -83,6 +84,7 @@ from .model_inputs import (
 )
 from .openai_realtime import (
     DEFAULT_MODEL_SETTINGS,
+    OpenAIRealtimeSIPModel,
     OpenAIRealtimeWebSocketModel,
     get_api_key,
 )
@@ -101,6 +103,7 @@ __all__ = [
     "RealtimeAudioFormat",
     "RealtimeClientMessage",
     "RealtimeGuardrailsSettings",
+    "RealtimeInputAudioNoiseReductionConfig",
     "RealtimeInputAudioTranscriptionConfig",
     "RealtimeModelName",
     "RealtimeModelTracingConfig",
@@ -174,6 +177,7 @@ __all__ = [
     "RealtimeModelUserInputMessage",
     # OpenAI Realtime
     "DEFAULT_MODEL_SETTINGS",
+    "OpenAIRealtimeSIPModel",
     "OpenAIRealtimeWebSocketModel",
     "get_api_key",
     # Session

agents/realtime/_util.py

@@ -2,8 +2,19 @@ from __future__ import annotations
 
 from .config import RealtimeAudioFormat
 
+PCM16_SAMPLE_RATE_HZ = 24_000
+PCM16_SAMPLE_WIDTH_BYTES = 2
+G711_SAMPLE_RATE_HZ = 8_000
+
 
 def calculate_audio_length_ms(format: RealtimeAudioFormat | None, audio_bytes: bytes) -> float:
-    if format and format.startswith("g711"):
-        return (len(audio_bytes) / 8000) * 1000
-    return (len(audio_bytes) / 24 / 2) * 1000
+    if not audio_bytes:
+        return 0.0
+
+    normalized_format = format.lower() if isinstance(format, str) else None
+
+    if normalized_format and normalized_format.startswith("g711"):
+        return (len(audio_bytes) / G711_SAMPLE_RATE_HZ) * 1000
+
+    samples = len(audio_bytes) / PCM16_SAMPLE_WIDTH_BYTES
+    return (samples / PCM16_SAMPLE_RATE_HZ) * 1000

agents/realtime/agent.py

@@ -6,6 +6,8 @@ from collections.abc import Awaitable
 from dataclasses import dataclass, field
 from typing import Any, Callable, Generic, cast
 
+from agents.prompts import Prompt
+
 from ..agent import AgentBase
 from ..guardrail import OutputGuardrail
 from ..handoffs import Handoff
@@ -55,6 +57,11 @@ class RealtimeAgent(AgentBase, Generic[TContext]):
     return a string.
     """
 
+    prompt: Prompt | None = None
+    """A prompt object. Prompts allow you to dynamically configure the instructions, tools
+    and other config for an agent outside of your code. Only usable with OpenAI models.
+    """
+
     handoffs: list[RealtimeAgent[Any] | Handoff[TContext, RealtimeAgent[Any]]] = field(
         default_factory=list
     )

agents/realtime/audio_formats.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Literal
+
+from openai.types.realtime.realtime_audio_formats import (
+    AudioPCM,
+    AudioPCMA,
+    AudioPCMU,
+    RealtimeAudioFormats,
+)
+
+from ..logger import logger
+
+
+def to_realtime_audio_format(
+    input_audio_format: str | RealtimeAudioFormats | Mapping[str, Any] | None,
+) -> RealtimeAudioFormats | None:
+    format: RealtimeAudioFormats | None = None
+    if input_audio_format is not None:
+        if isinstance(input_audio_format, str):
+            if input_audio_format in ["pcm16", "audio/pcm", "pcm"]:
+                format = AudioPCM(type="audio/pcm", rate=24000)
+            elif input_audio_format in ["g711_ulaw", "audio/pcmu", "pcmu"]:
+                format = AudioPCMU(type="audio/pcmu")
+            elif input_audio_format in ["g711_alaw", "audio/pcma", "pcma"]:
+                format = AudioPCMA(type="audio/pcma")
+            else:
+                logger.debug(f"Unknown input_audio_format: {input_audio_format}")
+        elif isinstance(input_audio_format, Mapping):
+            fmt_type = input_audio_format.get("type")
+            rate = input_audio_format.get("rate")
+            if fmt_type == "audio/pcm":
+                pcm_rate: Literal[24000] | None
+                if isinstance(rate, (int, float)) and int(rate) == 24000:
+                    pcm_rate = 24000
+                elif rate is None:
+                    pcm_rate = 24000
+                else:
+                    logger.debug(
+                        f"Unknown pcm rate in input_audio_format mapping: {input_audio_format}"
+                    )
+                    pcm_rate = 24000
+                format = AudioPCM(type="audio/pcm", rate=pcm_rate)
+            elif fmt_type == "audio/pcmu":
+                format = AudioPCMU(type="audio/pcmu")
+            elif fmt_type == "audio/pcma":
+                format = AudioPCMA(type="audio/pcma")
+            else:
+                logger.debug(f"Unknown input_audio_format mapping: {input_audio_format}")
+        else:
+            format = input_audio_format
+    return format