feat(adk): add Anthropic effort config handling, thinking parameter propagation, and conflict mitigation

Key changes:
 - Reasoning Effort Support for anthropic model: Introduces AnthropicGenerateContentConfig to allow users to set the effort field directly ("low", "medium", "high", "xhigh", "max") for Anthropic model effort level.
- the standard thinking_config.thinking_level was not passed to anthropic effort due to mapping inconsistencies between the 4-level standard enum and Anthropic's 5 effort levels. It will raise a warning.
- Conflict Mitigation: Automatically excludes sampling parameters (temperature, top_p, top_k) when thinking or reasoning effort is enabled, avoiding Anthropic API 400 errors. Emits a warning log if these parameters were provided but ignored.
- Unified Parameter Propagation: Propagates core GenerateContentConfig parameters (temperature, top_p, top_k, stop_sequences, and max_output_tokens [mapped to max_tokens]) to the Anthropic client using the new _build_anthropic_kwargs helper.
- Type Annotation Updates: Adds ThinkingConfigAdaptiveParam to the thinking parameter type annotations across streaming and non-streaming interfaces.

Note for callers:
- This is a behavior change for existing Anthropic
  model callers. Previously, temperature, top_p, top_k, stop_sequences,
  and max_output_tokens were ignored (dropped) for Claude. They are now
  correctly propagated to the Anthropic client, and max_output_tokens
  will now correctly override the default max_tokens (8192).

Fixes: #5393
Closes: #5513

Co-authored-by: Yi Liu <yiliuly@google.com>
COPYBARA_INTEGRATE_REVIEW=#5513 from sebastienc:feat/anthropic-generation-config 0276484
PiperOrigin-RevId: 940074181

Author: 2 people

src/google/adk/models/__init__.py

@@ -27,6 +27,7 @@
 if TYPE_CHECKING:
   from google.adk.labs.openai import OpenAILlm
 
+  from .anthropic_llm import AnthropicGenerateContentConfig
   from .anthropic_llm import Claude
   from .apigee_llm import ApigeeLlm
   from .gemma_llm import Gemma
@@ -35,6 +36,7 @@
   from .lite_llm import LiteLlm
 
 __all__ = [
+    'AnthropicGenerateContentConfig',
     'ApigeeLlm',
     'BaseLlm',
     'Claude',
@@ -97,18 +99,27 @@
   LLMRegistry._register_lazy(_patterns, _target_module, _name)
 
 
+_OTHER_LAZY_IMPORTS: dict[str, str] = {
+    'AnthropicGenerateContentConfig': 'anthropic_llm',
+}
+
+
 def __getattr__(name: str):
   if name in _LAZY_PROVIDERS:
     module_name = _LAZY_PROVIDERS[name][1]
-    try:
-      if module_name.startswith('google.adk.'):
-        module = importlib.import_module(module_name)
-      else:
-        module = importlib.import_module(f'{__name__}.{module_name}')
-    except ImportError as e:
-      raise ImportError(
-          f'`{name}` requires an optional dependency that is not installed.'
-          ' Install with: pip install google-adk[extensions]'
-      ) from e
-    return getattr(module, name)
-  raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+  elif name in _OTHER_LAZY_IMPORTS:
+    module_name = _OTHER_LAZY_IMPORTS[name]
+  else:
+    raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+
+  try:
+    if module_name.startswith('google.adk.'):
+      module = importlib.import_module(module_name)
+    else:
+      module = importlib.import_module(f'{__name__}.{module_name}')
+  except ImportError as e:
+    raise ImportError(
+        f'`{name}` requires an optional dependency that is not installed.'
+        ' Install with: pip install google-adk[extensions]'
+    ) from e
+  return getattr(module, name)

src/google/adk/models/anthropic_llm.py

@@ -31,6 +31,7 @@
 from typing import Optional
 from typing import TYPE_CHECKING
 from typing import Union
+import warnings
 
 from anthropic import AsyncAnthropic
 from anthropic import AsyncAnthropicVertex
@@ -39,16 +40,19 @@
 from anthropic import types as anthropic_types
 from google.genai import types
 from pydantic import BaseModel
+from pydantic import Field
+from pydantic import model_validator
 from typing_extensions import override
 
 from ..utils._google_client_headers import get_tracking_headers
 from .base_llm import BaseLlm
+from .interactions_utils import extract_system_instruction
 from .llm_response import LlmResponse
 
 if TYPE_CHECKING:
   from .llm_request import LlmRequest
 
-__all__ = ["AnthropicLlm", "Claude"]
+__all__ = ["AnthropicLlm", "Claude", "AnthropicGenerateContentConfig"]
 
 logger = logging.getLogger("google_adk." + __name__)
 
@@ -98,6 +102,12 @@ def _build_anthropic_thinking_param(
       caller gets the canonical error message). Rejected by Claude Opus 4.7
       -- callers targeting 4.7+ must use a negative value (adaptive) or
       ``0`` (disabled).
+
+  Args:
+    config: Optional GenerateContentConfig object.
+
+  Returns:
+    Mapped thinking parameter or NotGiven.
   """
   if not config or not config.thinking_config:
     return NOT_GIVEN
@@ -130,6 +140,85 @@ def _build_anthropic_thinking_param(
   )
 
 
+class AnthropicGenerateContentConfig(types.GenerateContentConfig):
+  """Configuration options for Anthropic Claude content generation.
+
+  This specialized configuration class is the recommended way to
+  configure reasoning and extended thinking for newer Claude models.
+
+  Attributes:
+    effort: The reasoning effort level for adaptive extended thinking. Set
+      directly to guide the reasoning depth ("low", "medium", "high", "xhigh",
+      "max"). This is the preferred alternative to the deprecated manual
+      `thinking_budget` on newer Claude models.
+  """
+
+  effort: Optional[Literal["low", "medium", "high", "xhigh", "max"]] = Field(
+      default=None,
+      description=(
+          "Configures the Claude-specific reasoning effort level for adaptive"
+          " extended thinking. This is the recommended, future-proof way to"
+          " control reasoning depth on newer Claude models."
+      ),
+  )
+
+  @model_validator(mode="after")
+  def validate_no_thinking_level(self) -> "AnthropicGenerateContentConfig":
+    """Ensures thinking_level is not configured on Anthropic-specific config."""
+
+    if self.thinking_config and self.thinking_config.thinking_level is not None:
+      raise ValueError(
+          "thinking_level is not supported in AnthropicGenerateContentConfig. "
+          "Use the `effort` field directly to configure reasoning effort."
+      )
+    return self
+
+
+def _build_effort_param(
+    config: Optional[types.GenerateContentConfig],
+) -> Optional[str]:
+  """Extracts Anthropic's effort parameter from the configuration.
+
+  To configure a specific reasoning effort level for Anthropic models,
+  callers must use ``google.adk.models.AnthropicGenerateContentConfig`` and
+  set the ``effort`` field directly.
+  Using the standard ``thinking_config.thinking_level`` is explicitly
+  unsupported because the standard `ThinkingLevel` enum (4 levels) cannot map
+  consistently to Anthropic's 5 effort levels
+  ("low", "medium", "high", "xhigh", "max").
+
+  Any attempt to set `thinking_level` will not be passed to the model and will
+  log a warning.
+
+  If `effort` is not set, we return `None`.
+  If `effort` and `thinking_level` are both set, `effort` takes precedence.
+
+  Args:
+    config: Optional GenerateContentConfig object.
+
+  Returns:
+    The effort level string (e.g., "xhigh") if specified via
+    AnthropicGenerateContentConfig, or None.
+  """
+  if not config:
+    return None
+
+  if isinstance(config, AnthropicGenerateContentConfig) and config.effort:
+    return config.effort
+
+  # If effort is not set, but thinking_level is, log a warning and ignore it.
+  if config.thinking_config and config.thinking_config.thinking_level:
+    warnings.warn(
+        "Standard thinking_config.thinking_level is not supported for Anthropic"
+        " models and will be ignored. Use AnthropicGenerateContentConfig and"
+        " set the `effort` field directly to configure reasoning effort.",
+        category=UserWarning,
+        stacklevel=4,
+    )
+
+  return None
+
+
 class ClaudeRequest(BaseModel):
   system_instruction: str
   messages: Iterable[anthropic_types.MessageParam]
@@ -509,6 +598,14 @@ def function_declaration_to_tool_param(
 class AnthropicLlm(BaseLlm):
   """Integration with Claude models via the Anthropic API.
 
+  Note:
+    Anthropic Claude supports 5 distinct effort levels ("low", "medium",
+    "high", "xhigh", "max") while the standard `ThinkingLevel` enum defines 4
+    levels (MINIMAL, LOW, MEDIUM, HIGH), the standard
+    `thinking_config.thinking_level` is not supported for Anthropic models.
+    To configure thinking effort, user must use `AnthropicGenerateContentConfig`
+    and set its `effort` field directly (e.g., `effort="xhigh"`).
+
   Attributes:
     model: The name of the Claude model.
     max_tokens: The maximum number of tokens to generate.
@@ -534,11 +631,86 @@ def _resolve_model_name(self, model: Optional[str]) -> str:
         return match.group(1)
     return model
 
+  def _build_anthropic_kwargs(
+      self,
+      llm_request: LlmRequest,
+      messages: list[anthropic_types.MessageParam],
+      tools: Union[Iterable[anthropic_types.ToolUnionParam], NotGiven],
+      tool_choice: Union[anthropic_types.ToolChoiceParam, NotGiven],
+      thinking: Union[
+          anthropic_types.ThinkingConfigEnabledParam,
+          anthropic_types.ThinkingConfigDisabledParam,
+          anthropic_types.ThinkingConfigAdaptiveParam,
+          NotGiven,
+      ],
+  ) -> dict[str, Any]:
+    system = NOT_GIVEN
+    if llm_request.config:
+      system_str = extract_system_instruction(llm_request.config)
+      if system_str:
+        system = system_str
+
+    model_to_use = self._resolve_model_name(llm_request.model)
+    kwargs = {
+        "model": model_to_use,
+        "system": system,
+        "messages": messages,
+        "tools": tools,
+        "tool_choice": tool_choice,
+        "thinking": thinking,
+    }
+
+    effort = _build_effort_param(llm_request.config)
+    if effort:
+      kwargs["output_config"] = {"effort": effort}
+
+    # Determine if thinking is enabled to avoid parameter conflicts.
+    thinking_enabled = False
+    if thinking is not NOT_GIVEN and thinking is not None:
+      if isinstance(thinking, dict):
+        thinking_enabled = thinking.get("type") in ["enabled", "adaptive"]
+
+    exclude_sampling = thinking_enabled or (effort is not None)
+
+    if llm_request.config:
+      # Models released after Claude Opus 4.6 do not support setting
+      # temperature, top_k, or top_p when thinking is enabled or effort is set.
+      if not exclude_sampling:
+        if llm_request.config.temperature is not None:
+          kwargs["temperature"] = llm_request.config.temperature
+        if llm_request.config.top_p is not None:
+          kwargs["top_p"] = llm_request.config.top_p
+        if llm_request.config.top_k is not None:
+          kwargs["top_k"] = int(llm_request.config.top_k)
+      else:
+        if (
+            llm_request.config.temperature is not None
+            or llm_request.config.top_p is not None
+            or llm_request.config.top_k is not None
+        ):
+          warnings.warn(
+              "Sampling parameters (temperature, top_p, top_k) are ignored "
+              "because thinking/effort is enabled.",
+              category=UserWarning,
+              stacklevel=3,
+          )
+
+      if llm_request.config.stop_sequences:
+        kwargs["stop_sequences"] = llm_request.config.stop_sequences
+
+      if llm_request.config.max_output_tokens is not None:
+        kwargs["max_tokens"] = llm_request.config.max_output_tokens
+      else:
+        kwargs["max_tokens"] = self.max_tokens
+    else:
+      kwargs["max_tokens"] = self.max_tokens
+
+    return kwargs
+
   @override
   async def generate_content_async(
       self, llm_request: LlmRequest, stream: bool = False
   ) -> AsyncGenerator[LlmResponse, None]:
-    model_to_use = self._resolve_model_name(llm_request.model)
     sanitizer = _ToolUseIdSanitizer()
     messages = [
         _content_to_message_param(content, sanitizer)
@@ -560,55 +732,51 @@ async def generate_content_async(
         else NOT_GIVEN
     )
     thinking = _build_anthropic_thinking_param(llm_request.config)
-    system = NOT_GIVEN
-    if llm_request.config.system_instruction is not None:
-      system = llm_request.config.system_instruction
 
     if not stream:
-      message = await self._anthropic_client.messages.create(
-          model=model_to_use,
-          system=system,
-          messages=messages,
-          tools=tools,
-          tool_choice=tool_choice,
-          max_tokens=self.max_tokens,
-          thinking=thinking,
+      kwargs = self._build_anthropic_kwargs(
+          llm_request, messages, tools, tool_choice, thinking
       )
+      message = await self._anthropic_client.messages.create(**kwargs)
       yield message_to_generate_content_response(message)
     else:
       async for response in self._generate_content_streaming(
-          llm_request, messages, system, tools, tool_choice, thinking
+          llm_request, messages, tools, tool_choice, thinking
       ):
         yield response
 
   async def _generate_content_streaming(
       self,
       llm_request: LlmRequest,
       messages: list[anthropic_types.MessageParam],
-      system: Union[str, types.Content, NotGiven],
       tools: Union[Iterable[anthropic_types.ToolUnionParam], NotGiven],
       tool_choice: Union[anthropic_types.ToolChoiceParam, NotGiven],
       thinking: Union[
           anthropic_types.ThinkingConfigEnabledParam,
           anthropic_types.ThinkingConfigDisabledParam,
+          anthropic_types.ThinkingConfigAdaptiveParam,
           NotGiven,
       ] = NOT_GIVEN,
   ) -> AsyncGenerator[LlmResponse, None]:
     """Handles streaming responses from Anthropic models.
 
-    Yields partial LlmResponse objects as content arrives, followed by
-    a final aggregated LlmResponse with all content.
+    Args:
+      llm_request: LlmRequest containing configurations and contents.
+      messages: List of formatted Anthropic messages.
+      tools: Optional tool configurations.
+      tool_choice: Optional tool choice setting.
+      thinking: Optional thinking details.
+
+    Yields:
+      Partial LlmResponse objects as content arrives, followed by
+      a final aggregated LlmResponse with all content.
     """
-    model_to_use = self._resolve_model_name(llm_request.model)
+    kwargs = self._build_anthropic_kwargs(
+        llm_request, messages, tools, tool_choice, thinking
+    )
     raw_stream = await self._anthropic_client.messages.create(
-        model=model_to_use,
-        system=system,
-        messages=messages,
-        tools=tools,
-        tool_choice=tool_choice,
-        max_tokens=self.max_tokens,
         stream=True,
-        thinking=thinking,
+        **kwargs,
     )
 
     # Track content blocks being built during streaming.
@@ -730,6 +898,15 @@ def _anthropic_client(self) -> AsyncAnthropic:
 class Claude(AnthropicLlm):
   """Integration with Claude models served from Vertex AI.
 
+  Note:
+    Because Anthropic Claude supports 5 distinct effort levels ("low", "medium",
+    "high", "xhigh", "max") while the standard `ThinkingLevel` enum defines 4
+    levels (MINIMAL, LOW, MEDIUM, HIGH), the standard
+    `thinking_config.thinking_level` is not supported for Anthropic models.
+
+    To configure thinking effort, user must use `AnthropicGenerateContentConfig`
+    and set its `effort` field directly (e.g., `effort="xhigh"`).
+
   Attributes:
     model: The name of the Claude model.
     max_tokens: The maximum number of tokens to generate.