Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
factor(tool): refactor the `tool_choice` argument to support advanced prompt cache in OpenAI response API (#1524)
qbc03e7c7c30f3d
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.pyindex 40ccd4e0d..7681c6ad2 100644--- a/src/agentscope/agent/_agent.py+++ b/src/agentscope/agent/_agent.py@@ -3,6 +3,7 @@import asyncioimport inspectimport uuid+from asyncio import Queuefrom copy import deepcopyfrom typing import (@@ -559,7 +560,7 @@ class Agent:async def _reasoning(self,- tool_choice: ToolChoice = "auto",+ tool_choice: ToolChoice | None = None,) -> AsyncGenerator[ModelCallStartEvent| TextBlockStartEvent@@ -613,7 +614,7 @@ class Agent:async def _reasoning_impl(self,- tool_choice: ToolChoice = "auto",+ tool_choice: ToolChoice | None = None,) -> AsyncGenerator[ModelCallStartEvent| TextBlockStartEvent@@ -1781,7 +1782,7 @@ class Agent:self,messages: list[Msg],tools: list[dict],- tool_choice: ToolChoice,+ tool_choice: ToolChoice | None = None,) -> ChatResponse | AsyncGenerator[ChatResponse, None]:"""Perform model inference with retry logic and middleware support.@@ -1790,7 +1791,7 @@ class Agent:The input messages to the model.tools (`list[dict]`):The function schemas of the tools.- tool_choice (`ToolChoice`):+ tool_choice (`ToolChoice | None`, optional):The tool choice strategy for the model call.Returns:diff --git a/src/agentscope/middleware/_base.py b/src/agentscope/middleware/_base.pyindex 88414e90d..884938e3e 100644--- a/src/agentscope/middleware/_base.py+++ b/src/agentscope/middleware/_base.py@@ -95,7 +95,7 @@ class MiddlewareBase:Args:agent: The Agent instance executing this middlewareinput_kwargs: Dictionary containing:- - tool_choice: ToolChoice (default "auto")+ - tool_choice: ToolChoice (default None)next_handler: Callable that executes the next middleware ororiginal methoddiff --git a/src/agentscope/model/_anthropic/_model.py b/src/agentscope/model/_anthropic/_model.pyindex 830d8f0cf..b92848858 100644--- a/src/agentscope/model/_anthropic/_model.py+++ b/src/agentscope/model/_anthropic/_model.py@@ -6,7 +6,7 @@ from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, Listfrom pydantic import BaseModel, Field-from .._base import ChatModelBase+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODESfrom .._model_response import ChatResponsefrom .._model_usage import ChatUsagefrom ...credential import AnthropicCredential@@ -160,14 +160,11 @@ class AnthropicChatModel(ChatModelBase):"budget_tokens": budget,}- if tools:- kwargs["tools"] = self._format_tools_json_schemas(tools)-- if tool_choice:- kwargs["tool_choice"] = self._format_tool_choice(- tool_choice,- tools,- )+ fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)+ if fmt_tools:+ kwargs["tools"] = fmt_tools+ if fmt_tool_choice is not None:+ kwargs["tool_choice"] = fmt_tool_choiceformatted_messages = await self.formatter.format(messages)@@ -402,64 +399,73 @@ class AnthropicChatModel(ChatModelBase):_final_kwargs["id"] = response_idyield ChatResponse(**_final_kwargs)- def _format_tools_json_schemas(- self,- schemas: list[dict[str, Any]],- ) -> list[dict[str, Any]]:- """Format the JSON schemas of the tool functions to the format that- Anthropic API expects."""- formatted_schemas = []- for schema in schemas:- assert (- "function" in schema- ), f"Invalid schema: {schema}, expect key 'function'."-- assert "name" in schema["function"], (- f"Invalid schema: {schema}, "- "expect key 'name' in 'function' field."- )-- formatted_schemas.append(- {- "name": schema["function"]["name"],- "description": schema["function"].get("description", ""),- "input_schema": schema["function"].get("parameters", {}),- },- )-- return formatted_schemas-- def _format_tool_choice(+ def _format_tools(self,- tool_choice: ToolChoice | None,tools: list[dict] | None,- ) -> dict | None:- """Format tool_choice parameter for API compatibility.+ tool_choice: ToolChoice | None,+ ) -> tuple[list[dict] | None, dict | None]:+ """Validate and format tools and tool_choice for Anthropic.++ Converts tool schemas to Anthropic's flat format and maps+ tool_choice modes to Anthropic's type-based format. When+ ``tool_choice.tools`` is specified the schemas list is filtered+ to only those tools. When ``tool_choice.mode`` is a specific tool+ name (str) the model is forced to call exactly that tool without+ needing to filter the list, preserving prompt-cache efficiency.Args:- tool_choice (`ToolChoice | None`):- The unified tool choice parameter which can be a mode ("auto",- "none", "required") or a specific function name.- tools (`list[dict] | None`):- The list of available tools, used for validation if- tool_choice is a specific function name.+ tools (`list[dict] | None`, optional):+ The raw tool schemas.+ tool_choice (`ToolChoice | None`, optional):+ The tool choice configuration.Returns:- `dict | None`:- The formatted tool choice configuration dict, or None if- tool_choice is None.+ `tuple[list[dict] | None, dict | None]`:+ A tuple of (formatted_tools, formatted_tool_choice)."""- self._validate_tool_choice(tool_choice, tools)+ if tool_choice and tools:+ self._validate_tool_choice(tool_choice, tools)+ if tool_choice.tools:+ allowed = set(tool_choice.tools)+ tools = [t for t in tools if t["function"]["name"] in allowed]++ fmt_tools = None+ if tools:+ fmt_tools = []+ for schema in tools:+ assert (+ "function" in schema+ ), f"Invalid schema: {schema}, expect key 'function'."+ assert "name" in schema["function"], (+ f"Invalid schema: {schema}, "+ "expect key 'name' in 'function' field."+ )+ fmt_tools.append(+ {+ "name": schema["function"]["name"],+ "description": schema["function"].get(+ "description",+ "",+ ),+ "input_schema": schema["function"].get(+ "parameters",+ {},+ ),+ },+ )++ if not tool_choice:+ return fmt_tools, None- if tool_choice is None:- return None+ mode = tool_choice.mode++ if mode not in _TOOL_CHOICE_LITERAL_MODES:+ # mode is a specific tool name — force call it+ return fmt_tools, {"type": "tool", "name": mode}type_mapping = {"auto": {"type": "auto"},"none": {"type": "none"},"required": {"type": "any"},}- if tool_choice in type_mapping:- return type_mapping[tool_choice]-- return {"type": "tool", "name": tool_choice}+ return fmt_tools, type_mapping[mode]diff --git a/src/agentscope/model/_base.py b/src/agentscope/model/_base.pyindex b0376260e..e00cb81f0 100644--- a/src/agentscope/model/_base.py+++ b/src/agentscope/model/_base.py@@ -27,7 +27,7 @@ from ..message import ()from ..tool import ToolChoice-_TOOL_CHOICE_MODES = ["auto", "none", "required"]+_TOOL_CHOICE_LITERAL_MODES = {"auto", "none", "required"}class ChatModelBase:@@ -213,32 +213,49 @@ class ChatModelBase:Args:tool_choice (`ToolChoice | None`):- Tool choice mode or function name+ Tool choice with ``mode`` and optional ``tools`` fields.tools (`list[dict] | None`):- Available tools list+ Available tools list.Raises:`ValueError`:- If tool_choice is not a valid mode or function name.+ If mode or tool names are invalid."""if tool_choice is None:return- if not isinstance(tool_choice, str):- raise ValueError(- f"tool_choice must be str, got {type(tool_choice)}",- )- if tool_choice in _TOOL_CHOICE_MODES:- return-- available_functions = [tool["function"]["name"] for tool in tools]+ mode = tool_choice.mode+ available_functions = [+ tool["function"]["name"] for tool in (tools or [])+ ]++ tool_names = tool_choice.tools+ if tool_names is not None:+ for name in tool_names:+ if name not in available_functions:+ raise ValueError(+ f"Invalid tool name '{name}' in tool_choice.tools. "+ f"Available tools: "+ f"{', '.join(sorted(available_functions))}",+ )- if tool_choice not in available_functions:- all_options = _TOOL_CHOICE_MODES + available_functions- raise ValueError(- f"Invalid tool_choice '{tool_choice}'. "- f"Available options: {', '.join(sorted(all_options))}",+ if mode not in _TOOL_CHOICE_LITERAL_MODES:+ # mode is a specific tool name — validate it exists+ # Fall back to all available tools when tool_names is empty or None+ validation_scope = (+ tool_names if tool_names else available_functions)+ if mode not in validation_scope:+ raise ValueError(+ f"Invalid tool name '{mode}' in tool_choice.mode. "+ + (+ f"Available tools in tool_choice.tools: "+ f"{', '.join(sorted(tool_names))}"+ if tool_names is not None+ else f"Available tools: "+ f"{', '.join(sorted(available_functions))}"+ ),+ )async def count_tokens(self,@@ -440,7 +457,9 @@ class ChatModelBase:},},],- tool_choice=func_name,+ tool_choice=ToolChoice(+ mode=func_name,+ ),**kwargs,)diff --git a/src/agentscope/model/_dashscope/_model.py b/src/agentscope/model/_dashscope/_model.pyindex c2398ec51..fef8b3159 100644--- a/src/agentscope/model/_dashscope/_model.py+++ b/src/agentscope/model/_dashscope/_model.py@@ -9,7 +9,7 @@ from typing import Any, AsyncGenerator, Generator, List, Literal, TYPE_CHECKINGfrom pydantic import BaseModel, Fieldfrom aioitertools import iter as giter-from .._base import ChatModelBase+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODESfrom .._model_response import ChatResponsefrom .._model_usage import ChatUsagefrom ...credential import DashScopeCredential@@ -159,10 +159,8 @@ class DashScopeChatModel(ChatModelBase):as the conversation messages.tools (`list[dict] | None`, default `None`):The tools JSON schemas that the model can use.- tool_choice (`Literal["auto", "none", "required"] | str \- | None`, default `None`):+ tool_choice (`ToolChoice | None`, default `None`):Controls which (if any) tool is called by the model.- Can be "auto", "none", "required", or specific tool name.Note: DashScope API only supports "auto" and "none", so"required" will be converted to "auto".For more details, please refer to@@ -191,16 +189,11 @@ class DashScopeChatModel(ChatModelBase):**kwargs,}- # tools- if tools:- kwargs["tools"] = self._format_tools_json_schemas(tools)-- # tool choice options- if tool_choice:- kwargs["tool_choice"] = self._format_tool_choice(- tool_choice,- tools,- )+ fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)+ if fmt_tools is not None:+ kwargs["tools"] = fmt_tools+ if fmt_tool_choice is not None:+ kwargs["tool_choice"] = fmt_tool_choice# thinking related options — map to DashScope API parameter nameskwargs["enable_thinking"] = self.parameters.thinking_enable@@ -497,64 +490,69 @@ class DashScopeChatModel(ChatModelBase):usage=usage,)- @staticmethod- def _format_tools_json_schemas(- schemas: list[dict[str, Any]],- ) -> list[dict[str, Any]]:- """Format the tools JSON schema into required format for DashScope API.-- Args:- schemas (`dict[str, dict[str, Any]]`):- The tools JSON schemas.- """- # Check schemas format- for value in schemas:- if (- not isinstance(value, dict)- or "type" not in value- or value["type"] != "function"- or "function" not in value- ):- raise ValueError(- f"Each schema must be a dict with 'type' as 'function' "- f"and 'function' key, got {value}",- )-- return schemas-- def _format_tool_choice(+ def _format_tools(self,- tool_choice: ToolChoice | None,tools: list[dict] | None,- ) -> str | dict | None:- """Format tool_choice parameter for API compatibility.+ tool_choice: ToolChoice | None,+ ) -> tuple[list[dict] | None, str | dict | None]:+ """Validate and format tools and tool_choice for DashScope.++ DashScope only supports "auto" and "none" modes; "required" is+ converted to "auto" with a warning. When ``tool_choice.tools``+ is specified the schemas list is filtered to only those tools.+ When ``tool_choice.mode`` is a specific tool name (str) the+ model is forced to call exactly that tool without needing to+ filter the list, preserving prompt-cache efficiency.Args:- tool_choice (`ToolChoice | None`):- The unified tool choice parameter which can be a mode ("auto",- "none", "required") or a specific function name.- tools (`list[dict] | None`):- The list of available tools, used for validation if- tool_choice is a specific function name.+ tools (`list[dict] | None`, optional):+ The raw tool schemas.+ tool_choice (`ToolChoice | None`, optional):+ The tool choice configuration.Returns:- `dict | None`:- The formatted tool choice configuration dict, or None if- tool_choice is None.+ `tuple[list[dict] | None, str | dict | None]`:+ A tuple of (formatted_tools, formatted_tool_choice)."""- # Validate the tool_choice value- self._validate_tool_choice(tool_choice, tools)+ if tool_choice and tools:+ self._validate_tool_choice(tool_choice, tools)+ if tool_choice.tools:+ allowed = set(tool_choice.tools)+ tools = [t for t in tools if t["function"]["name"] in allowed]++ fmt_tools = None+ if tools:+ for value in tools:+ if (+ not isinstance(value, dict)+ or "type" not in value+ or value["type"] != "function"+ or "function" not in value+ ):+ raise ValueError(+ f"Each schema must be a dict with 'type' as "+ f"'function' and 'function' key, got {value}",+ )+ fmt_tools = tools++ if not tool_choice:+ return fmt_tools, None++ mode = tool_choice.mode- # DashScope API specific validation and formatting- if tool_choice in ["auto", "none"]:- return tool_choice+ if mode not in _TOOL_CHOICE_LITERAL_MODES:+ # mode is a specific tool name — force call it+ return fmt_tools, {+ "type": "function",+ "function": {"name": mode},+ }- if tool_choice == "required":+ if mode == "required":warnings.warn(- f"'{tool_choice}' is not supported by DashScope API. "+ f"'{mode}' is not supported by DashScope API. ""It will be converted to 'auto'.",DeprecationWarning,)- return "auto"+ return fmt_tools, "auto"- return {"type": "function", "function": {"name": tool_choice}}+ return fmt_tools, modediff --git a/src/agentscope/model/_deepseek/_model.py b/src/agentscope/model/_deepseek/_model.pyindex 52a247671..284ce0995 100644--- a/src/agentscope/model/_deepseek/_model.py+++ b/src/agentscope/model/_deepseek/_model.py@@ -6,7 +6,7 @@ from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, Listfrom pydantic import BaseModel, Field-from .._base import ChatModelBase+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODESfrom .._model_response import ChatResponsefrom .._model_usage import ChatUsagefrom ...credential import DeepSeekCredential@@ -162,14 +162,13 @@ class DeepSeekChatModel(ChatModelBase):kwargs.update(generate_kwargs)- if tools:- kwargs["tools"] = tools+ fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)- if tool_choice:- kwargs["tool_choice"] = self._format_tool_choice(- tool_choice,- tools,- )+ if fmt_tools:+ kwargs["tools"] = fmt_tools++ if fmt_tool_choice is not None:+ kwargs["tool_choice"] = fmt_tool_choiceif self.stream:kwargs["stream_options"] = {"include_usage": True}@@ -353,32 +352,41 @@ class DeepSeekChatModel(ChatModelBase):return ChatResponse(**resp_kwargs)- def _format_tool_choice(+ def _format_tools(self,- tool_choice: ToolChoice | None,tools: list[dict] | None,- ) -> str | dict | None:- """Format tool_choice parameter for the DeepSeek API.+ tool_choice: ToolChoice | None,+ ) -> tuple[list[dict] | None, str | dict | None]:+ """Validate, filter, and format tools and tool_choice for the DeepSeek+ API.++ When ``tool_choice.tools`` is specified the schemas list is filtered+ to only those tools. When ``tool_choice.mode`` is a specific tool name+ (str) the model is forced to call exactly that tool without needing to+ filter the list, preserving prompt-cache efficiency.Args:- tool_choice (`ToolChoice | None`):- The unified tool choice parameter which can be ``"auto"``,- ``"none"``, ``"required"``, or a specific function name.- tools (`list[dict] | None`):- The list of available tools, used for validation when- ``tool_choice`` is a specific function name.+ tools (`list[dict] | None`, optional):+ The raw tool schemas.+ tool_choice (`ToolChoice | None`, optional):+ The tool choice configuration.Returns:- `str | dict | None`:- The formatted tool choice string or configuration dict for- the DeepSeek API, or ``None`` if ``tool_choice`` is ``None``.+ `tuple[list[dict] | None, str | dict | None]`:+ A tuple of (formatted_tools, formatted_tool_choice)."""- self._validate_tool_choice(tool_choice, tools)+ if tool_choice and tools:+ self._validate_tool_choice(tool_choice, tools)+ if tool_choice.tools:+ allowed = set(tool_choice.tools)+ tools = [t for t in tools if t["function"]["name"] in allowed]++ if not tool_choice:+ return tools, None- if tool_choice is None:- return None+ mode = tool_choice.mode- if tool_choice in ["auto", "none", "required"]:- return tool_choice+ if mode not in _TOOL_CHOICE_LITERAL_MODES:+ return tools, {"type": "function", "function": {"name": mode}}- return {"type": "function", "function": {"name": tool_choice}}+ return tools, modediff --git a/src/agentscope/model/_gemini/_model.py b/src/agentscope/model/_gemini/_model.pyindex e96f6c612..cb9fa9713 100644--- a/src/agentscope/model/_gemini/_model.py+++ b/src/agentscope/model/_gemini/_model.py@@ -9,7 +9,7 @@ from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, Listfrom pydantic import BaseModel, Field-from .._base import ChatModelBase+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODESfrom .._model_response import ChatResponsefrom .._model_usage import ChatUsagefrom ...credential import GeminiCredential@@ -218,14 +218,13 @@ class GeminiChatModel(ChatModelBase):"thinking_budget": self.parameters.thinking_budget or 1024,}- if tools:- config["tools"] = self._format_tools_json_schemas(tools)+ fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)- if tool_choice:- config["tool_config"] = self._format_tool_choice(- tool_choice,- tools,- )+ if fmt_tools is not None:+ config["tools"] = fmt_tools++ if fmt_tool_choice is not None:+ config["tool_config"] = fmt_tool_choicekwargs: dict[str, Any] = {"model": model_name,@@ -454,69 +453,73 @@ class GeminiChatModel(ChatModelBase):)return None- def _format_tools_json_schemas(+ def _format_tools(self,- schemas: list[dict[str, Any]],- ) -> list[dict[str, Any]]:- """Format tool schemas for the Gemini API.+ tools: list[dict] | None,+ tool_choice: ToolChoice | None,+ ) -> tuple[list[dict] | None, dict | None]:+ """Validate and format tools and tool_choice for Gemini.++ Converts tool schemas to Gemini's ``function_declarations``+ format (resolving ``$ref`` references) and maps tool_choice+ modes to Gemini's ``function_calling_config``. When+ ``tool_choice.tools`` is specified the schemas list is filtered+ to only those tools. When ``tool_choice.mode`` is a specific+ tool name (str) the model is restricted via+ ``allowed_function_names`` without needing to filter the list,+ preserving prompt-cache efficiency.Args:- schemas (`list[dict[str, Any]]`):- The raw tool JSON schemas in the standard ``{"function": ...}``- format.+ tools (`list[dict] | None`, optional):+ The raw tool schemas.+ tool_choice (`ToolChoice | None`, optional):+ The tool choice configuration.Returns:- `list[dict[str, Any]]`:- A list containing a single dict with- ``"function_declarations"`` key, as required by the Gemini- API.+ `tuple[list[dict] | None, dict | None]`:+ A tuple of (formatted_tools, formatted_tool_config)."""- function_declarations = []- for schema in schemas:- if "function" not in schema:- continue- func = schema["function"].copy()- if "parameters" in func:- func["parameters"] = _flatten_json_schema(func["parameters"])- function_declarations.append(func)- return [{"function_declarations": function_declarations}]-- def _format_tool_choice(- self,- tool_choice: ToolChoice | None,- tools: list[dict] | None,- ) -> dict | None:- """Format tool_choice parameter for the Gemini API.+ if tool_choice and tools:+ self._validate_tool_choice(tool_choice, tools)+ if tool_choice.tools:+ allowed = set(tool_choice.tools)+ tools = [t for t in tools if t["function"]["name"] in allowed]- Args:- tool_choice (`ToolChoice | None`):- The unified tool choice parameter which can be ``"auto"``,- ``"none"``, ``"required"``, or a specific function name.- tools (`list[dict] | None`):- The list of available tools, used for validation when- ``tool_choice`` is a specific function name.+ fmt_tools = None+ if tools:+ function_declarations = []+ for schema in tools:+ if "function" not in schema:+ continue+ func = schema["function"].copy()+ if "parameters" in func:+ func["parameters"] = _flatten_json_schema(+ func["parameters"],+ )+ function_declarations.append(func)+ fmt_tools = [{"function_declarations": function_declarations}]- Returns:- `dict | None`:- The formatted ``tool_config`` dict for the Gemini API, or- ``None`` if ``tool_choice`` is ``None``.- """- self._validate_tool_choice(tool_choice, tools)+ if not tool_choice:+ return fmt_tools, None- if tool_choice is None:- return None+ mode = tool_choice.mode++ if mode not in _TOOL_CHOICE_LITERAL_MODES:+ # mode is a specific tool name — restrict to that single tool+ fmt_choice: dict = {+ "function_calling_config": {+ "mode": "ANY",+ "allowed_function_names": [mode],+ },+ }+ return fmt_tools, fmt_choicemode_mapping = {"auto": "AUTO","none": "NONE","required": "ANY",}- mode = mode_mapping.get(tool_choice)- if mode:- return {"function_calling_config": {"mode": mode}}- return {- "function_calling_config": {- "mode": "ANY",- "allowed_function_names": [tool_choice],- },+ fmt_choice = {+ "function_calling_config": {"mode": mode_mapping[mode]},}+ return fmt_tools, fmt_choicediff --git a/src/agentscope/model/_kimi/_model.py b/src/agentscope/model/_kimi/_model.pyindex 1d3991a1c..9b97191c4 100644--- a/src/agentscope/model/_kimi/_model.py+++ b/src/agentscope/model/_kimi/_model.py@@ -6,7 +6,7 @@ from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, Listfrom pydantic import BaseModel, Field-from .._base import ChatModelBase+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODESfrom .._model_response import ChatResponsefrom .._model_usage import ChatUsagefrom ...credential import KimiCredential@@ -153,14 +153,13 @@ class KimiChatModel(ChatModelBase):kwargs.update(generate_kwargs)- if tools:- kwargs["tools"] = tools+ fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)- if tool_choice:- kwargs["tool_choice"] = self._format_tool_choice(- tool_choice,- tools,- )+ if fmt_tools:+ kwargs["tools"] = fmt_tools++ if fmt_tool_choice is not None:+ kwargs["tool_choice"] = fmt_tool_choiceif self.stream:kwargs["stream_options"] = {"include_usage": True}@@ -344,32 +343,40 @@ class KimiChatModel(ChatModelBase):return ChatResponse(**resp_kwargs)- def _format_tool_choice(+ def _format_tools(self,- tool_choice: ToolChoice | None,tools: list[dict] | None,- ) -> str | dict | None:- """Format tool_choice parameter for the Kimi API.+ tool_choice: ToolChoice | None,+ ) -> tuple[list[dict] | None, str | dict | None]:+ """Validate, filter, and format tools and tool_choice for the Kimi API.++ When ``tool_choice.tools`` is specified the schemas list is filtered+ to only those tools. When ``tool_choice.mode`` is a specific tool name+ (str) the model is forced to call exactly that tool without needing to+ filter the list, preserving prompt-cache efficiency.Args:- tool_choice (`ToolChoice | None`):- The unified tool choice parameter which can be ``"auto"``,- ``"none"``, ``"required"``, or a specific function name.- tools (`list[dict] | None`):- The list of available tools, used for validation when- ``tool_choice`` is a specific function name.+ tools (`list[dict] | None`, optional):+ The raw tool schemas.+ tool_choice (`ToolChoice | None`, optional):+ The tool choice configuration.Returns:- `str | dict | None`:- The formatted tool choice string or configuration dict for- the Kimi API, or ``None`` if ``tool_choice`` is ``None``.+ `tuple[list[dict] | None, str | dict | None]`:+ A tuple of (formatted_tools, formatted_tool_choice)."""- self._validate_tool_choice(tool_choice, tools)+ if tool_choice and tools:+ self._validate_tool_choice(tool_choice, tools)+ if tool_choice.tools:+ allowed = set(tool_choice.tools)+ tools = [t for t in tools if t["function"]["name"] in allowed]++ if not tool_choice:+ return tools, None- if tool_choice is None:- return None+ mode = tool_choice.mode- if tool_choice in ["auto", "none", "required"]:- return tool_choice+ if mode not in _TOOL_CHOICE_LITERAL_MODES:+ return tools, {"type": "function", "function": {"name": mode}}- return {"type": "function", "function": {"name": tool_choice}}+ return tools, modediff --git a/src/agentscope/model/_ollama/_model.py b/src/agentscope/model/_ollama/_model.pyindex bd3dbb43e..8f8344fd5 100644--- a/src/agentscope/model/_ollama/_model.py+++ b/src/agentscope/model/_ollama/_model.py@@ -151,11 +151,10 @@ class OllamaChatModel(ChatModelBase):kwargs.update(generate_kwargs)- if tools:- kwargs["tools"] = tools+ fmt_tools, _ = self._format_tools(tools, tool_choice)- if tool_choice:- logger.warning("Ollama does not support tool_choice yet, ignored.")+ if fmt_tools:+ kwargs["tools"] = fmt_toolsstart_datetime = datetime.now()response = await client.chat(**kwargs)@@ -165,6 +164,43 @@ class OllamaChatModel(ChatModelBase):return await self._parse_completion_response(start_datetime, response)+ def _format_tools(+ self,+ tools: list[dict] | None,+ tool_choice: ToolChoice | None,+ ) -> tuple[list[dict] | None, None]:+ """Validate, filter tools, and warn if tool_choice is set.++ Ollama does not support ``tool_choice`` natively. When+ ``tool_choice.tools`` is specified the schemas list is filtered to+ only those tools. Any ``tool_choice.mode`` value is ignored with a+ warning.++ Args:+ tools (`list[dict] | None`, optional):+ The raw tool schemas.+ tool_choice (`ToolChoice | None`, optional):+ The tool choice configuration.++ Returns:+ `tuple[list[dict] | None, None]`:+ A tuple of (filtered_tools, None) — tool_choice is always+ ``None`` since Ollama does not support it.+ """+ if tool_choice and tools:+ self._validate_tool_choice(tool_choice, tools)+ if tool_choice.tools:+ allowed = set(tool_choice.tools)+ tools = [t for t in tools if t["function"]["name"] in allowed]++ if tool_choice:+ logger.warning(+ "Ollama ignores tool_choice.mode; "+ "tool_choice.tools is still applied to filter tool schemas.",+ )++ return tools, None+async def _parse_stream_response(self,start_datetime: datetime,diff --git a/src/agentscope/model/_openai_chat/_model.py b/src/agentscope/model/_openai_chat/_model.pyindex 3bcf4709d..d44cfafb3 100644--- a/src/agentscope/model/_openai_chat/_model.py+++ b/src/agentscope/model/_openai_chat/_model.py@@ -6,7 +6,7 @@ from typing import Literal, Any, AsyncGenerator, TYPE_CHECKING, Listfrom pydantic import BaseModel, Field-from .._base import ChatModelBase+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODESfrom .._model_response import ChatResponsefrom .._model_usage import ChatUsagefrom ...credential import OpenAICredential@@ -169,16 +169,15 @@ class OpenAIChatModel(ChatModelBase):kwargs.update(generate_kwargs)- if tools:- kwargs["tools"] = tools+ fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)++ if fmt_tools:+ kwargs["tools"] = fmt_toolsif not self.parameters.parallel_tool_calls:kwargs["parallel_tool_calls"] = False- if tool_choice:- kwargs["tool_choice"] = self._format_tool_choice(- tool_choice,- tools,- )+ if fmt_tool_choice is not None:+ kwargs["tool_choice"] = fmt_tool_choiceif self.stream:kwargs["stream_options"] = {"include_usage": True}@@ -363,32 +362,41 @@ class OpenAIChatModel(ChatModelBase):return ChatResponse(**resp_kwargs)- def _format_tool_choice(+ def _format_tools(self,- tool_choice: ToolChoice | None,tools: list[dict] | None,- ) -> str | dict | None:- """Format tool_choice parameter for the OpenAI Chat Completions API.+ tool_choice: ToolChoice | None,+ ) -> tuple[list[dict] | None, str | dict | None]:+ """Validate, filter, and format tools and tool_choice for the OpenAI+ Chat Completions API.++ When ``tool_choice.tools`` is specified the schemas list is filtered+ to only those tools. When ``tool_choice.mode`` is a specific tool name+ (str) the model is forced to call exactly that tool without needing to+ filter the list, preserving prompt-cache efficiency.Args:- tool_choice (`ToolChoice | None`):- The unified tool choice parameter which can be ``"auto"``,- ``"none"``, ``"required"``, or a specific function name.- tools (`list[dict] | None`):- The list of available tools, used for validation when- ``tool_choice`` is a specific function name.+ tools (`list[dict] | None`, optional):+ The raw tool schemas.+ tool_choice (`ToolChoice | None`, optional):+ The tool choice configuration.Returns:- `str | dict | None`:- The formatted tool choice string or configuration dict for- the OpenAI API, or ``None`` if ``tool_choice`` is ``None``.+ `tuple[list[dict] | None, str | dict | None]`:+ A tuple of (formatted_tools, formatted_tool_choice)."""- self._validate_tool_choice(tool_choice, tools)+ if tool_choice and tools:+ self._validate_tool_choice(tool_choice, tools)+ if tool_choice.tools:+ allowed = set(tool_choice.tools)+ tools = [t for t in tools if t["function"]["name"] in allowed]++ if not tool_choice:+ return tools, None- if tool_choice is None:- return None+ mode = tool_choice.mode- if tool_choice in ["auto", "none", "required"]:- return tool_choice+ if mode not in _TOOL_CHOICE_LITERAL_MODES:+ return tools, {"type": "function", "function": {"name": mode}}- return {"type": "function", "function": {"name": tool_choice}}+ return tools, modediff --git a/src/agentscope/model/_openai_response/_model.py b/src/agentscope/model/_openai_response/_model.pyindex d7854a1d1..c6c160b59 100644--- a/src/agentscope/model/_openai_response/_model.py+++ b/src/agentscope/model/_openai_response/_model.py@@ -5,7 +5,7 @@ from typing import Literal, Any, AsyncGenerator, List, TYPE_CHECKINGfrom pydantic import BaseModel, Field-from .._base import ChatModelBase+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODESfrom .._model_response import ChatResponsefrom .._model_usage import ChatUsagefrom ...credential import OpenAICredential@@ -23,8 +23,6 @@ else:ResponseStreamEvent = AnyAsyncStream = Any-_TOOL_CHOICE_LITERAL_MODES = ["auto", "none", "required"]-class OpenAIResponseModel(ChatModelBase):"""The OpenAI Responses API chat model.@@ -405,12 +403,18 @@ class OpenAIResponseModel(ChatModelBase):tools: list[dict] | None,tool_choice: ToolChoice | None,) -> tuple[list[dict] | None, str | dict | None]:- """Format tools and tool_choice for the Responses API.+ """Validate, filter, and format tools and tool_choice for the+ Responses API.++ When ``tool_choice.tools`` is specified the schemas list is filtered+ to only those tools. When ``tool_choice.mode`` is a specific tool name+ (str) the model is forced to call exactly that tool without needing to+ filter the list, preserving prompt-cache efficiency.Args:- tools (`list[dict] | None`):+ tools (`list[dict] | None`, optional):The raw tool schemas.- tool_choice (`ToolChoice | None`):+ tool_choice (`ToolChoice | None`, optional):The tool choice configuration.Returns:@@ -418,7 +422,11 @@ class OpenAIResponseModel(ChatModelBase):A tuple of ``(formatted_tools, formatted_tool_choice)``ready for the Responses API."""- self._validate_tool_choice(tool_choice, tools)+ if tool_choice and tools:+ self._validate_tool_choice(tool_choice, tools)+ if tool_choice.tools:+ allowed = set(tool_choice.tools)+ tools = [t for t in tools if t["function"]["name"] in allowed]fmt_tools = Noneif tools:@@ -429,7 +437,9 @@ class OpenAIResponseModel(ChatModelBase):if not tool_choice:return fmt_tools, None- if tool_choice not in _TOOL_CHOICE_LITERAL_MODES:- return fmt_tools, {"type": "function", "name": tool_choice}+ mode = tool_choice.mode++ if mode not in _TOOL_CHOICE_LITERAL_MODES:+ return fmt_tools, {"type": "function", "name": mode}- return fmt_tools, tool_choice+ return fmt_tools, modediff --git a/src/agentscope/model/_xai/_model.py b/src/agentscope/model/_xai/_model.pyindex 6fc20d234..546316f3c 100644--- a/src/agentscope/model/_xai/_model.py+++ b/src/agentscope/model/_xai/_model.py@@ -5,11 +5,11 @@ from typing import Any, AsyncGenerator, List, Literal, TYPE_CHECKINGfrom pydantic import BaseModel, Field-from .._base import ChatModelBase+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODESfrom .._model_response import ChatResponsefrom .._model_usage import ChatUsagefrom ...credential import XAICredential-from ...formatter._xai_formatter import XAIChatFormatter+from ...formatter import XAIChatFormatterfrom ...message import (TextBlock,ThinkingBlock,@@ -20,11 +20,10 @@ from ...tracing import trace_llmif TYPE_CHECKING:from xai_sdk import AsyncClient- from xai_sdk.chat import Response, Chunk+ from xai_sdk.chat import Responseelse:AsyncClient = AnyResponse = Any- Chunk = Anyclass XAIChatModel(ChatModelBase):@@ -152,22 +151,15 @@ class XAIChatModel(ChatModelBase):generator of ``ChatResponse`` objects when streaming isenabled."""- from xai_sdk import (- AsyncClient as XAIAsyncClient,- ) # pylint: disable=import-outside-toplevel+ from xai_sdk import AsyncClient- client = XAIAsyncClient(+ client = AsyncClient(api_key=self.credential.api_key.get_secret_value(),)xai_messages = await self.formatter.format(messages)- xai_tools = self._convert_tools(tools) if tools else None- xai_tool_choice = (- self._convert_tool_choice(tool_choice, tools)- if tool_choice- else None- )+ xai_tools, xai_tool_choice = self._format_tools(tools, tool_choice)create_kwargs: dict[str, Any] = {"model": model_name}if self.parameters.max_tokens is not None:@@ -203,67 +195,66 @@ class XAIChatModel(ChatModelBase):return self._parse_completion_response(start_datetime, response)- def _convert_tools(self, tools: list[dict]) -> list:- """Convert AgentScope tool schemas to ``xai_sdk`` ``Tool`` protos.-- Args:- tools (`list[dict]`):- A list of tool schemas in OpenAI function-calling format.-- Returns:- `list`:- A list of ``chat_pb2.Tool`` proto objects.- """- from xai_sdk.chat import tool-- xai_tools = []- for t in tools:- if t.get("type") == "function" and "function" in t:- fn = t["function"]- xai_tools.append(- tool(- name=fn["name"],- description=fn.get("description", ""),- parameters=fn.get("parameters", {}),- ),- )- return xai_tools-- def _convert_tool_choice(+ def _format_tools(self,- tool_choice: ToolChoice | None,tools: list[dict] | None,- ) -> Any:- """Convert a ``ToolChoice`` value to an ``xai_sdk`` compatible object.+ tool_choice: ToolChoice | None,+ ) -> tuple[list | None, Any]:+ """Validate, filter, and format tools and tool_choice for the xAI API.++ When ``tool_choice.tools`` is specified the schemas list is filtered+ to only those tools. When ``tool_choice.mode`` is a specific tool name+ (str) the model is forced to call exactly that tool without needing to+ filter the list, preserving prompt-cache efficiency.Args:- tool_choice (`ToolChoice | None`):- The unified tool-choice parameter (``"auto"``, ``"none"``,- ``"required"``, or a specific function name).- tools (`list[dict] | None`):- The list of available tools, used for validation.+ tools (`list[dict] | None`, optional):+ The raw tool schemas.+ tool_choice (`ToolChoice | None`, optional):+ The tool choice configuration.Returns:- `Any`:- The ``xai_sdk``-compatible tool-choice value, or ``None``.+ `tuple[list | None, Any]`:+ A tuple of (xai_tools, xai_tool_choice) ready for the+ ``xai_sdk`` client."""- from xai_sdk.chat import ( # pylint: disable=import-outside-toplevel- required_tool,- )+ from xai_sdk.chat import required_tool, tool++ if tool_choice and tools:+ self._validate_tool_choice(tool_choice, tools)+ if tool_choice.tools:+ allowed = set(tool_choice.tools)+ tools = [t for t in tools if t["function"]["name"] in allowed]++ xai_tools = None+ if tools:+ xai_tools = []+ for t in tools:+ if t.get("type") == "function" and "function" in t:+ fn = t["function"]+ xai_tools.append(+ tool(+ name=fn["name"],+ description=fn.get("description", ""),+ parameters=fn.get("parameters", {}),+ ),+ )++ if not tool_choice:+ return xai_tools, None++ mode = tool_choice.mode- self._validate_tool_choice(tool_choice, tools)+ if mode in _TOOL_CHOICE_LITERAL_MODES:+ return xai_tools, mode- if tool_choice is None:- return None- if tool_choice in ("auto", "none", "required"):- return tool_choice- return required_tool(tool_choice)+ return xai_tools, required_tool(mode)async def _parse_stream_response(self,start_datetime: datetime,chat: Any,- client: Any,+ client: AsyncClient,) -> AsyncGenerator[ChatResponse, None]:"""Parse the xAI streaming response from ``xai_sdk``.@@ -362,7 +353,7 @@ class XAIChatModel(ChatModelBase):def _parse_completion_response(self,start_datetime: datetime,- response: Any,+ response: Response,) -> ChatResponse:"""Parse the xAI non-streaming response from ``xai_sdk``.diff --git a/src/agentscope/tool/_types.py b/src/agentscope/tool/_types.pyindex 07e8e645c..b969e2973 100644--- a/src/agentscope/tool/_types.py+++ b/src/agentscope/tool/_types.py@@ -191,4 +191,29 @@ Function: TypeAlias = ()-ToolChoice: TypeAlias = Literal["auto", "none", "required"] | str+class ToolChoice(BaseModel):+ """The tool choice configuration.++ Attributes:+ mode: The tool choice mode. Supports:++ * ``"auto"`` – the model decides whether to call a tool.+ * ``"none"`` – the model must not call any tool.+ * ``"required"`` – the model must call at least one tool.+ * ``str`` (a tool name) – the model **must** call exactly that+ tool (forced single-tool call). The name is validated against+ ``tools`` (if provided) or against the full tools list passed to+ the model.++ tools: An optional list of tool names. When specified, the tool+ schemas forwarded to the model are filtered to only those tools.+ This also acts as a validation whitelist for ``mode`` when it+ is a specific tool name (str): the name must appear in this+ list. Prefer using ``mode=<tool_name>`` (str) over+ ``tools=["<tool_name>"]`` when the goal is a forced single-tool+ call without changing the available tool set, as the former+ avoids schema-list changes that would invalidate prompt caches.+ """++ mode: Literal["auto", "none", "required"] | str+ tools: list[str] | None = Nonediff --git a/src/agentscope/tracing/_extractor.py b/src/agentscope/tracing/_extractor.pyindex 06179db09..2bf0908b8 100644--- a/src/agentscope/tracing/_extractor.py+++ b/src/agentscope/tracing/_extractor.py@@ -6,6 +6,7 @@ from typing import Any, Dict, Tuple, TYPE_CHECKINGfrom ..embedding import EmbeddingModelBasefrom ..message import Msg, ToolCallBlockfrom ..model import ChatModelBase+from ..tool import ToolChoicefrom ._attributes import (SpanAttributes,@@ -135,7 +136,7 @@ def _get_provider_name(instance: ChatModelBase) -> str:def _get_tool_definitions(tools: list[dict[str, Any]] | None,- tool_choice: str | None,+ tool_choice: ToolChoice | None,) -> str | None:"""Extract and serialize tool definitions for tracing.@@ -146,10 +147,10 @@ def _get_tool_definitions(tools (`list[dict[str, Any]] | None`, optional):List of tool definitions in OpenAI format with nestedstructure: ``[{"type": "function", "function": {...}}]``- tool_choice (`str | None`, optional):- Tool choice mode. Can be "auto", "none", "any", "required",- or a specific tool name. If "none", returns None to indicate- tools should not be traced.+ tool_choice (`ToolChoice | None`, optional):+ Tool choice configuration with ``mode`` and optional ``tools``+ fields. If mode is ``"none"``, returns None to indicate tools+ should not be traced.Returns:`str | None`:@@ -163,7 +164,7 @@ def _get_tool_definitions(return None# Tool choice is explicitly "none" (model should not use tools)- if tool_choice == "none":+ if tool_choice is not None and tool_choice.mode == "none":return Nonetry:diff --git a/tests/model_anthropic_test.py b/tests/model_anthropic_test.pyindex b1b31e2b3..f28064e3d 100644--- a/tests/model_anthropic_test.py+++ b/tests/model_anthropic_test.py@@ -7,12 +7,14 @@ Formatter tests have been moved to tests/formatter_anthropic_test.py.import jsonfrom typing import Anyfrom datetime import datetime+import unittestfrom unittest import IsolatedAsyncioTestCasefrom unittest.mock import MagicMockfrom agentscope.message import TextBlock, ToolCallBlock, ThinkingBlockfrom agentscope.model import AnthropicChatModelfrom agentscope.credential import AnthropicCredential+from agentscope.tool import ToolChoice# ---------------------------------------------------------------------------@@ -129,3 +131,118 @@ class TestAnthropicModelParsing(IsolatedAsyncioTestCase):resp,)self.assertEqual(result.id, "msg-1")+++# ---------------------------------------------------------------------------+# Shared _format_tools fixtures+# ---------------------------------------------------------------------------++_FT_TOOLS = [+ {+ "type": "function",+ "function": {+ "name": "get_weather",+ "description": "Get the weather",+ "parameters": {+ "type": "object",+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ },+ },+ },+ {+ "type": "function",+ "function": {+ "name": "get_time",+ "description": "Get the time",+ "parameters": {+ "type": "object",+ "properties": {"timezone": {"type": "string"}},+ "required": ["timezone"],+ },+ },+ },+]+++_FT_TOOLS_ANTHROPIC = [+ {+ "name": "get_weather",+ "description": "Get the weather",+ "input_schema": {+ "type": "object",+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ },+ },+ {+ "name": "get_time",+ "description": "Get the time",+ "input_schema": {+ "type": "object",+ "properties": {"timezone": {"type": "string"}},+ "required": ["timezone"],+ },+ },+]+++# pylint: disable=protected-access+class TestAnthropicFormatTools(unittest.TestCase):+ """Tests for AnthropicChatModel._format_tools."""++ def setUp(self) -> None:+ """Set up model instance."""+ self.model = _make_model()++ def test_auto_mode(self) -> None:+ """Auto mode returns converted tools and type=auto."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS_ANTHROPIC)+ self.assertEqual(fmt_choice, {"type": "auto"})++ def test_none_mode(self) -> None:+ """None mode returns converted tools and type=none."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="none"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS_ANTHROPIC)+ self.assertEqual(fmt_choice, {"type": "none"})++ def test_required_mode(self) -> None:+ """Required mode maps to type=any."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="required"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS_ANTHROPIC)+ self.assertEqual(fmt_choice, {"type": "any"})++ def test_str_mode_force_call(self) -> None:+ """A specific tool name forces that tool call."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="get_weather"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS_ANTHROPIC)+ self.assertEqual(fmt_choice, {"type": "tool", "name": "get_weather"})++ def test_tools_filtered(self) -> None:+ """When tool_choice.tools is set, only those tools are included."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto", tools=["get_weather"]),+ )+ self.assertEqual(len(fmt_tools), 1)+ self.assertEqual(fmt_tools[0]["name"], "get_weather")+ self.assertEqual(fmt_choice, {"type": "auto"})++ def test_no_tool_choice(self) -> None:+ """Without tool_choice, returns converted tools and None."""+ fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)+ self.assertEqual(fmt_tools, _FT_TOOLS_ANTHROPIC)+ self.assertIsNone(fmt_choice)diff --git a/tests/model_dashscope_test.py b/tests/model_dashscope_test.pyindex d3e4b1e08..f126ce75f 100644--- a/tests/model_dashscope_test.py+++ b/tests/model_dashscope_test.py@@ -8,12 +8,14 @@ import jsonfrom typing import Anyfrom datetime import datetimefrom http import HTTPStatus+import unittestfrom unittest import IsolatedAsyncioTestCasefrom unittest.mock import MagicMockfrom agentscope.message import TextBlock, ToolCallBlockfrom agentscope.model import DashScopeChatModelfrom agentscope.credential import DashScopeCredential+from agentscope.tool import ToolChoice# ---------------------------------------------------------------------------@@ -115,3 +117,99 @@ class TestDashScopeModelParsing(IsolatedAsyncioTestCase):self.start,resp,)+++# ---------------------------------------------------------------------------+# Shared _format_tools fixtures+# ---------------------------------------------------------------------------++_FT_TOOLS = [+ {+ "type": "function",+ "function": {+ "name": "get_weather",+ "description": "Get the weather",+ "parameters": {+ "type": "object",+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ },+ },+ },+ {+ "type": "function",+ "function": {+ "name": "get_time",+ "description": "Get the time",+ "parameters": {+ "type": "object",+ "properties": {"timezone": {"type": "string"}},+ "required": ["timezone"],+ },+ },+ },+]+++class TestDashScopeFormatTools(unittest.TestCase):+ """Tests for DashScopeChatModel._format_tools."""++ def setUp(self) -> None:+ """Set up model instance."""+ self.model = _make_model()++ def test_auto_mode(self) -> None:+ """Auto mode returns tools unchanged and string 'auto'."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertEqual(fmt_choice, "auto")++ def test_none_mode(self) -> None:+ """None mode returns tools unchanged and string 'none'."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="none"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertEqual(fmt_choice, "none")++ def test_required_mode_warns(self) -> None:+ """Required mode emits a DeprecationWarning and falls back to auto."""+ with self.assertWarns(DeprecationWarning):+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="required"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertEqual(fmt_choice, "auto")++ def test_str_mode_force_call(self) -> None:+ """A specific tool name forces that tool call."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="get_weather"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertEqual(+ fmt_choice,+ {"type": "function", "function": {"name": "get_weather"}},+ )++ def test_tools_filtered(self) -> None:+ """When tool_choice.tools is set, only those tools are included."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto", tools=["get_weather"]),+ )+ self.assertEqual(len(fmt_tools), 1)+ self.assertEqual(fmt_tools[0]["function"]["name"], "get_weather")+ self.assertEqual(fmt_choice, "auto")++ def test_no_tool_choice(self) -> None:+ """Without tool_choice, returns tools and None."""+ fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertIsNone(fmt_choice)diff --git a/tests/model_deepseek_test.py b/tests/model_deepseek_test.pyindex f775e72b0..cec1fb221 100644--- a/tests/model_deepseek_test.py+++ b/tests/model_deepseek_test.py@@ -6,12 +6,14 @@ Formatter tests have been moved to tests/formatter_deepseek_test.py."""from typing import Anyfrom datetime import datetime+import unittestfrom unittest import IsolatedAsyncioTestCasefrom unittest.mock import MagicMockfrom agentscope.message import TextBlock, ToolCallBlock, ThinkingBlockfrom agentscope.model import DeepSeekChatModelfrom agentscope.credential import DeepSeekCredential+from agentscope.tool import ToolChoice# ---------------------------------------------------------------------------@@ -114,3 +116,98 @@ class TestDeepSeekModelParsing(IsolatedAsyncioTestCase):resp = self._mock_completion(text="Hi")result = self.model._parse_completion_response(self.start, resp)self.assertEqual(result.id, "deepseek-1")+++# ---------------------------------------------------------------------------+# Shared _format_tools fixtures+# ---------------------------------------------------------------------------++_FT_TOOLS = [+ {+ "type": "function",+ "function": {+ "name": "get_weather",+ "description": "Get the weather",+ "parameters": {+ "type": "object",+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ },+ },+ },+ {+ "type": "function",+ "function": {+ "name": "get_time",+ "description": "Get the time",+ "parameters": {+ "type": "object",+ "properties": {"timezone": {"type": "string"}},+ "required": ["timezone"],+ },+ },+ },+]+++class TestDeepSeekFormatTools(unittest.TestCase):+ """Tests for DeepSeekChatModel._format_tools."""++ def setUp(self) -> None:+ """Set up model instance."""+ self.model = _make_model()++ def test_auto_mode(self) -> None:+ """Auto mode returns tools unchanged and string 'auto'."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertEqual(fmt_choice, "auto")++ def test_none_mode(self) -> None:+ """None mode returns tools unchanged and string 'none'."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="none"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertEqual(fmt_choice, "none")++ def test_required_mode(self) -> None:+ """Required mode returns tools unchanged and string 'required'."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="required"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertEqual(fmt_choice, "required")++ def test_str_mode_force_call(self) -> None:+ """A specific tool name returns a type=function dict."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="get_weather"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertEqual(+ fmt_choice,+ {"type": "function", "function": {"name": "get_weather"}},+ )++ def test_tools_filtered(self) -> None:+ """When tool_choice.tools is set, only those tools are included."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto", tools=["get_weather"]),+ )+ self.assertEqual(len(fmt_tools), 1)+ self.assertEqual(fmt_tools[0]["function"]["name"], "get_weather")+ self.assertEqual(fmt_choice, "auto")++ def test_no_tool_choice(self) -> None:+ """Without tool_choice, returns tools and None."""+ fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertIsNone(fmt_choice)diff --git a/tests/model_gemini_test.py b/tests/model_gemini_test.pyindex 53736994f..c789e14e0 100644--- a/tests/model_gemini_test.py+++ b/tests/model_gemini_test.py@@ -7,12 +7,14 @@ Formatter tests have been moved to tests/formatter_gemini_test.py.import jsonfrom typing import Anyfrom datetime import datetime+import unittestfrom unittest import IsolatedAsyncioTestCasefrom unittest.mock import MagicMockfrom agentscope.message import TextBlock, ToolCallBlock, ThinkingBlockfrom agentscope.model import GeminiChatModelfrom agentscope.credential import GeminiCredential+from agentscope.tool import ToolChoice# ---------------------------------------------------------------------------@@ -115,3 +117,145 @@ class TestGeminiModelParsing(IsolatedAsyncioTestCase):thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]self.assertEqual(len(thinkings), 1)self.assertEqual(thinkings[0].thinking, "Let me think...")+++# ---------------------------------------------------------------------------+# Shared _format_tools fixtures+# ---------------------------------------------------------------------------++_FT_TOOLS = [+ {+ "type": "function",+ "function": {+ "name": "get_weather",+ "description": "Get the weather",+ "parameters": {+ "type": "object",+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ },+ },+ },+ {+ "type": "function",+ "function": {+ "name": "get_time",+ "description": "Get the time",+ "parameters": {+ "type": "object",+ "properties": {"timezone": {"type": "string"}},+ "required": ["timezone"],+ },+ },+ },+]+++_FT_TOOLS_GEMINI = [+ {+ "function_declarations": [+ {+ "name": "get_weather",+ "description": "Get the weather",+ "parameters": {+ "type": "object",+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ },+ },+ {+ "name": "get_time",+ "description": "Get the time",+ "parameters": {+ "type": "object",+ "properties": {"timezone": {"type": "string"}},+ "required": ["timezone"],+ },+ },+ ],+ },+]+++# pylint: disable=protected-access+class TestGeminiFormatTools(unittest.TestCase):+ """Tests for GeminiChatModel._format_tools."""++ def setUp(self) -> None:+ """Set up model instance."""+ self.model = _make_model()++ def test_auto_mode(self) -> None:+ """Auto mode returns function_declarations and AUTO config."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS_GEMINI)+ self.assertEqual(+ fmt_choice,+ {"function_calling_config": {"mode": "AUTO"}},+ )++ def test_none_mode(self) -> None:+ """None mode returns function_declarations and NONE config."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="none"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS_GEMINI)+ self.assertEqual(+ fmt_choice,+ {"function_calling_config": {"mode": "NONE"}},+ )++ def test_required_mode(self) -> None:+ """Required mode maps to ANY config."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="required"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS_GEMINI)+ self.assertEqual(+ fmt_choice,+ {"function_calling_config": {"mode": "ANY"}},+ )++ def test_str_mode_force_call(self) -> None:+ """A specific tool name restricts via allowed_function_names."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="get_weather"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS_GEMINI)+ self.assertEqual(+ fmt_choice,+ {+ "function_calling_config": {+ "mode": "ANY",+ "allowed_function_names": ["get_weather"],+ },+ },+ )++ def test_tools_filtered(self) -> None:+ """When tool_choice.tools is set, only those tools are included."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto", tools=["get_weather"]),+ )+ self.assertEqual(len(fmt_tools[0]["function_declarations"]), 1)+ self.assertEqual(+ fmt_tools[0]["function_declarations"][0]["name"],+ "get_weather",+ )+ self.assertEqual(+ fmt_choice,+ {"function_calling_config": {"mode": "AUTO"}},+ )++ def test_no_tool_choice(self) -> None:+ """Without tool_choice, returns function_declarations and None."""+ fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)+ self.assertEqual(fmt_tools, _FT_TOOLS_GEMINI)+ self.assertIsNone(fmt_choice)diff --git a/tests/model_kimi_test.py b/tests/model_kimi_test.pyindex 8dc98adbe..07c192415 100644--- a/tests/model_kimi_test.py+++ b/tests/model_kimi_test.py@@ -7,12 +7,14 @@ Formatter tests have been moved to tests/formatter_kimi_test.py.import jsonfrom typing import Anyfrom datetime import datetime+import unittestfrom unittest import IsolatedAsyncioTestCasefrom unittest.mock import MagicMockfrom agentscope.message import TextBlock, ToolCallBlock, ThinkingBlockfrom agentscope.model import KimiChatModelfrom agentscope.credential import KimiCredential+from agentscope.tool import ToolChoice# ---------------------------------------------------------------------------@@ -113,3 +115,98 @@ class TestKimiModelParsing(IsolatedAsyncioTestCase):resp = self._mock_completion(text="Hi")result = self.model._parse_completion_response(self.start, resp)self.assertEqual(result.id, "kimi-1")+++# ---------------------------------------------------------------------------+# Shared _format_tools fixtures+# ---------------------------------------------------------------------------++_FT_TOOLS = [+ {+ "type": "function",+ "function": {+ "name": "get_weather",+ "description": "Get the weather",+ "parameters": {+ "type": "object",+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ },+ },+ },+ {+ "type": "function",+ "function": {+ "name": "get_time",+ "description": "Get the time",+ "parameters": {+ "type": "object",+ "properties": {"timezone": {"type": "string"}},+ "required": ["timezone"],+ },+ },+ },+]+++class TestKimiFormatTools(unittest.TestCase):+ """Tests for KimiChatModel._format_tools."""++ def setUp(self) -> None:+ """Set up model instance."""+ self.model = _make_model()++ def test_auto_mode(self) -> None:+ """Auto mode returns tools unchanged and string 'auto'."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertEqual(fmt_choice, "auto")++ def test_none_mode(self) -> None:+ """None mode returns tools unchanged and string 'none'."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="none"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertEqual(fmt_choice, "none")++ def test_required_mode(self) -> None:+ """Required mode returns tools unchanged and string 'required'."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="required"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertEqual(fmt_choice, "required")++ def test_str_mode_force_call(self) -> None:+ """A specific tool name returns a type=function dict."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="get_weather"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertEqual(+ fmt_choice,+ {"type": "function", "function": {"name": "get_weather"}},+ )++ def test_tools_filtered(self) -> None:+ """When tool_choice.tools is set, only those tools are included."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto", tools=["get_weather"]),+ )+ self.assertEqual(len(fmt_tools), 1)+ self.assertEqual(fmt_tools[0]["function"]["name"], "get_weather")+ self.assertEqual(fmt_choice, "auto")++ def test_no_tool_choice(self) -> None:+ """Without tool_choice, returns tools and None."""+ fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertIsNone(fmt_choice)diff --git a/tests/model_ollama_test.py b/tests/model_ollama_test.pyindex c8637bce6..4eb89f5e8 100644--- a/tests/model_ollama_test.py+++ b/tests/model_ollama_test.py@@ -7,11 +7,13 @@ Formatter tests have been moved to tests/formatter_ollama_test.py.import jsonfrom typing import Anyfrom datetime import datetime+import unittestfrom unittest import IsolatedAsyncioTestCasefrom unittest.mock import MagicMockfrom agentscope.message import TextBlock, ToolCallBlock, ThinkingBlockfrom agentscope.model import OllamaChatModel+from agentscope.tool import ToolChoice# ---------------------------------------------------------------------------@@ -99,3 +101,61 @@ class TestOllamaModelParsing(IsolatedAsyncioTestCase):result = await self.model._parse_completion_response(self.start, resp)thinkings = [b for b in result.content if isinstance(b, ThinkingBlock)]self.assertEqual(thinkings[0].thinking, "Let me think...")+++# ---------------------------------------------------------------------------+# Shared _format_tools fixtures+# ---------------------------------------------------------------------------++_FT_TOOLS = [+ {+ "type": "function",+ "function": {+ "name": "get_weather",+ "description": "Get the weather",+ "parameters": {+ "type": "object",+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ },+ },+ },+ {+ "type": "function",+ "function": {+ "name": "get_time",+ "description": "Get the time",+ "parameters": {+ "type": "object",+ "properties": {"timezone": {"type": "string"}},+ "required": ["timezone"],+ },+ },+ },+]+++class TestOllamaFormatTools(unittest.TestCase):+ """Tests for OllamaChatModel._format_tools."""++ def setUp(self) -> None:+ """Set up model instance."""+ self.model = _make_model()++ def test_tools_forwarded_no_choice(self) -> None:+ """Without tool_choice, returns tools unchanged and None."""+ fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertIsNone(fmt_choice)++ def test_tools_filtered(self) -> None:+ """When tool_choice.tools is set, only those tools are included."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto", tools=["get_weather"]),+ )+ self.assertIsNotNone(fmt_tools)+ assert fmt_tools is not None+ self.assertEqual(len(fmt_tools), 1)+ self.assertEqual(fmt_tools[0]["function"]["name"], "get_weather")+ self.assertIsNone(fmt_choice)diff --git a/tests/model_openai_chat_test.py b/tests/model_openai_chat_test.pyindex 62d731865..0ba0efbe0 100644--- a/tests/model_openai_chat_test.py+++ b/tests/model_openai_chat_test.py@@ -7,11 +7,13 @@ Formatter tests have been moved to tests/formatter_openai_chat_test.py.import jsonfrom typing import Anyfrom datetime import datetime+import unittestfrom unittest import IsolatedAsyncioTestCasefrom unittest.mock import MagicMockfrom agentscope.message import TextBlock, ToolCallBlock, ThinkingBlockfrom agentscope.model import OpenAIChatModel+from agentscope.tool import ToolChoicefrom agentscope.credential import OpenAICredential@@ -120,3 +122,98 @@ class TestOpenAIChatModelParsing(IsolatedAsyncioTestCase):resp = self._mock_completion(text="Hi")result = self.model._parse_completion_response(self.start, resp)self.assertEqual(result.id, "resp-1")+++# ---------------------------------------------------------------------------+# Shared _format_tools fixtures+# ---------------------------------------------------------------------------++_FT_TOOLS = [+ {+ "type": "function",+ "function": {+ "name": "get_weather",+ "description": "Get the weather",+ "parameters": {+ "type": "object",+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ },+ },+ },+ {+ "type": "function",+ "function": {+ "name": "get_time",+ "description": "Get the time",+ "parameters": {+ "type": "object",+ "properties": {"timezone": {"type": "string"}},+ "required": ["timezone"],+ },+ },+ },+]+++class TestOpenAIChatFormatTools(unittest.TestCase):+ """Tests for OpenAIChatModel._format_tools."""++ def setUp(self) -> None:+ """Set up model instance."""+ self.model = _make_model()++ def test_auto_mode(self) -> None:+ """Auto mode returns tools unchanged and string 'auto'."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertEqual(fmt_choice, "auto")++ def test_none_mode(self) -> None:+ """None mode returns tools unchanged and string 'none'."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="none"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertEqual(fmt_choice, "none")++ def test_required_mode(self) -> None:+ """Required mode returns tools unchanged and string 'required'."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="required"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertEqual(fmt_choice, "required")++ def test_str_mode_force_call(self) -> None:+ """A specific tool name returns a type=function dict."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="get_weather"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertEqual(+ fmt_choice,+ {"type": "function", "function": {"name": "get_weather"}},+ )++ def test_tools_filtered(self) -> None:+ """When tool_choice.tools is set, only those tools are included."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto", tools=["get_weather"]),+ )+ self.assertEqual(len(fmt_tools), 1)+ self.assertEqual(fmt_tools[0]["function"]["name"], "get_weather")+ self.assertEqual(fmt_choice, "auto")++ def test_no_tool_choice(self) -> None:+ """Without tool_choice, returns tools and None."""+ fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)+ self.assertEqual(fmt_tools, _FT_TOOLS)+ self.assertIsNone(fmt_choice)diff --git a/tests/model_openai_response_test.py b/tests/model_openai_response_test.pyindex fe6edfb66..8db83acf0 100644--- a/tests/model_openai_response_test.py+++ b/tests/model_openai_response_test.py@@ -7,11 +7,13 @@ Formatter tests have been moved to tests/formatter_openai_response_test.py.import jsonfrom typing import Anyfrom datetime import datetime+import unittestfrom unittest import IsolatedAsyncioTestCasefrom unittest.mock import MagicMockfrom agentscope.message import TextBlock, ToolCallBlock, ThinkingBlockfrom agentscope.model import OpenAIResponseModel+from agentscope.tool import ToolChoicefrom agentscope.credential import OpenAICredential@@ -136,3 +138,123 @@ class TestOpenAIResponseModelParsing(IsolatedAsyncioTestCase):resp = self._mock_response(text="Hi")result = self.model._parse_completion_response(self.start, resp)self.assertEqual(result.id, "resp-openai-1")+++# ---------------------------------------------------------------------------+# Shared _format_tools fixtures+# ---------------------------------------------------------------------------++_FT_TOOLS = [+ {+ "type": "function",+ "function": {+ "name": "get_weather",+ "description": "Get the weather",+ "parameters": {+ "type": "object",+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ },+ },+ },+ {+ "type": "function",+ "function": {+ "name": "get_time",+ "description": "Get the time",+ "parameters": {+ "type": "object",+ "properties": {"timezone": {"type": "string"}},+ "required": ["timezone"],+ },+ },+ },+]+++_FT_TOOLS_RESPONSE = [+ {+ "type": "function",+ "name": "get_weather",+ "description": "Get the weather",+ "parameters": {+ "type": "object",+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ },+ },+ {+ "type": "function",+ "name": "get_time",+ "description": "Get the time",+ "parameters": {+ "type": "object",+ "properties": {"timezone": {"type": "string"}},+ "required": ["timezone"],+ },+ },+]+++# pylint: disable=protected-access+class TestOpenAIResponseFormatTools(unittest.TestCase):+ """Tests for OpenAIResponseModel._format_tools."""++ def setUp(self) -> None:+ """Set up model instance."""+ self.model = _make_model()++ def test_auto_mode(self) -> None:+ """Auto mode returns flat tools and string 'auto'."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS_RESPONSE)+ self.assertEqual(fmt_choice, "auto")++ def test_none_mode(self) -> None:+ """None mode returns flat tools and string 'none'."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="none"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS_RESPONSE)+ self.assertEqual(fmt_choice, "none")++ def test_required_mode(self) -> None:+ """Required mode returns flat tools and string 'required'."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="required"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS_RESPONSE)+ self.assertEqual(fmt_choice, "required")++ def test_str_mode_force_call(self) -> None:+ """A specific tool name returns a type=function dict with name."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="get_weather"),+ )+ self.assertEqual(fmt_tools, _FT_TOOLS_RESPONSE)+ self.assertEqual(+ fmt_choice,+ {"type": "function", "name": "get_weather"},+ )++ def test_tools_filtered(self) -> None:+ """When tool_choice.tools is set, only those tools are included."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto", tools=["get_weather"]),+ )+ self.assertEqual(len(fmt_tools), 1)+ self.assertEqual(fmt_tools[0]["name"], "get_weather")+ self.assertEqual(fmt_choice, "auto")++ def test_no_tool_choice(self) -> None:+ """Without tool_choice, returns flat tools and None."""+ fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)+ self.assertEqual(fmt_tools, _FT_TOOLS_RESPONSE)+ self.assertIsNone(fmt_choice)diff --git a/tests/model_xai_test.py b/tests/model_xai_test.pyindex d3328ced4..22b678431 100644--- a/tests/model_xai_test.py+++ b/tests/model_xai_test.py@@ -9,6 +9,7 @@ import sysfrom typing import Anyfrom datetime import datetimefrom types import ModuleType+import unittestfrom unittest import IsolatedAsyncioTestCasefrom unittest.mock import MagicMock@@ -19,6 +20,7 @@ from agentscope.message import ()from agentscope.model import XAIChatModelfrom agentscope.credential import XAICredential+from agentscope.tool import ToolChoice# ---------------------------------------------------------------------------@@ -199,3 +201,125 @@ class TestXAIModelParsing(IsolatedAsyncioTestCase):resp = self._mock_response(text="Hi")result = self.model._parse_completion_response(self.start, resp)self.assertEqual(result.id, "xai-resp-1")+++# ---------------------------------------------------------------------------+# Shared _format_tools fixtures+# ---------------------------------------------------------------------------++_FT_TOOLS = [+ {+ "type": "function",+ "function": {+ "name": "get_weather",+ "description": "Get the weather",+ "parameters": {+ "type": "object",+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ },+ },+ },+ {+ "type": "function",+ "function": {+ "name": "get_time",+ "description": "Get the time",+ "parameters": {+ "type": "object",+ "properties": {"timezone": {"type": "string"}},+ "required": ["timezone"],+ },+ },+ },+]+++def _extend_xai_stub_for_tools() -> None:+ """Add tool and required_tool stubs to the existing xai_sdk stub."""+ xai_chat = sys.modules.get("xai_sdk.chat")+ if xai_chat is None or hasattr(xai_chat, "required_tool"):+ return++ class _RequiredTool:+ """Minimal stub for xai_sdk.chat.required_tool(name)."""++ def __init__(self, tool_name: str) -> None:+ self.tool_name = tool_name++ def __eq__(self, other: object) -> bool:+ """Compare by tool_name."""+ return (+ isinstance(other, _RequiredTool)+ and self.tool_name == other.tool_name+ )++ def _tool_stub(+ name: str,+ description: str = "",+ parameters: Any = None,+ ) -> MagicMock:+ """Minimal stub for xai_sdk.chat.tool(name, ...)."""+ m = MagicMock()+ m.name = name+ m.description = description+ m.parameters = parameters or {}+ return m++ xai_chat.required_tool = _RequiredTool+ xai_chat.tool = _tool_stub+++_extend_xai_stub_for_tools()+++class TestXAIFormatTools(unittest.TestCase):+ """Tests for XAIChatModel._format_tools."""++ def setUp(self) -> None:+ """Set up model instance."""+ self.model = _make_model()++ def test_no_tool_choice(self) -> None:+ """Without tool_choice, returns xai_sdk tools and None."""+ fmt_tools, fmt_choice = self.model._format_tools(_FT_TOOLS, None)+ self.assertIsNotNone(fmt_tools)+ self.assertEqual(len(fmt_tools), 2)+ self.assertIsNone(fmt_choice)++ def test_auto_mode(self) -> None:+ """Auto mode returns xai_sdk tools and string 'auto'."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto"),+ )+ self.assertIsNotNone(fmt_tools)+ self.assertEqual(fmt_choice, "auto")++ def test_none_mode(self) -> None:+ """None mode returns xai_sdk tools and string 'none'."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="none"),+ )+ self.assertIsNotNone(fmt_tools)+ self.assertEqual(fmt_choice, "none")++ def test_str_mode_force_call(self) -> None:+ """A specific tool name returns a required_tool stub object."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="get_weather"),+ )+ self.assertIsNotNone(fmt_tools)+ self.assertEqual(fmt_choice.tool_name, "get_weather")++ def test_tools_filtered(self) -> None:+ """When tool_choice.tools is set, only those tools are included."""+ fmt_tools, fmt_choice = self.model._format_tools(+ _FT_TOOLS,+ ToolChoice(mode="auto", tools=["get_weather"]),+ )+ self.assertEqual(len(fmt_tools), 1)+ self.assertEqual(fmt_tools[0].name, "get_weather")+ self.assertEqual(fmt_choice, "auto")