feat(anthropic): add effort support (#34116)

Author: mdrxy

libs/langchain/tests/unit_tests/chat_models/test_base.py

@@ -256,6 +256,7 @@ def test_configurable_with_default() -> None:
             "max_tokens": 64000,
             "temperature": None,
             "thinking": None,
+            "effort": None,
             "top_k": None,
             "top_p": None,
             "default_request_timeout": None,

libs/langchain_v1/tests/unit_tests/chat_models/test_chat_models.py

@@ -251,6 +251,7 @@ def test_configurable_with_default() -> None:
         "bound": {
             "name": None,
             "disable_streaming": False,
+            "effort": None,
             "model": "claude-sonnet-4-5-20250929",
             "mcp_servers": None,
             "max_tokens": 64000,

libs/partners/anthropic/langchain_anthropic/chat_models.py

@@ -75,8 +75,18 @@
 
 
 def _get_default_model_profile(model_name: str) -> ModelProfile:
-    default = _MODEL_PROFILES.get(model_name) or {}
-    return default.copy()
+    """Get the default profile for a model.
+
+    Args:
+        model_name: The model identifier.
+
+    Returns:
+        The model profile dictionary, or an empty dict if not found.
+    """
+    default = _MODEL_PROFILES.get(model_name)
+    if default:
+        return default.copy()
+    return {}
 
 
 _MODEL_DEFAULT_MAX_OUTPUT_TOKENS: Final[dict[str, int]] = {
@@ -1056,6 +1066,29 @@ def get_weather(location: str) -> str:
             Refer to the [Claude docs](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#differences-in-thinking-across-model-versions)
             for more info.
 
+    ???+ example "Effort"
+
+        Certain Claude models support an [effort](https://platform.claude.com/docs/en/build-with-claude/effort)
+        feature, which will control how many tokens Claude uses when responding.
+
+        !!! example
+
+            ```python hl_lines="6"
+            from langchain_anthropic import ChatAnthropic
+
+            model = ChatAnthropic(
+                model="claude-opus-4-5-20251101",
+                max_tokens=4096,
+                effort="medium",  # Options: "high", "medium", "low"
+            )
+
+            response = model.invoke("Analyze the trade-offs between microservices and monolithic architectures")
+            print(response.content)
+            ```
+
+        See the [Claude docs](https://platform.claude.com/docs/en/build-with-claude/effort)
+        for more detail on when to use different effort levels.
+
     ???+ example "Prompt caching"
 
         Prompt caching reduces processing time and costs for repetitive tasks or prompts
@@ -1638,26 +1671,40 @@ class Joke(BaseModel):
     e.g., `#!python {"type": "enabled", "budget_tokens": 10_000}`
     """
 
+    effort: Literal["high", "medium", "low"] | None = None
+    """Control how many tokens Claude uses when responding.
+
+    This parameter will be merged into the `output_config` parameter when making
+    API calls.
+
+    Example: `effort="medium"`
+
+    !!! note
+
+        Setting `effort` to `'high'` produces exactly the same behavior as omitting the
+        parameter altogether.
+
+    !!! note "Model Support"
+
+        This feature is currently only supported by Claude Opus 4.5.
+
+    !!! note "Automatic beta header"
+
+        The required `effort-2025-11-24` beta header is
+        automatically appended to the request when using `effort`, so you
+        don't need to manually specify it in the `betas` parameter.
+    """
+
     mcp_servers: list[dict[str, Any]] | None = None
     """List of MCP servers to use for the request.
 
     Example: `#!python mcp_servers=[{"type": "url", "url": "https://mcp.example.com/mcp",
     "name": "example-mcp"}]`
-
-    !!! note
-
-        This feature requires the beta header `'mcp-client-2025-11-20'` to be set in
-        [`betas`][langchain_anthropic.chat_models.ChatAnthropic.betas].
     """
 
     context_management: dict[str, Any] | None = None
     """Configuration for
     [context management](https://platform.claude.com/docs/en/build-with-claude/context-editing).
-
-    !!! note
-
-        This feature requires the beta header `'context-management-2025-06-27'` to be
-        set in [`betas`][langchain_anthropic.chat_models.ChatAnthropic.betas].
     """
 
     @property
@@ -1868,6 +1915,27 @@ def _get_request_payload(
         if self.thinking is not None:
             payload["thinking"] = self.thinking
 
+        # Handle output_config and effort parameter
+        # Priority: self.effort > payload output_config
+        output_config = payload.get("output_config", {})
+        output_config = output_config.copy() if isinstance(output_config, dict) else {}
+
+        if self.effort:
+            output_config["effort"] = self.effort
+
+        if output_config:
+            payload["output_config"] = output_config
+
+            # Auto-append required beta for effort
+            if "effort" in output_config:
+                required_beta = "effort-2025-11-24"
+                if payload["betas"]:
+                    # Merge with existing betas
+                    if required_beta not in payload["betas"]:
+                        payload["betas"] = [*payload["betas"], required_beta]
+                else:
+                    payload["betas"] = [required_beta]
+
         if "response_format" in payload:
             # response_format present when using agents.create_agent's ProviderStrategy
             # ---

libs/partners/anthropic/pyproject.toml

@@ -12,7 +12,7 @@ authors = []
 version = "1.2.0"
 requires-python = ">=3.10.0,<4.0.0"
 dependencies = [
-    "anthropic>=0.73.0,<1.0.0",
+    "anthropic>=0.75.0,<1.0.0",
     "langchain-core>=1.1.0,<2.0.0",
     "pydantic>=2.7.4,<3.0.0",
 ]

libs/partners/anthropic/tests/integration_tests/test_chat_models.py

@@ -1152,6 +1152,30 @@ def test_structured_output_thinking_force_tool_use() -> None:
         llm.invoke("Generate a username for Sally with green hair")
 
 
+def test_effort_parameter() -> None:
+    """Test that effort parameter can be passed without errors.
+
+    Only Opus 4.5 supports currently.
+    """
+    llm = ChatAnthropic(
+        model="claude-opus-4-5-20251101",
+        effort="medium",
+        max_tokens=100,
+    )
+
+    result = llm.invoke("Say hello in one sentence")
+
+    # Verify we got a response
+    assert isinstance(result.content, str)
+    assert len(result.content) > 0
+
+    # Verify response metadata is present
+    assert "model_name" in result.response_metadata
+    assert result.usage_metadata is not None
+    assert result.usage_metadata["input_tokens"] > 0
+    assert result.usage_metadata["output_tokens"] > 0
+
+
 def test_image_tool_calling() -> None:
     """Test tool calling with image inputs."""
 

libs/partners/anthropic/tests/unit_tests/test_chat_models.py

@@ -16,7 +16,7 @@
 from langchain_core.tools import BaseTool
 from langchain_core.tracers.base import BaseTracer
 from langchain_core.tracers.schemas import Run
-from pydantic import BaseModel, Field, SecretStr
+from pydantic import BaseModel, Field, SecretStr, ValidationError
 from pytest import CaptureFixture, MonkeyPatch
 
 from langchain_anthropic import ChatAnthropic
@@ -1906,3 +1906,109 @@ async def test_model_profile_not_blocking() -> None:
     with blockbuster_ctx():
         model = ChatAnthropic(model="claude-sonnet-4-5")
         _ = model.profile
+
+
+def test_effort_parameter_validation() -> None:
+    """Test that effort parameter is validated correctly.
+
+    The effort parameter is currently in beta and only supported by Claude Opus 4.5.
+    """
+    # Valid effort values should work
+    model = ChatAnthropic(model="claude-opus-4-5-20251101", effort="high")
+    assert model.effort == "high"
+
+    model = ChatAnthropic(model="claude-opus-4-5-20251101", effort="medium")
+    assert model.effort == "medium"
+
+    model = ChatAnthropic(model="claude-opus-4-5-20251101", effort="low")
+    assert model.effort == "low"
+
+    # Invalid effort values should raise ValidationError
+    with pytest.raises(ValidationError, match="Input should be"):
+        ChatAnthropic(model="claude-opus-4-5-20251101", effort="invalid")  # type: ignore[arg-type]
+
+
+def test_effort_populates_betas() -> None:
+    """Test that effort parameter auto-populates required betas."""
+    model = ChatAnthropic(model="claude-opus-4-5-20251101", effort="medium")
+    assert model.effort == "medium"
+
+    # Test that effort works with dated API ID
+    payload = model._get_request_payload("Test query")
+    assert payload["output_config"]["effort"] == "medium"
+    assert "effort-2025-11-24" in payload["betas"]
+
+
+def test_effort_in_output_config() -> None:
+    """Test that effort can be specified in `output_config`."""
+    # Test valid effort in output_config
+    model = ChatAnthropic(
+        model="claude-opus-4-5-20251101",
+        output_config={"effort": "low"},
+    )
+    assert model.model_kwargs["output_config"] == {"effort": "low"}
+
+
+def test_effort_priority() -> None:
+    """Test that top-level effort takes precedence over `output_config`."""
+    model = ChatAnthropic(
+        model="claude-opus-4-5-20251101",
+        effort="high",
+        output_config={"effort": "low"},
+    )
+
+    # Top-level effort should take precedence in the payload
+    payload = model._get_request_payload("Test query")
+    assert payload["output_config"]["effort"] == "high"
+
+
+def test_effort_beta_header_auto_append() -> None:
+    """Test that effort beta header is automatically appended."""
+    # Test with top-level effort parameter
+    model = ChatAnthropic(model="claude-opus-4-5-20251101", effort="medium")
+    payload = model._get_request_payload("Test query")
+    assert "effort-2025-11-24" in payload["betas"]
+
+    # Test with output_config
+    model = ChatAnthropic(
+        model="claude-opus-4-5-20251101",
+        output_config={"effort": "low"},
+    )
+    payload = model._get_request_payload("Test query")
+    assert "effort-2025-11-24" in payload["betas"]
+
+    # Test that beta is not duplicated if already present
+    model = ChatAnthropic(
+        model="claude-opus-4-5-20251101",
+        effort="high",
+        betas=["effort-2025-11-24"],
+    )
+    payload = model._get_request_payload("Test query")
+    assert payload["betas"].count("effort-2025-11-24") == 1
+
+    # Test combining effort with other betas
+    model = ChatAnthropic(
+        model="claude-opus-4-5-20251101",
+        effort="medium",
+        betas=["context-1m-2025-08-07"],
+    )
+    payload = model._get_request_payload("Test query")
+    assert set(payload["betas"]) == {
+        "context-1m-2025-08-07",
+        "effort-2025-11-24",
+    }
+
+
+def test_output_config_without_effort() -> None:
+    """Test that output_config can be used without effort."""
+    # output_config might have other fields in the future
+    model = ChatAnthropic(
+        model=MODEL_NAME,
+        output_config={"some_future_param": "value"},
+    )
+    payload = model._get_request_payload("Test query")
+    assert payload["output_config"] == {"some_future_param": "value"}
+    # No effort beta should be added
+    assert payload.get("betas") is None or "effort-2025-11-24" not in payload.get(
+        "betas", []
+    )