Skip to content

Build and run agents you can see, understand and trust.

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.py
index 40ccd4e0d..7681c6ad2 100644
--- a/src/agentscope/agent/_agent.py
+++ b/src/agentscope/agent/_agent.py
@@ -3,6 +3,7 @@
import asyncio
import inspect
import uuid
+
from asyncio import Queue
from copy import deepcopy
from 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.py
index 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 middleware
input_kwargs: Dictionary containing:
- - tool_choice: ToolChoice (default "auto")
+ - tool_choice: ToolChoice (default None)
next_handler: Callable that executes the next middleware or
original method
diff --git a/src/agentscope/model/_anthropic/_model.py b/src/agentscope/model/_anthropic/_model.py
index 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, List
from pydantic import BaseModel, Field
-from .._base import ChatModelBase
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
from .._model_response import ChatResponse
from .._model_usage import ChatUsage
from ...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_choice
formatted_messages = await self.formatter.format(messages)
@@ -402,64 +399,73 @@ class AnthropicChatModel(ChatModelBase):
_final_kwargs["id"] = response_id
yield 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.py
index 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.py
index 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_CHECKING
from pydantic import BaseModel, Field
from aioitertools import iter as giter
-from .._base import ChatModelBase
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
from .._model_response import ChatResponse
from .._model_usage import ChatUsage
from ...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 names
kwargs["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, mode
diff --git a/src/agentscope/model/_deepseek/_model.py b/src/agentscope/model/_deepseek/_model.py
index 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, List
from pydantic import BaseModel, Field
-from .._base import ChatModelBase
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
from .._model_response import ChatResponse
from .._model_usage import ChatUsage
from ...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_choice
if 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, mode
diff --git a/src/agentscope/model/_gemini/_model.py b/src/agentscope/model/_gemini/_model.py
index 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, List
from pydantic import BaseModel, Field
-from .._base import ChatModelBase
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
from .._model_response import ChatResponse
from .._model_usage import ChatUsage
from ...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_choice
kwargs: 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_choice
mode_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_choice
diff --git a/src/agentscope/model/_kimi/_model.py b/src/agentscope/model/_kimi/_model.py
index 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, List
from pydantic import BaseModel, Field
-from .._base import ChatModelBase
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
from .._model_response import ChatResponse
from .._model_usage import ChatUsage
from ...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_choice
if 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, mode
diff --git a/src/agentscope/model/_ollama/_model.py b/src/agentscope/model/_ollama/_model.py
index 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_tools
start_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.py
index 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, List
from pydantic import BaseModel, Field
-from .._base import ChatModelBase
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
from .._model_response import ChatResponse
from .._model_usage import ChatUsage
from ...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_tools
if 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_choice
if 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, mode
diff --git a/src/agentscope/model/_openai_response/_model.py b/src/agentscope/model/_openai_response/_model.py
index 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_CHECKING
from pydantic import BaseModel, Field
-from .._base import ChatModelBase
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
from .._model_response import ChatResponse
from .._model_usage import ChatUsage
from ...credential import OpenAICredential
@@ -23,8 +23,6 @@ else:
ResponseStreamEvent = Any
AsyncStream = 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 = None
if 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, mode
diff --git a/src/agentscope/model/_xai/_model.py b/src/agentscope/model/_xai/_model.py
index 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_CHECKING
from pydantic import BaseModel, Field
-from .._base import ChatModelBase
+from .._base import ChatModelBase, _TOOL_CHOICE_LITERAL_MODES
from .._model_response import ChatResponse
from .._model_usage import ChatUsage
from ...credential import XAICredential
-from ...formatter._xai_formatter import XAIChatFormatter
+from ...formatter import XAIChatFormatter
from ...message import (
TextBlock,
ThinkingBlock,
@@ -20,11 +20,10 @@ from ...tracing import trace_llm
if TYPE_CHECKING:
from xai_sdk import AsyncClient
- from xai_sdk.chat import Response, Chunk
+ from xai_sdk.chat import Response
else:
AsyncClient = Any
Response = Any
- Chunk = Any
class XAIChatModel(ChatModelBase):
@@ -152,22 +151,15 @@ class XAIChatModel(ChatModelBase):
generator of ``ChatResponse`` objects when streaming is
enabled.
"""
- 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.py
index 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 = None
diff --git a/src/agentscope/tracing/_extractor.py b/src/agentscope/tracing/_extractor.py
index 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_CHECKING
from ..embedding import EmbeddingModelBase
from ..message import Msg, ToolCallBlock
from ..model import ChatModelBase
+from ..tool import ToolChoice
from ._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 nested
structure: ``[{"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 None
try:
diff --git a/tests/model_anthropic_test.py b/tests/model_anthropic_test.py
index 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 json
from typing import Any
from datetime import datetime
+import unittest
from unittest import IsolatedAsyncioTestCase
from unittest.mock import MagicMock
from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
from agentscope.model import AnthropicChatModel
from 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.py
index d3e4b1e08..f126ce75f 100644
--- a/tests/model_dashscope_test.py
+++ b/tests/model_dashscope_test.py
@@ -8,12 +8,14 @@ import json
from typing import Any
from datetime import datetime
from http import HTTPStatus
+import unittest
from unittest import IsolatedAsyncioTestCase
from unittest.mock import MagicMock
from agentscope.message import TextBlock, ToolCallBlock
from agentscope.model import DashScopeChatModel
from 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.py
index 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 Any
from datetime import datetime
+import unittest
from unittest import IsolatedAsyncioTestCase
from unittest.mock import MagicMock
from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
from agentscope.model import DeepSeekChatModel
from 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.py
index 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 json
from typing import Any
from datetime import datetime
+import unittest
from unittest import IsolatedAsyncioTestCase
from unittest.mock import MagicMock
from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
from agentscope.model import GeminiChatModel
from 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.py
index 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 json
from typing import Any
from datetime import datetime
+import unittest
from unittest import IsolatedAsyncioTestCase
from unittest.mock import MagicMock
from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
from agentscope.model import KimiChatModel
from 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.py
index 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 json
from typing import Any
from datetime import datetime
+import unittest
from unittest import IsolatedAsyncioTestCase
from unittest.mock import MagicMock
from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
from 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.py
index 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 json
from typing import Any
from datetime import datetime
+import unittest
from unittest import IsolatedAsyncioTestCase
from unittest.mock import MagicMock
from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
from agentscope.model import OpenAIChatModel
+from agentscope.tool import ToolChoice
from 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.py
index 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 json
from typing import Any
from datetime import datetime
+import unittest
from unittest import IsolatedAsyncioTestCase
from unittest.mock import MagicMock
from agentscope.message import TextBlock, ToolCallBlock, ThinkingBlock
from agentscope.model import OpenAIResponseModel
+from agentscope.tool import ToolChoice
from 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.py
index d3328ced4..22b678431 100644
--- a/tests/model_xai_test.py
+++ b/tests/model_xai_test.py
@@ -9,6 +9,7 @@ import sys
from typing import Any
from datetime import datetime
from types import ModuleType
+import unittest
from unittest import IsolatedAsyncioTestCase
from unittest.mock import MagicMock
@@ -19,6 +20,7 @@ from agentscope.message import (
)
from agentscope.model import XAIChatModel
from 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")