Skip to content

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

feat(model): unify the thinking related argument for the chat model classes (#1622)

qbcd0826821e2cb
diff --git a/scripts/model_examples/openai_chat_call.py b/scripts/model_examples/openai_chat_call.py
index 797b3903b..04316c7ea 100644
--- a/scripts/model_examples/openai_chat_call.py
+++ b/scripts/model_examples/openai_chat_call.py
@@ -26,9 +26,12 @@ async def example_simple_call() -> None:
credential=OpenAICredential(
api_key=os.environ["OPENAI_API_KEY"],
),
- model="gpt-4.1",
+ model="o4-mini",
stream=True,
- context_size=1_047_576,
+ context_size=200_000,
+ parameters=OpenAIChatModel.Parameters(
+ reasoning_effort="low",
+ ),
)
msgs = [
@@ -70,9 +73,12 @@ async def example_tool_call() -> None:
credential=OpenAICredential(
api_key=os.environ["OPENAI_API_KEY"],
),
- model="gpt-4.1",
+ model="o4-mini",
stream=True,
- context_size=1_047_576,
+ context_size=200_000,
+ parameters=OpenAIChatModel.Parameters(
+ reasoning_effort="low",
+ ),
)
msgs = [
diff --git a/src/agentscope/model/_deepseek/_model.py b/src/agentscope/model/_deepseek/_model.py
index 9308f330a..5f6974d1d 100644
--- a/src/agentscope/model/_deepseek/_model.py
+++ b/src/agentscope/model/_deepseek/_model.py
@@ -39,9 +39,20 @@ class DeepSeekChatModel(ChatModelBase):
default=False,
title="Thinking",
description=(
- "Whether to enable thinking. Note: for the DeepSeek API, "
- "thinking mode is selected by choosing the deepseek-reasoner "
- "model rather than an API parameter."
+ "Whether to enable thinking mode. When enabled, the model "
+ "outputs a chain-of-thought reasoning before the final "
+ "answer via the reasoning_content field."
+ ),
+ )
+
+ reasoning_effort: Literal["high", "max"] | None = Field(
+ default=None,
+ title="Reasoning Effort",
+ description=(
+ "Controls the depth of reasoning in thinking mode. "
+ "Supported values: high (default), max. "
+ "For compatibility, low/medium map to high, "
+ "xhigh maps to max."
),
)
@@ -158,8 +169,18 @@ class DeepSeekChatModel(ChatModelBase):
if self.parameters.top_p is not None:
kwargs["top_p"] = self.parameters.top_p
+ if self.parameters.reasoning_effort is not None:
+ kwargs["reasoning_effort"] = self.parameters.reasoning_effort
+
kwargs.update(generate_kwargs)
+ thinking_type = (
+ "enabled" if self.parameters.thinking_enable else "disabled"
+ )
+ kwargs.setdefault("extra_body", {})
+ kwargs["extra_body"].setdefault("thinking", {})
+ kwargs["extra_body"]["thinking"].setdefault("type", thinking_type)
+
fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)
if fmt_tools:
diff --git a/src/agentscope/model/_moonshot/_model.py b/src/agentscope/model/_moonshot/_model.py
index d130da7dd..c08df5daa 100644
--- a/src/agentscope/model/_moonshot/_model.py
+++ b/src/agentscope/model/_moonshot/_model.py
@@ -35,6 +35,16 @@ class MoonshotChatModel(ChatModelBase):
gt=0,
)
+ thinking_enable: bool = Field(
+ default=False,
+ title="Thinking",
+ description=(
+ "Whether to enable thinking mode. For kimi-k2-thinking, "
+ "thinking is always enabled. For kimi-k2.6, thinking is "
+ "enabled by default but can be disabled."
+ ),
+ )
+
temperature: float | None = Field(
default=None,
title="Temperature",
@@ -150,6 +160,13 @@ class MoonshotChatModel(ChatModelBase):
kwargs.update(generate_kwargs)
+ thinking_type = (
+ "enabled" if self.parameters.thinking_enable else "disabled"
+ )
+ kwargs.setdefault("extra_body", {})
+ kwargs["extra_body"].setdefault("thinking", {})
+ kwargs["extra_body"]["thinking"].setdefault("type", thinking_type)
+
fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)
if fmt_tools:
diff --git a/src/agentscope/model/_openai_chat/_model.py b/src/agentscope/model/_openai_chat/_model.py
index a808aeacd..86ecc9c9d 100644
--- a/src/agentscope/model/_openai_chat/_model.py
+++ b/src/agentscope/model/_openai_chat/_model.py
@@ -39,9 +39,22 @@ class OpenAIChatModel(ChatModelBase):
default=False,
title="Thinking",
description=(
- "Whether to enable reasoning output. Note: for the OpenAI "
- "Chat Completions API, reasoning is controlled by model "
- "selection (e.g. o3, o4-mini) rather than an API parameter."
+ "Whether to enable reasoning for reasoning models "
+ "(e.g. o3, o4-mini, gpt-5.5). Use reasoning_effort to "
+ "control the depth of reasoning."
+ ),
+ )
+
+ reasoning_effort: (
+ Literal["none", "minimal", "low", "medium", "high", "xhigh"] | None
+ ) = Field(
+ default=None,
+ title="Reasoning Effort",
+ description=(
+ "Controls the depth of reasoning for reasoning models "
+ "(e.g. o3, o4-mini, gpt-5.5). Supported values are "
+ "model-dependent and may include: none, minimal, low, "
+ "medium, high, xhigh."
),
)
@@ -165,6 +178,12 @@ class OpenAIChatModel(ChatModelBase):
if self.parameters.top_p is not None:
kwargs["top_p"] = self.parameters.top_p
+ if (
+ self.parameters.thinking_enable
+ and self.parameters.reasoning_effort
+ ):
+ kwargs["reasoning_effort"] = self.parameters.reasoning_effort
+
kwargs.update(generate_kwargs)
fmt_tools, fmt_tool_choice = self._format_tools(tools, tool_choice)
diff --git a/src/agentscope/model/_openai_response/_model.py b/src/agentscope/model/_openai_response/_model.py
index e7c0d525b..fc5d2e3ad 100644
--- a/src/agentscope/model/_openai_response/_model.py
+++ b/src/agentscope/model/_openai_response/_model.py
@@ -42,12 +42,26 @@ class OpenAIResponseModel(ChatModelBase):
gt=0,
)
- reasoning_effort: Literal["low", "medium", "high"] | None = Field(
+ thinking_enable: bool = Field(
+ default=False,
+ title="Thinking",
+ description=(
+ "Whether to enable reasoning for reasoning models "
+ "(e.g. o3, o4-mini, gpt-5.5). Use reasoning_effort to "
+ "control the depth of reasoning."
+ ),
+ )
+
+ reasoning_effort: (
+ Literal["none", "minimal", "low", "medium", "high", "xhigh"] | None
+ ) = Field(
default=None,
title="Reasoning Effort",
description=(
- "The reasoning effort level for reasoning models "
- "(e.g. o3, o4-mini)."
+ "Controls the depth of reasoning for reasoning models "
+ "(e.g. o3, o4-mini, gpt-5.5). Supported values are "
+ "model-dependent and may include: none, minimal, low, "
+ "medium, high, xhigh."
),
)
@@ -154,7 +168,10 @@ class OpenAIResponseModel(ChatModelBase):
if self.parameters.temperature is not None:
api_kwargs["temperature"] = self.parameters.temperature
- if self.parameters.reasoning_effort is not None:
+ if (
+ self.parameters.thinking_enable
+ and self.parameters.reasoning_effort
+ ):
api_kwargs["reasoning"] = {
"effort": self.parameters.reasoning_effort,
}
diff --git a/src/agentscope/model/_xai/_model.py b/src/agentscope/model/_xai/_model.py
index a7ce506f3..e998b8ff7 100644
--- a/src/agentscope/model/_xai/_model.py
+++ b/src/agentscope/model/_xai/_model.py
@@ -46,6 +46,16 @@ class XAIChatModel(ChatModelBase):
)
"""The maximum number of tokens to generate."""
+ thinking_enable: bool = Field(
+ default=False,
+ title="Thinking",
+ description=(
+ "Whether to enable reasoning for models that support "
+ "extended thinking (e.g. ``grok-3-mini``). Use "
+ "reasoning_effort to control the depth of reasoning."
+ ),
+ )
+
reasoning_effort: Literal["low", "medium", "high"] | None = Field(
default=None,
title="Reasoning Effort",
@@ -57,7 +67,6 @@ class XAIChatModel(ChatModelBase):
"reasoning."
),
)
- """Reasoning effort level for xAI reasoning models."""
temperature: float | None = Field(
default=None,
@@ -167,7 +176,10 @@ class XAIChatModel(ChatModelBase):
create_kwargs["temperature"] = self.parameters.temperature
if self.parameters.top_p is not None:
create_kwargs["top_p"] = self.parameters.top_p
- if self.parameters.reasoning_effort is not None:
+ if (
+ self.parameters.thinking_enable
+ and self.parameters.reasoning_effort
+ ):
create_kwargs[
"reasoning_effort"
] = self.parameters.reasoning_effort
diff --git a/tests/model_deepseek_test.py b/tests/model_deepseek_test.py
index f5562a2e1..f20006dae 100644
--- a/tests/model_deepseek_test.py
+++ b/tests/model_deepseek_test.py
@@ -520,6 +520,32 @@ class TestDeepSeekStream(IsolatedAsyncioTestCase):
self.assertEqual(responses[-1].usage.cache_input_tokens, 50)
+class TestDeepSeekModelParameters(unittest.TestCase):
+ """Tests for DeepSeekChatModel.Parameters."""
+
+ def test_thinking_enable_stored_on_model(self) -> None:
+ """thinking_enable is accessible through model.parameters."""
+ model = DeepSeekChatModel(
+ credential=DeepSeekCredential(api_key="test"),
+ model="deepseek-reasoner",
+ stream=False,
+ context_size=65_536,
+ parameters=DeepSeekChatModel.Parameters(thinking_enable=True),
+ )
+ self.assertTrue(model.parameters.thinking_enable)
+
+ def test_reasoning_effort_stored_on_model(self) -> None:
+ """reasoning_effort is accessible through model.parameters."""
+ model = DeepSeekChatModel(
+ credential=DeepSeekCredential(api_key="test"),
+ model="deepseek-reasoner",
+ stream=False,
+ context_size=65_536,
+ parameters=DeepSeekChatModel.Parameters(reasoning_effort="max"),
+ )
+ self.assertEqual(model.parameters.reasoning_effort, "max")
+
+
# ---------------------------------------------------------------------------
# Shared _format_tools fixtures
# ---------------------------------------------------------------------------
diff --git a/tests/model_moonshot_test.py b/tests/model_moonshot_test.py
index 92ffabc7a..a13cf8b29 100644
--- a/tests/model_moonshot_test.py
+++ b/tests/model_moonshot_test.py
@@ -232,6 +232,21 @@ class TestMoonshotNonStream(IsolatedAsyncioTestCase):
)
+class TestKimiModelParameters(unittest.TestCase):
+ """Tests for MoonshotChatModel.Parameters."""
+
+ def test_thinking_enable_stored_on_model(self) -> None:
+ """thinking_enable is accessible through model.parameters."""
+ model = MoonshotChatModel(
+ credential=MoonshotCredential(api_key="test"),
+ model="kimi-k2-5",
+ stream=False,
+ context_size=131_072,
+ parameters=MoonshotChatModel.Parameters(thinking_enable=True),
+ )
+ self.assertTrue(model.parameters.thinking_enable)
+
+
# ---------------------------------------------------------------------------
# Streaming tests
# ---------------------------------------------------------------------------
diff --git a/tests/model_openai_chat_test.py b/tests/model_openai_chat_test.py
index 9058b5ff2..9dc9fccbd 100644
--- a/tests/model_openai_chat_test.py
+++ b/tests/model_openai_chat_test.py
@@ -422,6 +422,32 @@ class TestOpenAIChatStream(IsolatedAsyncioTestCase):
self.assertEqual(responses[-1].usage.output_tokens, 20)
+class TestOpenAIChatModelParameters(unittest.TestCase):
+ """Tests for OpenAIChatModel.Parameters."""
+
+ def test_reasoning_effort_stored_on_model(self) -> None:
+ """reasoning_effort is accessible through model.parameters."""
+ model = OpenAIChatModel(
+ credential=OpenAICredential(api_key="test"),
+ model="o3",
+ stream=False,
+ context_size=200_000,
+ parameters=OpenAIChatModel.Parameters(reasoning_effort="low"),
+ )
+ self.assertEqual(model.parameters.reasoning_effort, "low")
+
+ def test_thinking_enable_stored_on_model(self) -> None:
+ """thinking_enable is accessible through model.parameters."""
+ model = OpenAIChatModel(
+ credential=OpenAICredential(api_key="test"),
+ model="o3",
+ stream=False,
+ context_size=200_000,
+ parameters=OpenAIChatModel.Parameters(thinking_enable=True),
+ )
+ self.assertTrue(model.parameters.thinking_enable)
+
+
# ---------------------------------------------------------------------------
# Shared _format_tools fixtures
# ---------------------------------------------------------------------------
diff --git a/tests/model_openai_response_test.py b/tests/model_openai_response_test.py
index eda6e09f7..4563a5c08 100644
--- a/tests/model_openai_response_test.py
+++ b/tests/model_openai_response_test.py
@@ -210,6 +210,34 @@ class TestOpenAIResponseNonStream(IsolatedAsyncioTestCase):
)
+class TestOpenAIResponseModelParameters(unittest.TestCase):
+ """Tests for OpenAIResponseModel.Parameters."""
+
+ def test_thinking_enable_stored_on_model(self) -> None:
+ """thinking_enable is accessible through model.parameters."""
+ model = OpenAIResponseModel(
+ credential=OpenAICredential(api_key="test"),
+ model="o4-mini",
+ stream=False,
+ context_size=200_000,
+ parameters=OpenAIResponseModel.Parameters(thinking_enable=True),
+ )
+ self.assertTrue(model.parameters.thinking_enable)
+
+ def test_reasoning_effort_stored_on_model(self) -> None:
+ """reasoning_effort is accessible through model.parameters."""
+ model = OpenAIResponseModel(
+ credential=OpenAICredential(api_key="test"),
+ model="o4-mini",
+ stream=False,
+ context_size=200_000,
+ parameters=OpenAIResponseModel.Parameters(
+ reasoning_effort="high",
+ ),
+ )
+ self.assertEqual(model.parameters.reasoning_effort, "high")
+
+
# ---------------------------------------------------------------------------
# Streaming tests
# ---------------------------------------------------------------------------
diff --git a/tests/model_xai_test.py b/tests/model_xai_test.py
index 64c75e7c7..4e6de9c59 100644
--- a/tests/model_xai_test.py
+++ b/tests/model_xai_test.py
@@ -432,6 +432,32 @@ class TestXAIStream(IsolatedAsyncioTestCase):
)
+class TestXAIModelParameters(unittest.TestCase):
+ """Tests for XAIChatModel.Parameters."""
+
+ def test_thinking_enable_stored_on_model(self) -> None:
+ """thinking_enable is accessible through model.parameters."""
+ model = XAIChatModel(
+ credential=XAICredential(api_key="test"),
+ model="grok-3-mini",
+ stream=False,
+ context_size=131_072,
+ parameters=XAIChatModel.Parameters(thinking_enable=True),
+ )
+ self.assertTrue(model.parameters.thinking_enable)
+
+ def test_reasoning_effort_stored_on_model(self) -> None:
+ """reasoning_effort is accessible through model.parameters."""
+ model = XAIChatModel(
+ credential=XAICredential(api_key="test"),
+ model="grok-3-mini",
+ stream=False,
+ context_size=131_072,
+ parameters=XAIChatModel.Parameters(reasoning_effort="high"),
+ )
+ self.assertEqual(model.parameters.reasoning_effort, "high")
+
+
# ---------------------------------------------------------------------------
# _format_tools tests
# ---------------------------------------------------------------------------