langchain-anthropic: `cache_control` on a `tool_use` content block is silently dropped when a matching `tool_calls` item exists

[menezesandre]

Submission checklist

• This is a bug, not a usage question.
• I added a clear and descriptive title that summarizes this issue.
• I used the GitHub search to find a similar question and didn't find it.
• I am sure that this is a bug in LangChain rather than my code.
• The bug is not resolved by updating to the latest stable version of LangChain (or the specific integration package).
• This is not related to the langchain-community package.
• I posted a self-contained, minimal, reproducible example. A maintainer can copy it and run it AS IS.

Package (Required)

• langchain
• langchain-openai
• langchain-anthropic
• langchain-classic
• langchain-core
• langchain-model-profiles
• langchain-tests
• langchain-text-splitters
• langchain-chroma
• langchain-deepseek
• langchain-exa
• langchain-fireworks
• langchain-groq
• langchain-huggingface
• langchain-mistralai
• langchain-nomic
• langchain-ollama
• langchain-openrouter
• langchain-perplexity
• langchain-qdrant
• langchain-xai
• Other / not sure / general

Related Issues / PRs

No response

Reproduction Steps / Example Code (Python)

from langchain_core.messages import AIMessage, HumanMessage, ToolCall
from langchain_anthropic.chat_models import _format_messages

ai = AIMessage(
    content=[
        {"type": "text", "text": "Let me check."},
        {
            "type": "tool_use",
            "id": "toolu_1",
            "name": "get_weather",
            "input": {"city": "Paris"},
            "cache_control": {"type": "ephemeral"},  # breakpoint on the tool_use block
        },
    ],
    tool_calls=[ToolCall(name="get_weather", args={"city": "Paris"}, id="toolu_1")],
)

_, formatted = _format_messages([HumanMessage(content="weather?"), ai])
out = formatted[-1]["content"]

print(out)  # cache_control is gone
# [{'type': 'text', 'text': 'Let me check.'}, {'type': 'tool_use', 'name': 'get_weather', 'input': {'city': 'Paris'}, 'id': 'toolu_1'}]

assert any("cache_control" in b for b in out), "cache_control was silently dropped"

Error Message and Stack Trace (if applicable)

Description

When an AIMessage carries a tool call in both its content (as a tool_use block) and the structured tool_calls field, _format_messages rebuilds the tool_use block from tool_calls ("the tool_call is preferred") and discards every extra key on the original block, including cache_control.
As a result, a prompt-cache breakpoint placed on a tool_use block is silently lost during conversion.

A provider-returned assistant turn that makes a tool call typically ends with the tool_use block. Any caller doing manual prompt-cache breakpoint placement on the conversation (rather than relying on a middleware) cannot put a surviving breakpoint on such a turn.

This is inconsistent with the rest of _format_messages: the text, thinking, and server_tool_use/mcp_tool_use branches all explicitly preserve cache_control. tool_use is the only content block type that drops it.

System Info

System Information

OS: Darwin
OS Version: Darwin Kernel Version 25.5.0: Mon Apr 27 20:41:15 PDT 2026; root:xnu-12377.121.6~2/RELEASE_ARM64_T6041
Python Version: 3.14.2 (main, Dec 5 2025, 21:11:58) [Clang 21.1.4 ]

Package Information

langchain_core: 1.4.8
langsmith: 0.9.1
langchain_anthropic: 1.4.7
langchain_protocol: 0.0.18

Optional packages not installed

deepagents
deepagents-cli

Other Dependencies

anthropic: 0.111.0
anyio: 4.14.0
distro: 1.9.0
httpx: 0.28.1
jsonpatch: 1.33
orjson: 3.11.9
packaging: 26.2
pydantic: 2.13.4
pyyaml: 6.0.3
requests: 2.34.2
requests-toolbelt: 1.0.0
sniffio: 1.3.1
tenacity: 9.1.4
typing-extensions: 4.15.0
uuid-utils: 0.16.2
websockets: 16.0
xxhash: 3.7.1
zstandard: 0.25.0

[Harsh23Kashyap]

I’d like to work on this issue. Proposed scoped approach:\n\n- Keep the existing preference for over overlapping content blocks when IDs match.\n- Preserve from the original content block when that replacement path is taken, so prompt-cache breakpoints survive formatting.\n- Also preserve when formatting inline blocks directly (same branch in ) for consistency with other content block types.\n- Add focused unit coverage in for both overlapping and inline cases to ensure is retained without changing tool-call argument precedence.\n\nVerification plan:\n- ============================= test session starts ==============================
platform darwin -- Python 3.12.12, pytest-9.0.3, pluggy-1.6.0
codspeed: 4.2.0 (disabled, mode: walltime, callgraph: not supported, timer_resolution: 41.7ns)
benchmark: 5.0.1 (defaults: timer=time.perf_counter disable_gc=False min_rounds=5 min_time=0.000005 max_time=1.0 calibration_precision=10 warmup=False warmup_iterations=100000)
rootdir: /Users/harshkashyap/Projects/OSS/langchain-master/libs/partners/anthropic
configfile: pyproject.toml
plugins: mock-3.15.1, recording-0.13.4, anyio-4.11.0, syrupy-5.1.0, benchmark-5.0.1, socket-0.7.0, xdist-3.8.0, timeout-2.4.0, retry-1.7.0, codspeed-4.2.0, asyncio-1.3.0, langchain-tests-1.1.9, langsmith-0.8.18
asyncio: mode=Mode.AUTO, debug=False, asyncio_default_fixture_loop_scope=None, asyncio_default_test_loop_scope=function
collected 107 items / 96 deselected / 11 selected

tests/unit_tests/test_chat_models.py ........... [100%]

============================= slowest 5 durations ==============================

(5 durations < 0.005s hidden. Use -vv to show these durations.)
====================== 11 passed, 96 deselected in 1.00s =======================\n- All checks passed!\n\nIf this direction looks good, could a maintainer assign the issue so I can open/reopen the PR under the assignment gate?

[Harsh23Kashyap]

Correction to formatting in my previous comment. Proposed scoped approach:\n\n- Keep existing precedence: when overlapping IDs exist, use structured tool_calls as the canonical tool payload.\n- Preserve cache_control from the original tool_use content block when that overlap replacement path is used, so cache breakpoints survive formatting.\n- Preserve cache_control for inline tool_use block formatting in the same _format_messages branch for consistency with other block types.\n- Add focused unit coverage in libs/partners/anthropic/tests/unit_tests/test_chat_models.py for:\n 1) overlapping tool_use + tool_calls with cache_control, and\n 2) inline tool_use with cache_control.\n\nVerification plan:\n- uv run --directory libs/partners/anthropic --group test pytest tests/unit_tests/test_chat_models.py -k cache_control\n- uv run --directory libs/partners/anthropic --group lint ruff check langchain_anthropic/chat_models.py tests/unit_tests/test_chat_models.py\n\nIf this direction looks good, could a maintainer assign the issue so I can open/reopen the PR under the assignment gate?

[Harsh23Kashyap]

Implementation is now up in PR #38399 with the scoped fix discussed above (cache_control preserved for overlapping and inline tool_use formatting paths, with focused unit coverage and local lint/test verification). If this direction looks good, could a maintainer assign this issue so the PR can remain/reopen under the assignment gate?

[Chessing234]

Proposed fix: when _format_messages rebuilds inline tool_use blocks from tool_calls, copy cache_control from the original content block onto the regenerated tool_use block (matching id). Branch: Chessing234/anthropic/preserve-tool-use-cache-control. Happy to adjust if you prefer a different approach—please assign if acceptable.