feat: Add warning for providers that don't support toolChoice

Author: zastrowm

src/strands/models/_config_validation.py renamed to src/strands/models/_validation.py

@@ -5,6 +5,8 @@
 
 from typing_extensions import get_type_hints
 
+from ..types.tools import ToolChoice
+
 
 def validate_config_keys(config_dict: Mapping[str, Any], config_class: Type) -> None:
     """Validate that config keys match the TypedDict fields.
@@ -25,3 +27,11 @@ def validate_config_keys(config_dict: Mapping[str, Any], config_class: Type) ->
             f"\nSee https://github.com/strands-agents/sdk-python/issues/815",
             stacklevel=4,
         )
+
+
+def warn_on_tool_choice_not_supported(tool_choice: ToolChoice | None) -> None:
+    if tool_choice:
+        warnings.warn(
+            "A ToolChoice was provided to this provider but is not supported and will be ignored",
+            stacklevel=4,
+        )

src/strands/models/anthropic.py

@@ -19,7 +19,7 @@
 from ..types.exceptions import ContextWindowOverflowException, ModelThrottledException
 from ..types.streaming import StreamEvent
 from ..types.tools import ToolChoice, ToolSpec
-from ._config_validation import validate_config_keys
+from ._validation import validate_config_keys
 from .model import Model
 
 logger = logging.getLogger(__name__)
@@ -199,7 +199,7 @@ def format_request(
         messages: Messages,
         tool_specs: Optional[list[ToolSpec]] = None,
         system_prompt: Optional[str] = None,
-        tool_choice: Optional[ToolChoice] = None,
+        tool_choice: ToolChoice | None = None,
     ) -> dict[str, Any]:
         """Format an Anthropic streaming request.
 
@@ -356,7 +356,7 @@ async def stream(
         messages: Messages,
         tool_specs: Optional[list[ToolSpec]] = None,
         system_prompt: Optional[str] = None,
-        tool_choice: Optional[ToolChoice] = None,
+        tool_choice: ToolChoice | None = None,
         **kwargs: Any,
     ) -> AsyncGenerator[StreamEvent, None]:
         """Stream conversation with the Anthropic model.

src/strands/models/bedrock.py

@@ -24,7 +24,7 @@
 )
 from ..types.streaming import CitationsDelta, StreamEvent
 from ..types.tools import ToolChoice, ToolResult, ToolSpec
-from ._config_validation import validate_config_keys
+from ._validation import validate_config_keys
 from .model import Model
 
 logger = logging.getLogger(__name__)
@@ -195,7 +195,7 @@ def format_request(
         messages: Messages,
         tool_specs: Optional[list[ToolSpec]] = None,
         system_prompt: Optional[str] = None,
-        tool_choice: Optional[ToolChoice] = None,
+        tool_choice: ToolChoice | None = None,
     ) -> dict[str, Any]:
         """Format a Bedrock converse stream request.
 
@@ -226,7 +226,7 @@ def format_request(
                                 else []
                             ),
                         ],
-                        **({"toolChoice": tool_choice} if tool_choice else {}),
+                        **({"toolChoice": tool_choice if tool_choice else {"auto": {}}}),
                     }
                 }
                 if tool_specs
@@ -418,7 +418,7 @@ async def stream(
         messages: Messages,
         tool_specs: Optional[list[ToolSpec]] = None,
         system_prompt: Optional[str] = None,
-        tool_choice: Optional[ToolChoice] = None,
+        tool_choice: ToolChoice | None = None,
         **kwargs: Any,
     ) -> AsyncGenerator[StreamEvent, None]:
         """Stream conversation with the Bedrock model.
@@ -467,7 +467,7 @@ def _stream(
         messages: Messages,
         tool_specs: Optional[list[ToolSpec]] = None,
         system_prompt: Optional[str] = None,
-        tool_choice: Optional[ToolChoice] = None,
+        tool_choice: ToolChoice | None = None,
     ) -> None:
         """Stream conversation with the Bedrock model.
 

src/strands/models/litellm.py

@@ -15,7 +15,7 @@
 from ..types.content import ContentBlock, Messages
 from ..types.streaming import StreamEvent
 from ..types.tools import ToolChoice, ToolSpec
-from ._config_validation import validate_config_keys
+from ._validation import validate_config_keys
 from .openai import OpenAIModel
 
 logger = logging.getLogger(__name__)
@@ -114,7 +114,7 @@ async def stream(
         messages: Messages,
         tool_specs: Optional[list[ToolSpec]] = None,
         system_prompt: Optional[str] = None,
-        tool_choice: Optional[ToolChoice] = None,
+        tool_choice: ToolChoice | None = None,
         **kwargs: Any,
     ) -> AsyncGenerator[StreamEvent, None]:
         """Stream conversation with the LiteLLM model.
@@ -123,15 +123,14 @@ async def stream(
             messages: List of message objects to be processed by the model.
             tool_specs: List of tool specifications to make available to the model.
             system_prompt: System prompt to provide context to the model.
-            tool_choice: Selection strategy for tool invocation. **Note: This parameter is accepted for
-                interface consistency but is currently ignored for this model provider.**
+            tool_choice: Selection strategy for tool invocation.
             **kwargs: Additional keyword arguments for future extensibility.
 
         Yields:
             Formatted message chunks from the model.
         """
         logger.debug("formatting request")
-        request = self.format_request(messages, tool_specs, system_prompt)
+        request = self.format_request(messages, tool_specs, system_prompt, tool_choice)
         logger.debug("request=<%s>", request)
 
         logger.debug("invoking model")

src/strands/models/llamaapi.py

@@ -19,7 +19,7 @@
 from ..types.exceptions import ModelThrottledException
 from ..types.streaming import StreamEvent, Usage
 from ..types.tools import ToolChoice, ToolResult, ToolSpec, ToolUse
-from ._config_validation import validate_config_keys
+from ._validation import validate_config_keys, warn_on_tool_choice_not_supported
 from .model import Model
 
 logger = logging.getLogger(__name__)
@@ -330,7 +330,7 @@ async def stream(
         messages: Messages,
         tool_specs: Optional[list[ToolSpec]] = None,
         system_prompt: Optional[str] = None,
-        tool_choice: Optional[ToolChoice] = None,
+        tool_choice: ToolChoice | None = None,
         **kwargs: Any,
     ) -> AsyncGenerator[StreamEvent, None]:
         """Stream conversation with the LlamaAPI model.
@@ -349,6 +349,8 @@ async def stream(
         Raises:
             ModelThrottledException: When the model service is throttling requests from the client.
         """
+        warn_on_tool_choice_not_supported(tool_choice)
+
         logger.debug("formatting request")
         request = self.format_request(messages, tool_specs, system_prompt)
         logger.debug("request=<%s>", request)

src/strands/models/mistral.py

@@ -16,7 +16,7 @@
 from ..types.exceptions import ModelThrottledException
 from ..types.streaming import StopReason, StreamEvent
 from ..types.tools import ToolChoice, ToolResult, ToolSpec, ToolUse
-from ._config_validation import validate_config_keys
+from ._validation import validate_config_keys, warn_on_tool_choice_not_supported
 from .model import Model
 
 logger = logging.getLogger(__name__)
@@ -397,7 +397,7 @@ async def stream(
         messages: Messages,
         tool_specs: Optional[list[ToolSpec]] = None,
         system_prompt: Optional[str] = None,
-        tool_choice: Optional[ToolChoice] = None,
+        tool_choice: ToolChoice | None = None,
         **kwargs: Any,
     ) -> AsyncGenerator[StreamEvent, None]:
         """Stream conversation with the Mistral model.
@@ -416,6 +416,8 @@ async def stream(
         Raises:
             ModelThrottledException: When the model service is throttling requests.
         """
+        warn_on_tool_choice_not_supported(tool_choice)
+
         logger.debug("formatting request")
         request = self.format_request(messages, tool_specs, system_prompt)
         logger.debug("request=<%s>", request)

src/strands/models/model.py

@@ -70,7 +70,7 @@ def stream(
         messages: Messages,
         tool_specs: Optional[list[ToolSpec]] = None,
         system_prompt: Optional[str] = None,
-        tool_choice: Optional[ToolChoice] = None,
+        tool_choice: ToolChoice | None = None,
         **kwargs: Any,
     ) -> AsyncIterable[StreamEvent]:
         """Stream conversation with the model.

src/strands/models/ollama.py

@@ -14,7 +14,7 @@
 from ..types.content import ContentBlock, Messages
 from ..types.streaming import StopReason, StreamEvent
 from ..types.tools import ToolChoice, ToolSpec
-from ._config_validation import validate_config_keys
+from ._validation import validate_config_keys, warn_on_tool_choice_not_supported
 from .model import Model
 
 logger = logging.getLogger(__name__)
@@ -287,7 +287,7 @@ async def stream(
         messages: Messages,
         tool_specs: Optional[list[ToolSpec]] = None,
         system_prompt: Optional[str] = None,
-        tool_choice: Optional[ToolChoice] = None,
+        tool_choice: ToolChoice | None = None,
         **kwargs: Any,
     ) -> AsyncGenerator[StreamEvent, None]:
         """Stream conversation with the Ollama model.
@@ -303,6 +303,8 @@ async def stream(
         Yields:
             Formatted message chunks from the model.
         """
+        warn_on_tool_choice_not_supported(tool_choice)
+
         logger.debug("formatting request")
         request = self.format_request(messages, tool_specs, system_prompt)
         logger.debug("request=<%s>", request)

src/strands/models/openai.py

@@ -17,7 +17,7 @@
 from ..types.content import ContentBlock, Messages
 from ..types.streaming import StreamEvent
 from ..types.tools import ToolChoice, ToolResult, ToolSpec, ToolUse
-from ._config_validation import validate_config_keys
+from ._validation import validate_config_keys
 from .model import Model
 
 logger = logging.getLogger(__name__)
@@ -175,7 +175,7 @@ def format_request_tool_message(cls, tool_result: ToolResult) -> dict[str, Any]:
         }
 
     @classmethod
-    def format_request_tool_choice(cls, tool_choice: ToolChoice) -> Union[str, dict[str, Any]]:
+    def _format_request_tool_choice(cls, tool_choice: ToolChoice | None) -> dict[str, Any]:
         """Format a tool choice for OpenAI compatibility.
 
         Args:
@@ -184,16 +184,19 @@ def format_request_tool_choice(cls, tool_choice: ToolChoice) -> Union[str, dict[
         Returns:
             OpenAI compatible tool choice format.
         """
+        if not tool_choice:
+            return {}
+
         match tool_choice:
             case {"auto": _}:
-                return "auto"  # OpenAI SDK doesn't define constants for these values
+                return {"tool_choice": "auto"}  # OpenAI SDK doesn't define constants for these values
             case {"any": _}:
-                return "required"
+                return {"tool_choice": "required"}
             case {"tool": {"name": tool_name}}:
-                return {"type": "function", "function": {"name": tool_name}}
+                return {"tool_choice": {"type": "function", "function": {"name": tool_name}}}
             case _:
                 # This should not happen with proper typing, but handle gracefully
-                return "auto"
+                return {"tool_choice": "auto"}
 
     @classmethod
     def format_request_messages(cls, messages: Messages, system_prompt: Optional[str] = None) -> list[dict[str, Any]]:
@@ -241,7 +244,7 @@ def format_request(
         messages: Messages,
         tool_specs: Optional[list[ToolSpec]] = None,
         system_prompt: Optional[str] = None,
-        tool_choice: Optional[ToolChoice] = None,
+        tool_choice: ToolChoice | None = None,
     ) -> dict[str, Any]:
         """Format an OpenAI compatible chat streaming request.
 
@@ -274,7 +277,7 @@ def format_request(
                 }
                 for tool_spec in tool_specs or []
             ],
-            **({"tool_choice": self.format_request_tool_choice(tool_choice)} if tool_choice else {}),
+            **(self._format_request_tool_choice(tool_choice)),
             **cast(dict[str, Any], self.config.get("params", {})),
         }
 
@@ -356,7 +359,7 @@ async def stream(
         messages: Messages,
         tool_specs: Optional[list[ToolSpec]] = None,
         system_prompt: Optional[str] = None,
-        tool_choice: Optional[ToolChoice] = None,
+        tool_choice: ToolChoice | None = None,
         **kwargs: Any,
     ) -> AsyncGenerator[StreamEvent, None]:
         """Stream conversation with the OpenAI model.

src/strands/models/sagemaker.py

@@ -15,7 +15,7 @@
 from ..types.content import ContentBlock, Messages
 from ..types.streaming import StreamEvent
 from ..types.tools import ToolChoice, ToolResult, ToolSpec
-from ._config_validation import validate_config_keys
+from ._validation import validate_config_keys, warn_on_tool_choice_not_supported
 from .openai import OpenAIModel
 
 T = TypeVar("T", bound=BaseModel)
@@ -201,7 +201,7 @@ def format_request(
         messages: Messages,
         tool_specs: Optional[list[ToolSpec]] = None,
         system_prompt: Optional[str] = None,
-        tool_choice: Optional[ToolChoice] = None,
+        tool_choice: ToolChoice | None = None,
     ) -> dict[str, Any]:
         """Format an Amazon SageMaker chat streaming request.
 
@@ -292,7 +292,7 @@ async def stream(
         messages: Messages,
         tool_specs: Optional[list[ToolSpec]] = None,
         system_prompt: Optional[str] = None,
-        tool_choice: Optional[ToolChoice] = None,
+        tool_choice: ToolChoice | None = None,
         **kwargs: Any,
     ) -> AsyncGenerator[StreamEvent, None]:
         """Stream conversation with the SageMaker model.
@@ -308,11 +308,14 @@ async def stream(
         Yields:
             Formatted message chunks from the model.
         """
+        warn_on_tool_choice_not_supported(tool_choice)
+
         logger.debug("formatting request")
         request = self.format_request(messages, tool_specs, system_prompt)
         logger.debug("formatted request=<%s>", request)
 
         logger.debug("invoking model")
+
         try:
             if self.payload_config.get("stream", True):
                 response = self.client.invoke_endpoint_with_response_stream(**request)