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+ )
8790from 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
557646def _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+
593715def _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"
0 commit comments