fix: include handoffs when deciding to inject JSON

 prompt

The JSON prompt injection was only triggered when tools list was non-empty,
but handoffs are converted to function tools and added separately. This meant
that agents using only handoffs with output_schema would not get the prompt
injection even when enable_structured_output_with_tools=True, causing Gemini
to error with 'Function calling with response mime type application/json is
unsupported.'

Changes:
- Combine tools and handoffs before checking if JSON prompt should be injected
- Add test case for handoffs-only scenario
- Update inline comment to clarify why handoffs must be included

This ensures the opt-in flag works correctly for multi-agent scenarios where
an agent might use handoffs without regular tools.

Author: devv-shayan

src/agents/extensions/models/litellm_model.py

@@ -292,8 +292,12 @@ async def _fetch_response(
 
         # Check if we need to inject JSON output prompt for models that don't support
         # tools + structured output simultaneously (like Gemini)
+        # Note: handoffs are converted to function tools, so we need to include them in the check
+        tools_and_handoffs = list(tools) if tools else []
+        if handoffs:
+            tools_and_handoffs.extend(handoffs)
         inject_json_prompt = should_inject_json_prompt(
-            output_schema, tools, self.enable_structured_output_with_tools
+            output_schema, tools_and_handoffs, self.enable_structured_output_with_tools
         )
         if inject_json_prompt and output_schema:
             json_prompt = get_json_output_prompt(output_schema)

src/agents/models/interface.py

@@ -1,125 +1,125 @@
-from __future__ import annotations
-
-import abc
-import enum
-from collections.abc import AsyncIterator
-from typing import TYPE_CHECKING
-
-from openai.types.responses.response_prompt_param import ResponsePromptParam
-
-from ..agent_output import AgentOutputSchemaBase
-from ..handoffs import Handoff
-from ..items import ModelResponse, TResponseInputItem, TResponseStreamEvent
-from ..tool import Tool
-
-if TYPE_CHECKING:
-    from ..model_settings import ModelSettings
-
-
-class ModelTracing(enum.Enum):
-    DISABLED = 0
-    """Tracing is disabled entirely."""
-
-    ENABLED = 1
-    """Tracing is enabled, and all data is included."""
-
-    ENABLED_WITHOUT_DATA = 2
-    """Tracing is enabled, but inputs/outputs are not included."""
-
-    def is_disabled(self) -> bool:
-        return self == ModelTracing.DISABLED
-
-    def include_data(self) -> bool:
-        return self == ModelTracing.ENABLED
-
-
-class Model(abc.ABC):
-    """The base interface for calling an LLM."""
-
-    @abc.abstractmethod
-    async def get_response(
-        self,
-        system_instructions: str | None,
-        input: str | list[TResponseInputItem],
-        model_settings: ModelSettings,
-        tools: list[Tool],
-        output_schema: AgentOutputSchemaBase | None,
-        handoffs: list[Handoff],
-        tracing: ModelTracing,
-        *,
-        previous_response_id: str | None,
-        conversation_id: str | None,
-        prompt: ResponsePromptParam | None,
-    ) -> ModelResponse:
-        """Get a response from the model.
-
-        Args:
-            system_instructions: The system instructions to use.
-            input: The input items to the model, in OpenAI Responses format.
-            model_settings: The model settings to use.
-            tools: The tools available to the model.
-            output_schema: The output schema to use.
-            handoffs: The handoffs available to the model.
-            tracing: Tracing configuration.
-            previous_response_id: the ID of the previous response. Generally not used by the model,
-                except for the OpenAI Responses API.
-            conversation_id: The ID of the stored conversation, if any.
-            prompt: The prompt config to use for the model.
-
-        Returns:
-            The full model response.
-        """
-        pass
-
-    @abc.abstractmethod
-    def stream_response(
-        self,
-        system_instructions: str | None,
-        input: str | list[TResponseInputItem],
-        model_settings: ModelSettings,
-        tools: list[Tool],
-        output_schema: AgentOutputSchemaBase | None,
-        handoffs: list[Handoff],
-        tracing: ModelTracing,
-        *,
-        previous_response_id: str | None,
-        conversation_id: str | None,
-        prompt: ResponsePromptParam | None,
-    ) -> AsyncIterator[TResponseStreamEvent]:
-        """Stream a response from the model.
-
-        Args:
-            system_instructions: The system instructions to use.
-            input: The input items to the model, in OpenAI Responses format.
-            model_settings: The model settings to use.
-            tools: The tools available to the model.
-            output_schema: The output schema to use.
-            handoffs: The handoffs available to the model.
-            tracing: Tracing configuration.
-            previous_response_id: the ID of the previous response. Generally not used by the model,
-                except for the OpenAI Responses API.
-            conversation_id: The ID of the stored conversation, if any.
-            prompt: The prompt config to use for the model.
-
-        Returns:
-            An iterator of response stream events, in OpenAI Responses format.
-        """
-        pass
-
-
-class ModelProvider(abc.ABC):
-    """The base interface for a model provider.
-
-    Model provider is responsible for looking up Models by name.
-    """
-
-    @abc.abstractmethod
-    def get_model(self, model_name: str | None) -> Model:
-        """Get a model by name.
-
-        Args:
-            model_name: The name of the model to get.
-
-        Returns:
-            The model.
-        """
+from __future__ import annotations
+
+import abc
+import enum
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING
+
+from openai.types.responses.response_prompt_param import ResponsePromptParam
+
+from ..agent_output import AgentOutputSchemaBase
+from ..handoffs import Handoff
+from ..items import ModelResponse, TResponseInputItem, TResponseStreamEvent
+from ..tool import Tool
+
+if TYPE_CHECKING:
+    from ..model_settings import ModelSettings
+
+
+class ModelTracing(enum.Enum):
+    DISABLED = 0
+    """Tracing is disabled entirely."""
+
+    ENABLED = 1
+    """Tracing is enabled, and all data is included."""
+
+    ENABLED_WITHOUT_DATA = 2
+    """Tracing is enabled, but inputs/outputs are not included."""
+
+    def is_disabled(self) -> bool:
+        return self == ModelTracing.DISABLED
+
+    def include_data(self) -> bool:
+        return self == ModelTracing.ENABLED
+
+
+class Model(abc.ABC):
+    """The base interface for calling an LLM."""
+
+    @abc.abstractmethod
+    async def get_response(
+        self,
+        system_instructions: str | None,
+        input: str | list[TResponseInputItem],
+        model_settings: ModelSettings,
+        tools: list[Tool],
+        output_schema: AgentOutputSchemaBase | None,
+        handoffs: list[Handoff],
+        tracing: ModelTracing,
+        *,
+        previous_response_id: str | None,
+        conversation_id: str | None,
+        prompt: ResponsePromptParam | None,
+    ) -> ModelResponse:
+        """Get a response from the model.
+
+        Args:
+            system_instructions: The system instructions to use.
+            input: The input items to the model, in OpenAI Responses format.
+            model_settings: The model settings to use.
+            tools: The tools available to the model.
+            output_schema: The output schema to use.
+            handoffs: The handoffs available to the model.
+            tracing: Tracing configuration.
+            previous_response_id: the ID of the previous response. Generally not used by the model,
+                except for the OpenAI Responses API.
+            conversation_id: The ID of the stored conversation, if any.
+            prompt: The prompt config to use for the model.
+
+        Returns:
+            The full model response.
+        """
+        pass
+
+    @abc.abstractmethod
+    def stream_response(
+        self,
+        system_instructions: str | None,
+        input: str | list[TResponseInputItem],
+        model_settings: ModelSettings,
+        tools: list[Tool],
+        output_schema: AgentOutputSchemaBase | None,
+        handoffs: list[Handoff],
+        tracing: ModelTracing,
+        *,
+        previous_response_id: str | None,
+        conversation_id: str | None,
+        prompt: ResponsePromptParam | None,
+    ) -> AsyncIterator[TResponseStreamEvent]:
+        """Stream a response from the model.
+
+        Args:
+            system_instructions: The system instructions to use.
+            input: The input items to the model, in OpenAI Responses format.
+            model_settings: The model settings to use.
+            tools: The tools available to the model.
+            output_schema: The output schema to use.
+            handoffs: The handoffs available to the model.
+            tracing: Tracing configuration.
+            previous_response_id: the ID of the previous response. Generally not used by the model,
+                except for the OpenAI Responses API.
+            conversation_id: The ID of the stored conversation, if any.
+            prompt: The prompt config to use for the model.
+
+        Returns:
+            An iterator of response stream events, in OpenAI Responses format.
+        """
+        pass
+
+
+class ModelProvider(abc.ABC):
+    """The base interface for a model provider.
+
+    Model provider is responsible for looking up Models by name.
+    """
+
+    @abc.abstractmethod
+    def get_model(self, model_name: str | None) -> Model:
+        """Get a model by name.
+
+        Args:
+            model_name: The name of the model to get.
+
+        Returns:
+            The model.
+        """