Skip to content

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

fix(model): derive anthropic thinking budget from per-call max_tokens (#3292)

哈基米f37adb1d467b
diff --git a/src/agentscope/model/_anthropic/_model.py b/src/agentscope/model/_anthropic/_model.py
index 46f03e9cf..cd2dd1194 100644
--- a/src/agentscope/model/_anthropic/_model.py
+++ b/src/agentscope/model/_anthropic/_model.py
@@ -24,6 +24,9 @@ else:
AsyncStream = Any
+_DEFAULT_MAX_TOKENS = 8192
+
+
def _total_input_tokens(usage: Any) -> int:
"""The input tokens of an Anthropic usage, including the cached ones.
@@ -209,17 +212,34 @@ class AnthropicChatModel(ChatModelBase):
self,
max_tokens: int,
) -> tuple[dict[str, Any] | None, int]:
- """Build the provider-specific thinking configuration."""
+ """Build thinking defaults and return a suggested output limit.
+
+ Only manual (``enabled``) thinking needs a budget. If the caller
+ omits it, use half the effective output limit, rounded down, with
+ a minimum of 1024 tokens. Raise ``ValueError`` if the resulting
+ budget would reach or exceed the limit.
+
+ Forward an explicit budget and any explicit output limit as given
+ for the provider to validate. If the caller omitted the limit and
+ the budget reaches or exceeds the 8192-token default, set the limit
+ to the budget plus 1024 to leave room for the answer.
+ """
mode = self._thinking_mode()
if mode is None:
return None, max_tokens
thinking: dict[str, Any] = {"type": mode}
if mode == "enabled":
- # Anthropic requires max_tokens > budget_tokens strictly.
- budget = self.parameters.thinking_budget or (max_tokens // 2)
- if budget >= max_tokens:
- # Auto-expand max_tokens to satisfy the inequality.
+ budget = self.parameters.thinking_budget
+ if budget is None:
+ budget = max(1024, max_tokens // 2)
+ if budget >= max_tokens:
+ raise ValueError(
+ "Cannot fit an automatic thinking budget under "
+ f"max_tokens={max_tokens}. Raise max_tokens above "
+ "1024 or disable thinking for this call.",
+ )
+ elif budget >= max_tokens:
max_tokens = budget + 1024
thinking["budget_tokens"] = budget
@@ -266,25 +286,20 @@ class AnthropicChatModel(ChatModelBase):
enabled.
"""
- # Anthropic requires max_tokens; fall back to a safe default when
- # the user hasn't configured one explicitly.
- max_tokens = self.parameters.max_tokens or 8192
-
kwargs: dict[str, Any] = {
"model": model_name,
- "max_tokens": max_tokens,
"stream": self.stream,
**generate_kwargs,
}
-
- if "thinking" not in kwargs:
- thinking, expanded_max_tokens = self._build_thinking_config(
- max_tokens,
- )
- if thinking is not None:
- kwargs["thinking"] = thinking
- if expanded_max_tokens != max_tokens:
- kwargs["max_tokens"] = expanded_max_tokens
+ # Resolve max_tokens in SDK precedence order: extra_body, per-call
+ # argument, then model parameters. Leave it unset if none applies so
+ # the thinking policy can distinguish the default from an explicit cap.
+ if self.parameters.max_tokens is not None:
+ kwargs.setdefault("max_tokens", self.parameters.max_tokens)
+ extra_body = kwargs.get("extra_body") or {}
+ if "max_tokens" in extra_body:
+ # The SDK merges extra_body after validating its named arguments.
+ kwargs["max_tokens"] = extra_body["max_tokens"]
# Effort travels inside ``output_config``, not as a top-level field.
if "output_config" not in kwargs:
@@ -298,6 +313,15 @@ class AnthropicChatModel(ChatModelBase):
if fmt_tool_choice is not None:
kwargs["tool_choice"] = fmt_tool_choice
+ default_limit = _DEFAULT_MAX_TOKENS
+ if "thinking" not in kwargs and "thinking" not in extra_body:
+ thinking, default_limit = self._build_thinking_config(
+ kwargs.get("max_tokens", default_limit),
+ )
+ if thinking is not None:
+ kwargs["thinking"] = thinking
+ kwargs.setdefault("max_tokens", default_limit)
+
formatted_messages = await self.formatter.format(messages)
# Extract the system message
diff --git a/tests/model_anthropic_test.py b/tests/model_anthropic_test.py
index 8ae5177c2..82c506344 100644
--- a/tests/model_anthropic_test.py
+++ b/tests/model_anthropic_test.py
@@ -13,6 +13,9 @@ import unittest
from unittest import IsolatedAsyncioTestCase
from unittest.mock import AsyncMock, MagicMock, patch
+import httpx
+import httpx2
+from anthropic import DefaultAsyncHttpxClient
from anthropic import types as anthropic_types
from utils import AnyString
@@ -547,6 +550,153 @@ class TestAnthropicThinkingMode(IsolatedAsyncioTestCase):
self.assertEqual(kwargs["thinking"]["budget_tokens"], 8192)
self.assertGreater(kwargs["max_tokens"], 8192)
+ async def test_per_call_max_tokens_bounds_auto_budget(self) -> None:
+ """The auto budget must respect a per-call max_tokens override."""
+ self.model.parameters.thinking_enable = True
+
+ await self.model([], max_tokens=4096)
+
+ kwargs = self.mock_create.call_args.kwargs
+ self.assertEqual(kwargs["max_tokens"], 4096)
+ self.assertEqual(
+ kwargs["thinking"],
+ {"type": "enabled", "budget_tokens": 2048},
+ )
+
+ async def test_auto_budget_floors_at_provider_minimum(self) -> None:
+ """Half of a small cap can fall below 1024, so clamp it up."""
+ self.model.parameters.thinking_enable = True
+
+ await self.model([], max_tokens=1500)
+
+ kwargs = self.mock_create.call_args.kwargs
+ self.assertEqual(kwargs["max_tokens"], 1500)
+ self.assertEqual(
+ kwargs["thinking"],
+ {"type": "enabled", "budget_tokens": 1024},
+ )
+
+ async def test_explicit_budget_is_forwarded(self) -> None:
+ """Let the provider validate the caller's explicit budget."""
+ self.model.parameters.thinking_enable = True
+ self.model.parameters.thinking_budget = 512
+
+ await self.model([])
+
+ kwargs = self.mock_create.call_args.kwargs
+ self.assertEqual(
+ kwargs["thinking"],
+ {"type": "enabled", "budget_tokens": 512},
+ )
+
+ async def test_unsatisfiable_cap_fails_fast(self) -> None:
+ """No valid budget exists while max_tokens <= 1024."""
+ self.model.parameters.thinking_enable = True
+
+ with self.assertRaises(ValueError) as ctx:
+ await self.model([], max_tokens=1024)
+
+ self.assertIn("1024", str(ctx.exception))
+ self.assertIn("max_tokens", str(ctx.exception))
+ self.mock_create.assert_not_called()
+
+ async def test_caller_can_disable_thinking_per_call(self) -> None:
+ """An explicit thinking kwarg is the per-call escape hatch."""
+ self.model.parameters.thinking_enable = True
+
+ await self.model(
+ [],
+ max_tokens=1000,
+ thinking={"type": "disabled"},
+ )
+
+ kwargs = self.mock_create.call_args.kwargs
+ self.assertEqual(kwargs["max_tokens"], 1000)
+ self.assertEqual(kwargs["thinking"], {"type": "disabled"})
+
+ async def test_explicit_limits_on_wire(self) -> None:
+ """Exercise SDK body overrides and caller limits at the HTTP layer."""
+ self.model.parameters.thinking_enable = True
+ self.model.parameters.max_tokens = 1500
+ bodies = []
+
+ # Use the same HTTP types as the installed Anthropic SDK.
+ backend = (
+ httpx2
+ if issubclass(DefaultAsyncHttpxClient, httpx2.AsyncClient)
+ else httpx
+ )
+
+ def capture(request: Any) -> Any:
+ bodies.append(json.loads(request.content))
+ return backend.Response(
+ 200,
+ json={
+ "id": "msg-1",
+ "type": "message",
+ "role": "assistant",
+ "model": self.model.model,
+ "content": [],
+ "usage": {"input_tokens": 1, "output_tokens": 0},
+ },
+ )
+
+ async with DefaultAsyncHttpxClient(
+ transport=backend.MockTransport(capture),
+ ) as client:
+ model = AnthropicChatModel(
+ credential=self.model.credential,
+ model=self.model.model,
+ parameters=self.model.parameters,
+ stream=False,
+ client_kwargs={"http_client": client},
+ )
+ # (budget, call overrides, wire limit, wire thinking)
+ cases: list[tuple[int | None, dict, int, dict]] = [
+ (4096, {}, 1500, {"type": "enabled", "budget_tokens": 4096}),
+ (
+ 4096,
+ {"max_tokens": 1000},
+ 1000,
+ {"type": "enabled", "budget_tokens": 4096},
+ ),
+ (
+ None,
+ {"max_tokens": 1000, "extra_body": {"max_tokens": 8192}},
+ 8192,
+ {"type": "enabled", "budget_tokens": 4096},
+ ),
+ (
+ None,
+ {"extra_body": {"max_tokens": 1025}},
+ 1025,
+ {"type": "enabled", "budget_tokens": 1024},
+ ),
+ (
+ None,
+ {
+ "max_tokens": 1000,
+ "extra_body": {"thinking": {"type": "disabled"}},
+ },
+ 1000,
+ {"type": "disabled"},
+ ),
+ ]
+ for budget, overrides, limit, thinking in cases:
+ with self.subTest(budget=budget, overrides=overrides):
+ model.parameters.thinking_budget = budget
+ await model([], **overrides)
+ self.assertEqual(
+ bodies[-1],
+ {
+ "model": model.model,
+ "stream": False,
+ "messages": [],
+ "max_tokens": limit,
+ "thinking": thinking,
+ },
+ )
+
def test_resolved_mode_drives_tool_choice_downgrade(self) -> None:
"""Only budget mode forbids forced tool use, so only it downgrades.