Skip to content

Commit 59baeb2

Browse files
richardscarrottccurmeopen-swe
authored
feat(anthropic,openai): mid-conversation tool changes on SystemMessage (#40758)
Co-authored-by: ccurme <[email protected]> Co-authored-by: open-swe[bot] <[email protected]> Co-authored-by: Chester Curme <[email protected]>
1 parent 4b65996 commit 59baeb2

10 files changed

Lines changed: 984 additions & 30 deletions

File tree

‎libs/partners/anthropic/langchain_anthropic/_compat.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,16 @@
66
from langchain_core.messages import content as types
77

88

9+
def _unwrap_non_standard(block: dict) -> dict:
10+
"""Unwrap a provider-native dictionary from a standard content block."""
11+
if block.get("type") == "non_standard" and isinstance(
12+
value := block.get("value"),
13+
dict,
14+
):
15+
return value
16+
return block
17+
18+
919
def _convert_annotation_from_v1(annotation: types.Annotation) -> dict[str, Any]:
1020
"""Convert LangChain annotation format to Anthropic's native citation format."""
1121
if annotation["type"] == "non_standard_annotation":

‎libs/partners/anthropic/langchain_anthropic/chat_models.py‎

Lines changed: 201 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,10 @@
8383
_get_default_async_httpx_client,
8484
_get_default_httpx_client,
8585
)
86-
from langchain_anthropic._compat import _convert_from_v1_to_anthropic
86+
from langchain_anthropic._compat import (
87+
_convert_from_v1_to_anthropic,
88+
_unwrap_non_standard,
89+
)
8790
from langchain_anthropic._sdk_compat import (
8891
_aparse,
8992
_route_unsupported_sampling_params,
@@ -536,22 +539,108 @@ def _format_text_block(block: dict) -> dict:
536539
return formatted_block
537540

538541

539-
def _format_system_content(content: str | list[Any]) -> str | list[dict]:
542+
_TOOL_CHANGE_BLOCK_TYPES = ("tool_addition", "tool_removal")
543+
"""Anthropic-native system content blocks that change the tool set mid-conversation."""
544+
545+
_MID_CONVERSATION_TOOL_CHANGES_BETA = "mid-conversation-tool-changes-2026-07-01"
546+
"""Beta header required to send `tool_addition` / `tool_removal` blocks."""
547+
548+
_INLINE_TOOLS_BETA = "inline-tools-2026-09-15"
549+
"""Beta header required to define a tool in a `tool_addition` block."""
550+
551+
552+
def _is_tool_change_block(block: object) -> bool:
553+
"""Return whether a content block changes the tool set, in either spelling."""
554+
return (
555+
isinstance(block, dict)
556+
and _unwrap_non_standard(block).get("type") in _TOOL_CHANGE_BLOCK_TYPES
557+
)
558+
559+
560+
def _has_tool_change_block(content: object) -> bool:
561+
"""Return whether any block in `content` changes the tool set."""
562+
return isinstance(content, list) and any(_is_tool_change_block(b) for b in content)
563+
564+
565+
def _has_inline_tool_definition(content: object) -> bool:
566+
"""Return whether `content` defines a tool in a `tool_addition` block."""
567+
if not isinstance(content, list):
568+
return False
569+
return any(
570+
isinstance(block, dict)
571+
and block.get("type") == "tool_addition"
572+
and isinstance(tool := block.get("tool"), dict)
573+
and tool.get("type") == "tool_definition"
574+
for block in content
575+
)
576+
577+
578+
def _format_system_content(
579+
content: str | list[Any],
580+
*,
581+
model: str | None = None,
582+
preserve_tool_changes: bool = False,
583+
stacklevel: int = 3,
584+
) -> str | list[dict]:
540585
"""Narrow system message content to what Anthropic accepts.
541586
542587
String content is passed through unchanged; promoting it to a single-element
543588
block array would invalidate existing callers' prompt caches.
589+
590+
Anthropic documents a closed set of system content blocks: `text` anywhere, plus
591+
`tool_addition` / `tool_removal` on a mid-conversation `system` turn. Anything
592+
else is rejected by the API, so it is dropped with a warning rather than
593+
forwarded. Blocks wrapped in core's `non_standard` escape hatch are unwrapped
594+
first, so both spellings behave identically.
595+
596+
Args:
597+
content: The system message's content.
598+
model: The model the request targets, used only in warning text.
599+
preserve_tool_changes: Whether tool-change blocks should be forwarded instead
600+
of dropped.
601+
stacklevel: Frames to skip when attributing a warning, so it points at the
602+
caller of `_format_messages` rather than at this module. The default
603+
suits a direct call; a caller reached through a helper adds a frame.
604+
605+
Returns:
606+
Content narrowed to the blocks Anthropic accepts in this position.
544607
"""
545-
if isinstance(content, list):
546-
return [
547-
(
548-
(_format_text_block(block) if block.get("type") == "text" else block)
549-
if isinstance(block, dict)
550-
else {"type": "text", "text": block}
608+
if not isinstance(content, list):
609+
return content
610+
611+
formatted: list[dict] = []
612+
for raw_block in content:
613+
if not isinstance(raw_block, dict):
614+
formatted.append({"type": "text", "text": raw_block})
615+
continue
616+
617+
block = _unwrap_non_standard(raw_block)
618+
block_type = block.get("type")
619+
if block_type == "text":
620+
formatted.append(_format_text_block(block))
621+
elif block_type in _TOOL_CHANGE_BLOCK_TYPES:
622+
if preserve_tool_changes:
623+
formatted.append(block)
624+
else:
625+
warnings.warn(
626+
f"Tool-change block {block_type!r} was dropped: it is only "
627+
"valid on a `SystemMessage` sent in place, and this one was "
628+
"hoisted into the top-level `system` field. Use a model that "
629+
"supports mid-conversation system messages and place the "
630+
"message after a human or tool message, either last or before "
631+
f"an AI message (model: {model!r}).",
632+
UserWarning,
633+
stacklevel=stacklevel,
634+
)
635+
else:
636+
warnings.warn(
637+
f"Unrecognized system content block {block_type!r} was dropped. "
638+
"Anthropic accepts `text` in any system message, plus "
639+
"`tool_addition` and `tool_removal` on a mid-conversation one.",
640+
UserWarning,
641+
stacklevel=stacklevel,
551642
)
552-
for block in content
553-
]
554-
return content
643+
return formatted
555644

556645

557646
def _warn_system_message_hoisted(model: str | None) -> None:
@@ -590,6 +679,39 @@ def _previous_turn_allows_system(previous_turn: dict | None) -> bool:
590679
)
591680

592681

682+
def _format_in_place_system_messages(
683+
pending_system: Sequence[BaseMessage],
684+
*,
685+
model: str | None,
686+
) -> list[dict]:
687+
"""Format system messages that keep their position in the message array.
688+
689+
A message whose content is narrowed away entirely is omitted: Anthropic
690+
rejects a `system` turn with empty content, and the dropped blocks have
691+
already been warned about.
692+
693+
Args:
694+
pending_system: System messages awaiting emission, in order.
695+
model: The model the request targets, used only in warning text.
696+
697+
Returns:
698+
Formatted `system`-role turns.
699+
"""
700+
turns: list[dict] = []
701+
for pending in pending_system:
702+
content = _format_system_content(
703+
pending.content,
704+
model=model,
705+
preserve_tool_changes=True,
706+
# This helper sits between `_format_messages` and the warning site.
707+
stacklevel=4,
708+
)
709+
if content == []:
710+
continue
711+
turns.append({"role": "system", "content": content})
712+
return turns
713+
714+
593715
def _format_messages(
594716
messages: Sequence[BaseMessage],
595717
*,
@@ -607,7 +729,11 @@ def _format_messages(
607729
for _i, message in enumerate(merged_messages):
608730
if message.type == "system":
609731
if _i == 0:
610-
system = _format_system_content(message.content)
732+
system = _format_system_content(
733+
message.content,
734+
model=model,
735+
preserve_tool_changes=True,
736+
)
611737
continue
612738
if _supports_mid_conversation_system_messages(model) and (
613739
pending_system
@@ -620,7 +746,7 @@ def _format_messages(
620746
if system is not None:
621747
msg = "Received multiple non-consecutive system messages."
622748
raise ValueError(msg)
623-
system = _format_system_content(message.content)
749+
system = _format_system_content(message.content, model=model)
624750
_warn_system_message_hoisted(model)
625751
continue
626752

@@ -874,25 +1000,20 @@ def _format_messages(
8741000
if pending_system:
8751001
if role == "assistant":
8761002
formatted_messages.extend(
877-
{
878-
"role": "system",
879-
"content": _format_system_content(pending.content),
880-
}
881-
for pending in pending_system
1003+
_format_in_place_system_messages(pending_system, model=model)
8821004
)
8831005
else:
8841006
for pending in pending_system:
8851007
if system is not None:
8861008
msg = "Received multiple non-consecutive system messages."
8871009
raise ValueError(msg)
888-
system = _format_system_content(pending.content)
1010+
system = _format_system_content(pending.content, model=model)
8891011
_warn_system_message_hoisted(model)
8901012
pending_system = []
8911013
formatted_messages.append({"role": role, "content": content})
8921014

8931015
formatted_messages.extend(
894-
{"role": "system", "content": _format_system_content(pending.content)}
895-
for pending in pending_system
1016+
_format_in_place_system_messages(pending_system, model=model)
8961017
)
8971018
return system, formatted_messages
8981019

@@ -1183,6 +1304,37 @@ class ChatAnthropic(BaseChatModel):
11831304
)
11841305
```
11851306
1307+
Example: Add a tool mid-conversation
1308+
```python
1309+
from langchain_core.messages import HumanMessage, SystemMessage
1310+
from langchain_anthropic import ChatAnthropic
1311+
1312+
model = ChatAnthropic(model="claude-opus-5-5")
1313+
model.invoke(
1314+
[
1315+
HumanMessage("What time is it?"),
1316+
SystemMessage(
1317+
[
1318+
{
1319+
"type": "tool_addition",
1320+
"tool": {
1321+
"type": "tool_definition",
1322+
"definition": {
1323+
"name": "get_time",
1324+
"description": "Get the current time.",
1325+
"input_schema": {
1326+
"type": "object",
1327+
"properties": {},
1328+
},
1329+
},
1330+
},
1331+
}
1332+
]
1333+
),
1334+
]
1335+
)
1336+
```
1337+
11861338
Note:
11871339
Any param which is not explicitly supported will be passed directly to
11881340
[`Anthropic.messages.create(...)`](https://platform.claude.com/docs/en/api/python/messages/create)
@@ -1703,6 +1855,12 @@ def _get_request_payload(
17031855
)
17041856

17051857
system, formatted_messages = _format_messages(messages, model=self.model)
1858+
if isinstance(system, list) and not system:
1859+
# Every block was narrowed away (or the message was empty to begin
1860+
# with). An empty block array carries no instructions, so drop the
1861+
# field rather than sending it. `_format_messages` has already
1862+
# claimed the slot, so a second hoisted system message still errors.
1863+
system = None
17061864

17071865
# Only the direct Anthropic API accepts top-level `cache_control`.
17081866
# Subclasses that route through other transports (e.g. Bedrock) expand
@@ -1929,6 +2087,28 @@ def _get_request_payload(
19292087
else:
19302088
payload["betas"] = [required_beta]
19312089

2090+
system_contents = [
2091+
message.get("content")
2092+
for message in (payload.get("messages") or [])
2093+
if message.get("role") == "system"
2094+
]
2095+
has_tool_change = any(_has_tool_change_block(c) for c in system_contents)
2096+
has_inline_definition = any(
2097+
_has_inline_tool_definition(c) for c in system_contents
2098+
)
2099+
explicit_betas = payload.get("betas") or []
2100+
tool_change_beta = (
2101+
_INLINE_TOOLS_BETA
2102+
if has_inline_definition
2103+
else (
2104+
_MID_CONVERSATION_TOOL_CHANGES_BETA
2105+
if has_tool_change and _INLINE_TOOLS_BETA not in explicit_betas
2106+
else None
2107+
)
2108+
)
2109+
if tool_change_beta and tool_change_beta not in explicit_betas:
2110+
payload["betas"] = [*explicit_betas, tool_change_beta]
2111+
19322112
# Auto-append required beta for user_profile_id
19332113
if payload.get("user_profile_id"):
19342114
required_beta = "user-profiles-2026-03-24"
Binary file not shown.

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

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -783,6 +783,36 @@ def get_weather(location: str, unit: Literal["C", "F"]) -> str:
783783
assert response.tool_calls
784784

785785

786+
@pytest.mark.vcr
787+
def test_system_tool_addition() -> None:
788+
model = ChatAnthropic(model="claude-opus-5-5") # type: ignore[call-arg]
789+
response = model.invoke(
790+
[
791+
HumanMessage("What time is it?"),
792+
SystemMessage(
793+
[
794+
{
795+
"type": "tool_addition",
796+
"tool": {
797+
"type": "tool_definition",
798+
"definition": {
799+
"name": "get_time",
800+
"description": "Get the current time.",
801+
"input_schema": {
802+
"type": "object",
803+
"properties": {},
804+
},
805+
},
806+
},
807+
}
808+
]
809+
),
810+
]
811+
)
812+
assert isinstance(response, AIMessage)
813+
assert response.tool_calls[0]["name"] == "get_time"
814+
815+
786816
def test_get_num_tokens_from_messages() -> None:
787817
llm = ChatAnthropic(model=MODEL_NAME) # type: ignore[call-arg]
788818

0 commit comments

Comments
 (0)