fix(deepseek): use native /anthropic/v1/messages endpoint and sanitize tools

[mateo-berri]

Copy of #28176 onto a litellm_-prefixed branch so CircleCI runs against litellm_internal_staging (only branches prefixed with litellm_ on BerriAI/litellm — not forks — trigger CI).

Original author: @FelipeRodriguesGare
Original PR: #28176

---

Changes

This PR adds a handler for DeepSeek's Anthropic-compatible APIs. DeepSeek already has an endpoint that is Anthropic-compatible, but the current implementation was falling back to the general handler and thus throwing errors for DeepSeek on Claude Code.

• Adds a DeepSeek-specific Anthropic Messages config so deepseek/... models use the native messages endpoint and preserve thinking blocks.
• Strips Anthropic custom tool type markers that DeepSeek rejects while keeping hosted tool types intact.
• Normalizes OpenAI-style DeepSeek api_base values ending in /v1 or /v1/messages by stripping those suffixes before adding the /anthropic messages path.
• Adds test package markers and tests under tests/test_litellm/llms/deepseek/messages/.

Type

Bug Fix

Slack Thread

  

[mateo-berri]

@greptileai

[greptile-apps]

Greptile Summary

This PR adds a DeepSeekAnthropicMessagesConfig class that routes deepseek/ models through DeepSeek's native Anthropic-compatible /anthropic/v1/messages endpoint instead of the general handler, fixing failures in Claude Code and similar clients that use the Anthropic Messages API shape.

• Introduces litellm/llms/deepseek/messages/transformation.py with URL normalization logic, a _sanitize_tools_for_deepseek helper that strips Anthropic's type: "custom" discriminator, and a header environment validator; wires the new config into ProviderConfigManager.get_provider_anthropic_messages_config in utils.py.
• Adds pure unit tests (no network calls) under tests/test_litellm/llms/deepseek/messages/ covering URL normalization, header injection, provider dispatch, and tool sanitization; also fixes a flaky Unicode-normalization assertion in an existing realtime test.

Confidence Score: 5/5

Safe to merge; changes are additive, well-tested, and follow established patterns in the codebase.

The new DeepSeek Anthropic Messages config is a self-contained subclass of the existing AnthropicMessagesConfig, touching no existing provider paths. The URL normalisation logic correctly handles all documented input shapes, the tool sanitiser is a straightforward key-removal, and the utils.py dispatch mirrors the existing pattern for Minimax and other providers. The realtime test fix is a non-weakening Unicode normalisation. No existing behaviour is altered.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/llms/deepseek/messages/transformation.py	New provider config: URL normalisation, tool sanitisation, and header injection for DeepSeek's Anthropic-compatible endpoint — logic is correct and well-tested.
litellm/utils.py	Thin dispatch added to ProviderConfigManager following the same pattern as other providers; no logic concerns.
tests/test_litellm/llms/deepseek/messages/test_deepseek_anthropic_messages_transformation.py	Unit tests are all mock-only with good coverage of URL normalisation, header injection, tool sanitisation, and provider dispatch; one edge case (fully-qualified api_base ending in /anthropic/v1/messages) is not exercised but the production code handles it correctly.
tests/llm_translation/realtime/test_realtime_guardrails_openai.py	Unicode-normalises smart quotes/apostrophes before checking safe_markers; legitimate flakiness fix that does not weaken assertions.

_{Reviews (6): Last reviewed commit: "fix(deepseek): strip /beta suffix in ant..." | Re-trigger Greptile}

[greptile-apps]

Greptile Summary

This PR fixes DeepSeek on Claude Code by introducing DeepSeekAnthropicMessagesConfig, a subclass of AnthropicMessagesConfig that routes deepseek/… models through DeepSeek's native /anthropic/v1/messages endpoint instead of the generic fallback handler.

• Adds DeepSeekAnthropicMessagesConfig with URL normalization (handles OpenAI-style /v1 or /v1/messages suffixes), correct x-api-key header injection, and a _sanitize_tools_for_deepseek helper that strips the type: \"custom\" discriminator that DeepSeek rejects while preserving hosted tool types.
• Wires the new config into ProviderConfigManager.get_provider_anthropic_messages_config alongside the existing Bedrock/Vertex/Azure/Minimax entries, and backs it with pure unit tests that cover URL normalization, header validation, tool sanitization, and provider-config dispatch.

Confidence Score: 4/5

Safe to merge; the change is additive and isolated to a new provider config that was previously non-functional.

The implementation is correct for all tested URL forms and the tool sanitisation logic is sound. Two small gaps in transformation.py — the substring-only /anthropic check and the missing DEEPSEEK_API_BASE fallback — could surprise users with custom proxies but won't affect anyone using the official DeepSeek endpoint.

litellm/llms/deepseek/messages/transformation.py — the URL normalisation logic and env-var fallback chain are worth a second look before merge.

Important Files Changed

Filename	Overview
litellm/llms/deepseek/messages/transformation.py	New DeepSeekAnthropicMessagesConfig: routes deepseek models to the native /anthropic endpoint, strips type: custom tools, and normalises api_base. URL normalisation uses simple substring detection for /anthropic that could misfire on paths like /anthropic-compat.
litellm/utils.py	Adds DeepSeek branch to get_provider_anthropic_messages_config; consistent with existing Minimax/Azure/Bedrock pattern.
tests/test_litellm/llms/deepseek/messages/test_deepseek_anthropic_messages_transformation.py	Pure unit tests covering URL normalisation, header validation, tool sanitisation, and provider config dispatch — no real network calls.

_{Reviews (2): Last reviewed commit: "chore(deepseek): add test package marker..." | Re-trigger Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 94.82759% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/llms/deepseek/messages/transformation.py	94.54%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[mateo-berri]

@greptileai

[mateo-berri]

@greptileai

[mateo-berri]

@greptileai

[cursor]

Cursor Bugbot has reviewed your changes using high mode and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: URL normalization misses /beta suffix from DeepSeek base
  • Added a /beta suffix strip in get_complete_url so that a DEEPSEEK_API_BASE ending in /beta is normalized before appending /anthropic/v1/messages.

Preview (7cf68906ba)

diff --git a/litellm/llms/deepseek/messages/transformation.py b/litellm/llms/deepseek/messages/transformation.py
new file mode 100644
--- /dev/null
+++ b/litellm/llms/deepseek/messages/transformation.py
@@ -1,0 +1,133 @@
+"""
+DeepSeek Anthropic-compatible messages transformation config.
+"""
+
+from typing import Any, Dict, List, Optional, Tuple
+
+import litellm
+from litellm.llms.anthropic.experimental_pass_through.messages.transformation import (
+    AnthropicMessagesConfig,
+)
+from litellm.secret_managers.main import get_secret_str
+from litellm.types.router import GenericLiteLLMParams
+
+
+class DeepSeekAnthropicMessagesConfig(AnthropicMessagesConfig):
+    """
+    DeepSeek exposes an Anthropic-compatible Messages API at
+    https://api.deepseek.com/anthropic.
+
+    It accepts the native Anthropic Messages conversation shape, including
+    thinking blocks in assistant history, but rejects Anthropic's explicit
+    custom-tool discriminator (`{"type": "custom"}`).
+    """
+
+    @property
+    def custom_llm_provider(self) -> Optional[str]:
+        return "deepseek"
+
+    @staticmethod
+    def get_api_key(api_key: Optional[str] = None) -> Optional[str]:
+        return api_key or get_secret_str("DEEPSEEK_API_KEY") or litellm.api_key
+
+    @staticmethod
+    def get_api_base(api_base: Optional[str] = None) -> str:
+        return (
+            api_base
+            or get_secret_str("DEEPSEEK_ANTHROPIC_API_BASE")
+            or get_secret_str("DEEPSEEK_API_BASE")
+            or "https://api.deepseek.com/anthropic"
+        )
+
+    def validate_anthropic_messages_environment(
+        self,
+        headers: dict,
+        model: str,
+        messages: List[Any],
+        optional_params: dict,
+        litellm_params: dict,
+        api_key: Optional[str] = None,
+        api_base: Optional[str] = None,
+    ) -> Tuple[dict, Optional[str]]:
+        dynamic_api_key = self.get_api_key(api_key=api_key)
+
+        if (
+            "x-api-key" not in headers
+            and "authorization" not in headers
+            and dynamic_api_key is not None
+        ):
+            headers["x-api-key"] = dynamic_api_key
+
+        if "anthropic-version" not in headers:
+            headers["anthropic-version"] = "2023-06-01"
+        if "content-type" not in headers:
+            headers["content-type"] = "application/json"
+
+        headers = self._update_headers_with_anthropic_beta(
+            headers=headers,
+            optional_params=optional_params,
+            custom_llm_provider=self.custom_llm_provider or "deepseek",
+        )
+
+        return headers, api_base
+
+    def get_complete_url(
+        self,
+        api_base: Optional[str],
+        api_key: Optional[str],
+        model: str,
+        optional_params: dict,
+        litellm_params: dict,
+        stream: Optional[bool] = None,
+    ) -> str:
+        base_url = self.get_api_base(api_base=api_base).rstrip("/")
+
+        if base_url.endswith("/v1/messages") and "/anthropic/" in base_url:
+            return base_url
+        if base_url.endswith("/v1/messages"):
+            base_url = base_url[: -len("/v1/messages")]
+        if base_url.endswith("/v1"):
+            base_url = base_url[: -len("/v1")]
+        if base_url.endswith("/beta"):
+            base_url = base_url[: -len("/beta")]
+
+        if not base_url.endswith("/anthropic") and "/anthropic/" not in base_url:
+            base_url = f"{base_url}/anthropic"
+
+        return f"{base_url}/v1/messages"
+
+    @staticmethod
+    def _sanitize_tools_for_deepseek(tools: Any) -> Any:
+        if not isinstance(tools, list):
+            return tools
+
+        sanitized_tools = []
+        for tool in tools:
+            if isinstance(tool, dict) and tool.get("type") == "custom":
+                sanitized_tool = dict(tool)
+                sanitized_tool.pop("type", None)
+                sanitized_tools.append(sanitized_tool)
+            else:
+                sanitized_tools.append(tool)
+        return sanitized_tools
+
+    def transform_anthropic_messages_request(
+        self,
+        model: str,
+        messages: List[Dict],
+        anthropic_messages_optional_request_params: Dict,
+        litellm_params: GenericLiteLLMParams,
+        headers: dict,
+    ) -> Dict:
+        anthropic_messages_request = super().transform_anthropic_messages_request(
+            model=model,
+            messages=messages,
+            anthropic_messages_optional_request_params=anthropic_messages_optional_request_params,
+            litellm_params=litellm_params,
+            headers=headers,
+        )
+        if "tools" in anthropic_messages_request:
+            anthropic_messages_request["tools"] = self._sanitize_tools_for_deepseek(
+                anthropic_messages_request["tools"]
+            )
+        return anthropic_messages_request

diff --git a/litellm/utils.py b/litellm/utils.py
--- a/litellm/utils.py
+++ b/litellm/utils.py
@@ -8539,6 +8539,12 @@
             )
 
             return MinimaxMessagesConfig()
+        elif litellm.LlmProviders.DEEPSEEK == provider:
+            from litellm.llms.deepseek.messages.transformation import (
+                DeepSeekAnthropicMessagesConfig,
+            )
+
+            return DeepSeekAnthropicMessagesConfig()
         return None
 
     @staticmethod

diff --git a/tests/llm_translation/realtime/test_realtime_guardrails_openai.py b/tests/llm_translation/realtime/test_realtime_guardrails_openai.py
--- a/tests/llm_translation/realtime/test_realtime_guardrails_openai.py
+++ b/tests/llm_translation/realtime/test_realtime_guardrails_openai.py
@@ -232,8 +232,15 @@
                 assert (
                     BLOCKED_PHRASE not in real_ai_text
                 ), f"Blocked phrase leaked into AI response: {real_ai_text!r}"
+                normalized_ai_text = (
+                    real_ai_text.lower()
+                    .replace("\u2019", "'")
+                    .replace("\u2018", "'")
+                    .replace("\u201c", '"')
+                    .replace("\u201d", '"')
+                )
                 assert any(
-                    marker in real_ai_text.lower() for marker in safe_markers
+                    marker in normalized_ai_text for marker in safe_markers
                 ), f"AI responded with non-guardrail content even though message was blocked: {real_ai_text!r}"
 
     finally:

diff --git a/tests/test_litellm/llms/deepseek/__init__.py b/tests/test_litellm/llms/deepseek/__init__.py
new file mode 100644

diff --git a/tests/test_litellm/llms/deepseek/messages/__init__.py b/tests/test_litellm/llms/deepseek/messages/__init__.py
new file mode 100644

diff --git a/tests/test_litellm/llms/deepseek/messages/test_deepseek_anthropic_messages_transformation.py b/tests/test_litellm/llms/deepseek/messages/test_deepseek_anthropic_messages_transformation.py
new file mode 100644
--- /dev/null
+++ b/tests/test_litellm/llms/deepseek/messages/test_deepseek_anthropic_messages_transformation.py
@@ -1,0 +1,189 @@
+import litellm
+from litellm.llms.anthropic.experimental_pass_through.messages.transformation import (
+    AnthropicMessagesConfig,
+)
+from litellm.llms.deepseek.messages.transformation import (
+    DeepSeekAnthropicMessagesConfig,
+)
+from litellm.types.router import GenericLiteLLMParams
+from litellm.utils import ProviderConfigManager
+
+
+def test_deepseek_provider_uses_anthropic_messages_config():
+    config = ProviderConfigManager.get_provider_anthropic_messages_config(
+        model="deepseek-v4-pro",
+        provider=litellm.LlmProviders.DEEPSEEK,
+    )
+
+    assert isinstance(config, DeepSeekAnthropicMessagesConfig)
+    assert config.custom_llm_provider == "deepseek"
+
+
+def test_deepseek_anthropic_messages_config_defaults():
+    config = DeepSeekAnthropicMessagesConfig()
+
+    assert config.custom_llm_provider == "deepseek"
+    assert config.get_api_base() == "https://api.deepseek.com/anthropic"
+
+
+def test_anthropic_provider_keeps_default_config_for_deepseek_named_model():
+    config = ProviderConfigManager.get_provider_anthropic_messages_config(
+        model="deepseek-v4-pro",
+        provider=litellm.LlmProviders.ANTHROPIC,
+    )
+
+    assert isinstance(config, AnthropicMessagesConfig)
+    assert not isinstance(config, DeepSeekAnthropicMessagesConfig)
+
+
+def test_deepseek_anthropic_messages_url_defaults_to_anthropic_endpoint():
+    config = DeepSeekAnthropicMessagesConfig()
+
+    assert (
+        config.get_complete_url(
+            api_base=None,
+            api_key=None,
+            model="deepseek-v4-pro",
+            optional_params={},
+            litellm_params={},
+        )
+        == "https://api.deepseek.com/anthropic/v1/messages"
+    )
+    assert (
+        config.get_complete_url(
+            api_base="https://api.deepseek.com/anthropic/v1",
+            api_key=None,
+            model="deepseek-v4-pro",
+            optional_params={},
+            litellm_params={},
+        )
+        == "https://api.deepseek.com/anthropic/v1/messages"
+    )
+    assert (
+        config.get_complete_url(
+            api_base="https://api.deepseek.com/anthropic",
+            api_key=None,
+            model="deepseek-v4-pro",
+            optional_params={},
+            litellm_params={},
+        )
+        == "https://api.deepseek.com/anthropic/v1/messages"
+    )
+    assert (
+        config.get_complete_url(
+            api_base="https://api.deepseek.com",
+            api_key=None,
+            model="deepseek-v4-pro",
+            optional_params={},
+            litellm_params={},
+        )
+        == "https://api.deepseek.com/anthropic/v1/messages"
+    )
+    assert (
+        config.get_complete_url(
+            api_base="https://api.deepseek.com/v1",
+            api_key=None,
+            model="deepseek-v4-pro",
+            optional_params={},
+            litellm_params={},
+        )
+        == "https://api.deepseek.com/anthropic/v1/messages"
+    )
+    assert (
+        config.get_complete_url(
+            api_base="https://api.deepseek.com/v1/messages",
+            api_key=None,
+            model="deepseek-v4-pro",
+            optional_params={},
+            litellm_params={},
+        )
+        == "https://api.deepseek.com/anthropic/v1/messages"
+    )
+
+
+def test_deepseek_anthropic_messages_headers_use_deepseek_key():
+    config = DeepSeekAnthropicMessagesConfig()
+
+    headers, api_base = config.validate_anthropic_messages_environment(
+        headers={},
+        model="deepseek-v4-pro",
+        messages=[],
+        optional_params={},
+        litellm_params={},
+        api_key="sk-deepseek",
+        api_base="https://example.test/anthropic",
+    )
+
+    assert api_base == "https://example.test/anthropic"
+    assert headers["x-api-key"] == "sk-deepseek"
+    assert headers["anthropic-version"] == "2023-06-01"
+    assert headers["content-type"] == "application/json"
+
+
+def test_deepseek_anthropic_messages_preserves_thinking_and_sanitizes_custom_tools():
+    config = DeepSeekAnthropicMessagesConfig()
+    messages = [
+        {
+            "role": "user",
+            "content": "Use the tool.",
+        },
+        {
+            "role": "assistant",
+            "content": [
+                {
+                    "type": "thinking",
+                    "thinking": "I should call the tool.",
+                    "signature": "sig",
+                },
+                {
+                    "type": "tool_use",
+                    "id": "toolu_123",
+                    "name": "get_weather",
+                    "input": {"city": "Sao Paulo"},
+                },
+            ],
+        },
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "tool_result",
+                    "tool_use_id": "toolu_123",
+                    "content": "Sunny",
+                }
+            ],
+        },
+    ]
+
+    request = config.transform_anthropic_messages_request(
+        model="deepseek-v4-pro",
+        messages=messages,
+        anthropic_messages_optional_request_params={
+            "max_tokens": 100,
+            "thinking": {"type": "enabled", "budget_tokens": 1024},
+            "tools": [
+                {
+                    "type": "custom",
+                    "name": "get_weather",
+                    "description": "Get weather",
+                    "input_schema": {"type": "object"},
+                },
+                {
+                    "type": "web_search_20260209",
+                    "name": "web_search",
+                    "max_uses": 1,
+                },
+            ],
+        },
+        litellm_params=GenericLiteLLMParams(),
+        headers={},
+    )
+
+    assert request["messages"] == messages
+    assert request["thinking"] == {"type": "enabled", "budget_tokens": 1024}
+    assert request["tools"][0] == {
+        "name": "get_weather",
+        "description": "Get weather",
+        "input_schema": {"type": "object"},
+    }
+    assert request["tools"][1]["type"] == "web_search_20260209"

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 2b6c9bf. Configure here.}

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
2 out of 3 committers have signed the CLA.

✅ FelipeRodriguesGare
✅ mateo-berri
❌ cursoragent
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[mateo-berri]

@greptileai