fix: simplify anthropic structured output flow

Author: fengju0213

PR_DESCRIPTION_fix_anthropic.md

@@ -0,0 +1,38 @@
+# PR Description
+
+## Summary
+- Simplify `AnthropicModel` structured output handling by removing the legacy beta structured-outputs path and keeping the stable `messages.create + output_config` flow.
+- Update the Anthropic structured output example to better match real third-party Anthropic-compatible endpoints by supporting configurable base URL/model, using a local fallback token counter, and documenting a successful combined `response_format + tools` run.
+
+## What Changed
+- `camel/models/anthropic_model.py`
+  - Removed the legacy `use_beta_for_structured_outputs` constructor argument and internal beta-header branch.
+  - Removed the `ANTHROPIC_BETA_FOR_STRUCTURED_OUTPUTS` constant.
+  - Unified sync and async execution onto the standard `messages.create` path.
+- `test/models/test_anthropic_model.py`
+  - Removed beta structured-output compatibility tests that no longer apply.
+  - Kept the tests that validate the current `output_config` request shape and tool/schema handling.
+- `docs/mintlify/reference/camel.models.anthropic_model.mdx`
+  - Removed the obsolete `use_beta_for_structured_outputs` parameter from the generated reference text.
+- `examples/models/anthropic_structured_output_example.py`
+  - Simplified the example to a single combined scenario: Anthropic structured output plus tool use.
+  - Added support for `ANTHROPIC_API_BASE_URL` and `ANTHROPIC_MODEL` so the example can run against Anthropic-compatible platforms.
+  - Added a local fallback token counter (`OpenAITokenCounter(ModelType.GPT_4O_MINI)`) with an inline comment explaining why third-party compatible endpoints may need it.
+  - Added a minimal explicit `max_tokens` config for compatibility with endpoints that require it.
+  - Appended a real sample output block showing the raw JSON response, parsed object, parsed JSON, and tool calls.
+
+## Testing
+- `python3 -m py_compile camel/models/anthropic_model.py test/models/test_anthropic_model.py`: passed
+- `python3 -m py_compile examples/models/anthropic_structured_output_example.py`: passed
+- `ANTHROPIC_API_KEY=... ANTHROPIC_API_BASE_URL='https://zenmux.ai/api/anthropic' ANTHROPIC_MODEL='claude-opus-4-6' uv run --extra model_platforms python examples/models/anthropic_structured_output_example.py`: passed
+  - Verified `response_format + tools` together
+  - Verified parsed Pydantic output was populated
+  - Verified tool calls were executed and recorded
+
+## Risks / Compatibility
+- This removes the explicit legacy beta structured-output fallback from `AnthropicModel`. Environments that still depend on the old beta header path will need to migrate to the standard `output_config` flow.
+- The example now documents a third-party compatible endpoint workaround via a local fallback token counter. That change is limited to the example and does not alter the shared token counting implementation.
+
+## Out of Scope
+- No broader changes to token counting behavior across the Anthropic backend.
+- No changes to unrelated model backends or shared structured output APIs.

camel/models/anthropic_model.py

@@ -33,7 +33,6 @@
     update_langfuse_trace,
 )
 
-ANTHROPIC_BETA_FOR_STRUCTURED_OUTPUTS = "structured-outputs-2025-11-13"
 ANTHROPIC_SUPPORTED_STRING_FORMATS = {
     "date",
     "date-time",
@@ -137,9 +136,6 @@ class AnthropicModel(BaseModelBackend):
         async_client (Optional[Any], optional): A custom asynchronous Anthropic
             client instance. If provided, this client will be used instead of
             creating a new one. (default: :obj:`None`)
-        use_beta_for_structured_outputs (bool, optional): Whether to send the
-            legacy beta header for structured outputs for backward-compatible
-            endpoints. (default: :obj:`False`)
         **kwargs (Any): Additional arguments to pass to the client
             initialization.
     """
@@ -161,7 +157,6 @@ def __init__(
         max_retries: int = 3,
         client: Optional[Any] = None,
         async_client: Optional[Any] = None,
-        use_beta_for_structured_outputs: bool = False,
         **kwargs: Any,
     ) -> None:
         if model_config_dict is None:
@@ -220,8 +215,6 @@ def __init__(
                 "ttl": cache_control,
             }
 
-        self._use_beta_for_structured_outputs = use_beta_for_structured_outputs
-
     @property
     def token_counter(self) -> BaseTokenCounter:
         r"""Initialize the token counter for the model backend.
@@ -890,12 +883,7 @@ def _run(
             if tool_choice is not None:
                 request_params["tool_choice"] = tool_choice
 
-        # Add beta for structured outputs if configured
-        if self._use_beta_for_structured_outputs:
-            request_params["betas"] = [ANTHROPIC_BETA_FOR_STRUCTURED_OUTPUTS]
-            create_func = self._client.beta.messages.create
-        else:
-            create_func = self._client.messages.create
+        create_func = self._client.messages.create
 
         # Check if streaming
         is_streaming = self.model_config_dict.get("stream", False)
@@ -1034,12 +1022,7 @@ async def _arun(
             if tool_choice is not None:
                 request_params["tool_choice"] = tool_choice
 
-        # Add beta for structured outputs if configured
-        if self._use_beta_for_structured_outputs:
-            request_params["betas"] = [ANTHROPIC_BETA_FOR_STRUCTURED_OUTPUTS]
-            create_func = self._async_client.beta.messages.create
-        else:
-            create_func = self._async_client.messages.create
+        create_func = self._async_client.messages.create
 
         # Check if streaming
         is_streaming = self.model_config_dict.get("stream", False)

docs/mintlify/reference/camel.models.anthropic_model.mdx

@@ -42,7 +42,7 @@ Anthropic API in a unified BaseModelBackend interface.
 - **max_retries** (int, optional): Maximum number of retries for API calls. (default: :obj:`3`)
 - **client** (Optional[Any], optional): A custom synchronous Anthropic client instance. If provided, this client will be used instead of creating a new one. (default: :obj:`None`)
 - **async_client** (Optional[Any], optional): A custom asynchronous Anthropic client instance. If provided, this client will be used instead of creating a new one. (default: :obj:`None`)
-- **use_beta_for_structured_outputs** (bool, optional): Whether to use the beta API for structured outputs. (default: :obj:`False`) **kwargs (Any): Additional arguments to pass to the client initialization.
+- **kwargs** (Any): Additional arguments to pass to the client initialization.
 
 <a id="camel.models.anthropic_model.AnthropicModel.__init__"></a>
 
@@ -60,7 +60,6 @@ def __init__(
     max_retries: int = 3,
     client: Optional[Any] = None,
     async_client: Optional[Any] = None,
-    use_beta_for_structured_outputs: bool = False,
     **kwargs: Any
 ):
 ```

examples/models/anthropic_structured_output_example.py

@@ -15,15 +15,12 @@
 """
 Anthropic structured output + tool use example for CAMEL.
 
-This single example focuses on the most important combined scenario:
-Anthropic tool calling and ``response_format`` in the same request.
-
 Required environment variable:
     export ANTHROPIC_API_KEY="<your-anthropic-api-key>"
 
 Optional environment variables:
     export ANTHROPIC_API_BASE_URL="<your-anthropic-compatible-base-url>"
-    export ANTHROPIC_USE_BETA_STRUCTURED_OUTPUTS="true"
+    export ANTHROPIC_MODEL="<your-anthropic-model>"
 
 Run:
     python3 examples/models/anthropic_structured_output_example.py
@@ -35,8 +32,9 @@
 from pydantic import BaseModel, Field
 
 from camel.agents import ChatAgent
-from camel.configs import AnthropicConfig
 from camel.models import AnthropicModel
+from camel.types import ModelType
+from camel.utils import OpenAITokenCounter
 
 
 class TripDecision(BaseModel):
@@ -124,22 +122,18 @@ def build_anthropic_model() -> AnthropicModel:
         )
 
     base_url = os.environ.get("ANTHROPIC_API_BASE_URL")
-    use_beta_for_structured_outputs = (
-        os.environ.get("ANTHROPIC_USE_BETA_STRUCTURED_OUTPUTS", "")
-        .strip()
-        .lower()
-        == "true"
+    model_type = os.environ.get("ANTHROPIC_MODEL") or (
+        "anthropic/claude-sonnet-4.5"
     )
 
     return AnthropicModel(
-        model_type="anthropic/claude-sonnet-4.5",
+        model_type=model_type,
         api_key=api_key,
         url=base_url,
-        use_beta_for_structured_outputs=use_beta_for_structured_outputs,
-        model_config_dict=AnthropicConfig(
-            temperature=0.0,
-            max_tokens=800,
-        ).as_dict(),
+        # Third-party Anthropic-compatible platforms may require a local
+        # fallback token counter instead of Anthropic's count_tokens API.
+        token_counter=OpenAITokenCounter(ModelType.GPT_4O_MINI),
+        model_config_dict={"max_tokens": 800},
     )
 
 
@@ -187,3 +181,30 @@ def main() -> None:
 
 if __name__ == "__main__":
     main()
+
+"""
+===============================================================================
+=== Raw Content ===
+{"recommended_area":"Higashiyama","estimated_total_budget_rmb":1100,"must_visit_spot":"Kiyomizu-dera","transport_tip":"Take a bus or taxi early in the morning to avoid crowds and save time-consider a Kyoto Bus One-Day Pass for unlimited rides."}
+
+=== Parsed Object ===
+recommended_area='Higashiyama' estimated_total_budget_rmb=1100
+must_visit_spot='Kiyomizu-dera' transport_tip='Take a bus or taxi early in
+the morning to avoid crowds and save time-consider a Kyoto Bus One-Day Pass
+for unlimited rides.'
+
+=== Parsed JSON ===
+{
+  "recommended_area": "Higashiyama",
+  "estimated_total_budget_rmb": 1100,
+  "must_visit_spot": "Kiyomizu-dera",
+  "transport_tip": "Take a bus or taxi early in the morning to avoid crowds and save time-consider a Kyoto Bus One-Day Pass for unlimited rides."
+}
+
+=== Tool Calls ===
+- lookup_kyoto_area args={'area': 'Higashiyama'} result={'must_visit_spot':
+'Kiyomizu-dera', 'transport_tip': 'Take a bus or taxi early in the morning.'}
+- estimate_kyoto_budget args={'days': 2, 'hotel_tier': 'budget'}
+result={'total_budget_rmb': 1100}
+===============================================================================
+"""

test/models/test_anthropic_model.py

@@ -20,7 +20,6 @@
 from camel.configs import AnthropicConfig
 from camel.models import AnthropicModel
 from camel.models.anthropic_model import (
-    ANTHROPIC_BETA_FOR_STRUCTURED_OUTPUTS,
     strip_trailing_whitespace_from_messages,
 )
 from camel.types import ModelType
@@ -610,17 +609,6 @@ def test_convert_stream_chunk_message_stop():
     assert result.choices[0].finish_reason == "stop"
 
 
-def test_use_beta_for_structured_outputs():
-    """Test that beta API is used when configured."""
-    model = AnthropicModel(
-        ModelType.CLAUDE_HAIKU_4_5,
-        api_key="dummy_api_key",
-        use_beta_for_structured_outputs=True,
-    )
-
-    assert model._use_beta_for_structured_outputs is True
-
-
 def test_build_output_config_enforces_additional_properties_false():
     """Test output_config generation for structured outputs."""
     model = AnthropicModel(
@@ -840,36 +828,3 @@ async def test_arun_passes_output_config_tool_choice_and_extra_fields():
         ]["description"]
         == "Must be at least 3 characters long."
     )
-
-
-def test_run_uses_beta_endpoint_for_legacy_structured_outputs_flag():
-    """Test legacy beta header path still works when explicitly enabled."""
-    mock_client = MagicMock()
-    mock_async_client = MagicMock()
-
-    mock_response = MagicMock()
-    mock_response.content = [{"type": "text", "text": '{"city":"Kyoto"}'}]
-    mock_response.stop_reason = "end_turn"
-    mock_response.id = "msg_structured_beta"
-    mock_response.usage = MagicMock()
-    mock_response.usage.input_tokens = 8
-    mock_response.usage.output_tokens = 3
-    mock_client.beta.messages.create.return_value = mock_response
-
-    model = AnthropicModel(
-        ModelType.CLAUDE_HAIKU_4_5,
-        model_config_dict=AnthropicConfig(max_tokens=64).as_dict(),
-        api_key="dummy_api_key",
-        client=mock_client,
-        async_client=mock_async_client,
-        use_beta_for_structured_outputs=True,
-    )
-
-    model._run(
-        messages=[{"role": "user", "content": "Plan a trip"}],
-        response_format=TravelResponse,
-    )
-
-    request_kwargs = mock_client.beta.messages.create.call_args.kwargs
-    assert request_kwargs["betas"] == [ANTHROPIC_BETA_FOR_STRUCTURED_OUTPUTS]
-    assert request_kwargs["output_config"]["format"]["type"] == "json_schema"