The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
feat(core,anthropic): `extras` on `BaseTool` (#34120)
Mason Daugherty754227899742
diff --git a/libs/core/langchain_core/messages/block_translators/anthropic.py b/libs/core/langchain_core/messages/block_translators/anthropic.pyindex c5178be45b..d3a297e202 100644--- a/libs/core/langchain_core/messages/block_translators/anthropic.py+++ b/libs/core/langchain_core/messages/block_translators/anthropic.py@@ -248,8 +248,14 @@ def _convert_to_v1_from_anthropic(message: AIMessage) -> list[types.ContentBlocktool_call_chunk: types.ToolCallChunk = (message.tool_call_chunks[0].copy() # type: ignore[assignment])+ if "caller" in block:+ if "extras" not in tool_call_chunk:+ tool_call_chunk["extras"] = {}+ tool_call_chunk["extras"]["caller"] = block["caller"]+if "type" not in tool_call_chunk:tool_call_chunk["type"] = "tool_call_chunk"+yield tool_call_chunkelse:tool_call_block: types.ToolCall | None = None@@ -282,6 +288,11 @@ def _convert_to_v1_from_anthropic(message: AIMessage) -> list[types.ContentBlock}if "index" in block:tool_call_block["index"] = block["index"]+ if "caller" in block:+ if "extras" not in tool_call_block:+ tool_call_block["extras"] = {}+ tool_call_block["extras"]["caller"] = block["caller"]+yield tool_call_blockelif block_type == "input_json_delta" and isinstance(diff --git a/libs/core/langchain_core/tools/base.py b/libs/core/langchain_core/tools/base.pyindex 23cf6f9865..ad770fea62 100644--- a/libs/core/langchain_core/tools/base.py+++ b/libs/core/langchain_core/tools/base.py@@ -496,6 +496,24 @@ class ChildTool(BaseTool):two-tuple corresponding to the `(content, artifact)` of a `ToolMessage`."""+ extras: dict[str, Any] | None = None+ """Optional provider-specific extra fields for the tool.++ This is used to pass provider-specific configuration that doesn't fit into+ standard tool fields.++ Example:+ Anthropic-specific fields like [`cache_control`](https://docs.langchain.com/oss/python/integrations/chat/anthropic#prompt-caching),+ [`defer_loading`](https://docs.langchain.com/oss/python/integrations/chat/anthropic#tool-search),+ or `input_examples`.++ ```python+ @tool(extras={"defer_loading": True, "cache_control": {"type": "ephemeral"}})+ def my_tool(x: str) -> str:+ return x+ ```+ """+def __init__(self, **kwargs: Any) -> None:"""Initialize the tool.diff --git a/libs/core/langchain_core/tools/convert.py b/libs/core/langchain_core/tools/convert.pyindex 1dabed5e00..be66424c72 100644--- a/libs/core/langchain_core/tools/convert.py+++ b/libs/core/langchain_core/tools/convert.py@@ -23,6 +23,7 @@ def tool(response_format: Literal["content", "content_and_artifact"] = "content",parse_docstring: bool = False,error_on_invalid_docstring: bool = True,+ extras: dict[str, Any] | None = None,) -> Callable[[Callable | Runnable], BaseTool]: ...@@ -38,6 +39,7 @@ def tool(response_format: Literal["content", "content_and_artifact"] = "content",parse_docstring: bool = False,error_on_invalid_docstring: bool = True,+ extras: dict[str, Any] | None = None,) -> BaseTool: ...@@ -52,6 +54,7 @@ def tool(response_format: Literal["content", "content_and_artifact"] = "content",parse_docstring: bool = False,error_on_invalid_docstring: bool = True,+ extras: dict[str, Any] | None = None,) -> BaseTool: ...@@ -66,6 +69,7 @@ def tool(response_format: Literal["content", "content_and_artifact"] = "content",parse_docstring: bool = False,error_on_invalid_docstring: bool = True,+ extras: dict[str, Any] | None = None,) -> Callable[[Callable | Runnable], BaseTool]: ...@@ -80,6 +84,7 @@ def tool(response_format: Literal["content", "content_and_artifact"] = "content",parse_docstring: bool = False,error_on_invalid_docstring: bool = True,+ extras: dict[str, Any] | None = None,) -> BaseTool | Callable[[Callable | Runnable], BaseTool]:"""Convert Python functions and `Runnables` to LangChain tools.@@ -130,6 +135,15 @@ def tool(parse parameter descriptions from Google Style function docstrings.error_on_invalid_docstring: If `parse_docstring` is provided, configurewhether to raise `ValueError` on invalid Google Style docstrings.+ extras: Optional provider-specific extra fields for the tool.++ Used to pass configuration that doesn't fit into standard tool fields.+ Chat models should process known extras when constructing model payloads.++ !!! example++ For example, Anthropic-specific fields like `cache_control`,+ `defer_loading`, or `input_examples`.Raises:ValueError: If too many positional arguments are provided (e.g. violating the@@ -292,6 +306,7 @@ def tool(response_format=response_format,parse_docstring=parse_docstring,error_on_invalid_docstring=error_on_invalid_docstring,+ extras=extras,)# If someone doesn't want a schema applied, we must treat it as# a simple string->string function@@ -308,6 +323,7 @@ def tool(return_direct=return_direct,coroutine=coroutine,response_format=response_format,+ extras=extras,)return _tool_factorydiff --git a/libs/core/tests/unit_tests/messages/block_translators/test_anthropic.py b/libs/core/tests/unit_tests/messages/block_translators/test_anthropic.pyindex bae653b1b4..1b0ec03586 100644--- a/libs/core/tests/unit_tests/messages/block_translators/test_anthropic.py+++ b/libs/core/tests/unit_tests/messages/block_translators/test_anthropic.py@@ -13,6 +13,16 @@ def test_convert_to_v1_from_anthropic() -> None:"name": "get_weather","input": {"location": "San Francisco"},},+ {+ "type": "tool_use",+ "id": "abc_234",+ "name": "get_weather_programmatic",+ "input": {"location": "Boston"},+ "caller": {+ "type": "code_execution_20250825",+ "tool_id": "srvtoolu_abc234",+ },+ },{"type": "text","text": "It's sunny.",@@ -88,6 +98,18 @@ def test_convert_to_v1_from_anthropic() -> None:"name": "get_weather","args": {"location": "San Francisco"},},+ {+ "type": "tool_call",+ "id": "abc_234",+ "name": "get_weather_programmatic",+ "args": {"location": "Boston"},+ "extras": {+ "caller": {+ "type": "code_execution_20250825",+ "tool_id": "srvtoolu_abc234",+ }+ },+ },{"type": "text","text": "It's sunny.",diff --git a/libs/langchain/tests/unit_tests/chat_models/test_base.py b/libs/langchain/tests/unit_tests/chat_models/test_base.pyindex 4b1a4147e4..cd91955f29 100644--- a/libs/langchain/tests/unit_tests/chat_models/test_base.py+++ b/libs/langchain/tests/unit_tests/chat_models/test_base.py@@ -269,6 +269,7 @@ def test_configurable_with_default() -> None:"betas": None,"default_headers": None,"model_kwargs": {},+ "reuse_last_container": None,"streaming": False,"stream_usage": True,"output_version": None,diff --git a/libs/langchain_v1/tests/unit_tests/chat_models/test_chat_models.py b/libs/langchain_v1/tests/unit_tests/chat_models/test_chat_models.pyindex 18a96fff2e..c4a95c73d4 100644--- a/libs/langchain_v1/tests/unit_tests/chat_models/test_chat_models.py+++ b/libs/langchain_v1/tests/unit_tests/chat_models/test_chat_models.py@@ -269,6 +269,7 @@ def test_configurable_with_default() -> None:"betas": None,"default_headers": None,"model_kwargs": {},+ "reuse_last_container": None,"streaming": False,"stream_usage": True,"output_version": None,diff --git a/libs/partners/anthropic/langchain_anthropic/_compat.py b/libs/partners/anthropic/langchain_anthropic/_compat.pyindex d16f5c7727..36495cd663 100644--- a/libs/partners/anthropic/langchain_anthropic/_compat.py+++ b/libs/partners/anthropic/langchain_anthropic/_compat.py@@ -113,14 +113,15 @@ def _convert_from_v1_to_anthropic(new_content.append(new_block)elif block["type"] == "tool_call":- new_content.append(- {- "type": "tool_use",- "name": block.get("name", ""),- "input": block.get("args", {}),- "id": block.get("id", ""),- }- )+ tool_use_block = {+ "type": "tool_use",+ "name": block.get("name", ""),+ "input": block.get("args", {}),+ "id": block.get("id", ""),+ }+ if "caller" in block.get("extras", {}):+ tool_use_block["caller"] = block["extras"]["caller"]+ new_content.append(tool_use_block)elif block["type"] == "tool_call_chunk":if isinstance(block["args"], str):diff --git a/libs/partners/anthropic/langchain_anthropic/chat_models.py b/libs/partners/anthropic/langchain_anthropic/chat_models.pyindex 4b2e313b38..15c1563d47 100644--- a/libs/partners/anthropic/langchain_anthropic/chat_models.py+++ b/libs/partners/anthropic/langchain_anthropic/chat_models.py@@ -3,6 +3,7 @@from __future__ import annotationsimport copy+import datetimeimport jsonimport reimport warnings@@ -105,6 +106,12 @@ class AnthropicTool(TypedDict):cache_control: NotRequired[dict[str, str]]+ defer_loading: NotRequired[bool]++ input_examples: NotRequired[list[dict[str, Any]]]++ allowed_callers: NotRequired[list[str]]+# Some tool types require specific beta headers to be enabled# Mapping of tool type patterns to required beta headers@@ -119,6 +126,14 @@ _TOOL_TYPE_TO_BETA: dict[str, str] = {"tool_search_tool_bm25_20251119": "advanced-tool-use-2025-11-20",}+# Allowlist of valid Anthropic-specific extra fields+_ANTHROPIC_EXTRA_FIELDS: set[str] = {+ "allowed_callers",+ "cache_control",+ "defer_loading",+ "input_examples",+}+def _is_builtin_tool(tool: Any) -> bool:"""Check if a tool is a built-in Anthropic tool.@@ -420,9 +435,11 @@ def _format_messages(elif block["type"] == "tool_use":# If a tool_call with the same id as a tool_use content block# exists, the tool_call is preferred.- if isinstance(message, AIMessage) and block["id"] in [- tc["id"] for tc in message.tool_calls- ]:+ if (+ isinstance(message, AIMessage)+ and (block["id"] in [tc["id"] for tc in message.tool_calls])+ and "caller" not in block # take caller from content+ ):overlapping = [tcfor tc in message.tool_calls@@ -443,14 +460,15 @@ def _format_messages(args = {}else:args = {}- content.append(- _AnthropicToolUse(- type="tool_use",- name=block["name"],- input=args,- id=block["id"],- )+ tool_use_block = _AnthropicToolUse(+ type="tool_use",+ name=block["name"],+ input=args,+ id=block["id"],)+ if "caller" in block:+ tool_use_block["caller"] = block["caller"]+ content.append(tool_use_block)elif block["type"] in ("server_tool_use", "mcp_tool_use"):formatted_block = {k: v@@ -655,8 +673,6 @@ class ChatAnthropic(BaseChatModel):* [`base_url`][langchain_anthropic.chat_models.ChatAnthropic.anthropic_api_url]:Base URL for API requests. Only specify if using a proxy or service emulator.- See full list of supported init args and their descriptions below.-???+ example "Instantiate"```python@@ -674,10 +690,11 @@ class ChatAnthropic(BaseChatModel):)```- ???+ note+ ???+ note "Unsupported params"Any param which is not explicitly supported will be passed directly to- `Anthropic.messages.create(...)` each time to the model is invoked.+ [`Anthropic.messages.create(...)`](https://platform.claude.com/docs/en/api/python/messages/create)+ each time to the model is invoked.!!! example@@ -794,7 +811,13 @@ class ChatAnthropic(BaseChatModel):)```- ???+ example "Tool calling"+ ???+ example "Token counting"++ You can count tokens in messages before sending them to the model using the+ [`get_num_tokens_from_messages()`][langchain_anthropic.chat_models.ChatAnthropic.get_num_tokens_from_messages]+ method, which uses Anthropic's official token counting API.++ ???+ example "Tools"```python hl_lines="16"from pydantic import BaseModel, Field@@ -853,210 +876,243 @@ class ChatAnthropic(BaseChatModel):See [`ChatAnthropic.bind_tools()`][langchain_anthropic.chat_models.ChatAnthropic.bind_tools]for more info.- ???+ example "Token-efficient tool use (beta)"+ ???+ example "Token-efficient tool use"- See LangChain [docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#token-efficient-tool-use)- for more detail.+ See LangChain [docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#token-efficient-tool-use)+ for more detail.- ```python hl_lines="9"- from langchain_anthropic import ChatAnthropic- from langchain_core.tools import tool+ ```python hl_lines="9"+ from langchain_anthropic import ChatAnthropic+ from langchain_core.tools import tool- model = ChatAnthropic(- model="claude-sonnet-4-5-20250929",- temperature=0,- model_kwargs={- "extra_headers": {- "anthropic-beta": "token-efficient-tools-2025-02-19"+ model = ChatAnthropic(+ model="claude-sonnet-4-5-20250929",+ temperature=0,+ model_kwargs={+ "extra_headers": {+ "anthropic-beta": "token-efficient-tools-2025-02-19"+ }}- }- )-- @tool- def get_weather(location: str) -> str:- \"\"\"Get the weather at a location.\"\"\"- return "It's sunny."+ )- model_with_tools = model.bind_tools([get_weather])- response = model_with_tools.invoke(- "What's the weather in San Francisco?"- )- print(response.tool_calls)- print(f'Total tokens: {response.usage_metadata["total_tokens"]}')- ```+ @tool+ def get_weather(location: str) -> str:+ \"\"\"Get the weather at a location.\"\"\"+ return "It's sunny."- ```txt- [{'name': 'get_weather', 'args': {'location': 'San Francisco'}, 'id': 'toolu_01HLjQMSb1nWmgevQUtEyz17', 'type': 'tool_call'}]- Total tokens: 408- ```+ model_with_tools = model.bind_tools([get_weather])+ response = model_with_tools.invoke(+ "What's the weather in San Francisco?"+ )+ print(response.tool_calls)+ print(f'Total tokens: {response.usage_metadata["total_tokens"]}')+ ```- ???+ example "Fine-grained tool streaming"+ ```txt+ [{'name': 'get_weather', 'args': {'location': 'San Francisco'}, 'id': 'toolu_01HLjQMSb1nWmgevQUtEyz17', 'type': 'tool_call'}]+ Total tokens: 408+ ```- Fine-grained tool streaming enables faster streaming of tool parameters- without buffering or JSON validation, reducing latency when receiving large tool- parameters.+ ???+ example "Fine-grained tool streaming"- More info available in the [Claude docs](https://platform.claude.com/docs/en/agents-and-tools/tool-use/fine-grained-tool-streaming)+ Fine-grained tool streaming enables faster streaming of tool parameters+ without buffering or JSON validation, reducing latency when receiving large tool+ parameters. For more details, see the+ [LangChain docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#fine-grained-tool-streaming).- ```python hl_lines="5"- from langchain_anthropic import ChatAnthropic+ ```python hl_lines="5"+ from langchain_anthropic import ChatAnthropic- model = ChatAnthropic(- model="claude-3-5-sonnet-20241022",- betas=["fine-grained-tool-streaming-2025-05-14"]- )+ model = ChatAnthropic(+ model="claude-3-5-sonnet-20241022",+ betas=["fine-grained-tool-streaming-2025-05-14"]+ )- def write_document(title: str, content: str) -> str:- \"\"\"Write a document with the given title and content.\"\"\"- return f"Document '{title}' written"+ def write_document(title: str, content: str) -> str:+ \"\"\"Write a document with the given title and content.\"\"\"+ return f"Document '{title}' written"- model_with_tools = model.bind_tools([write_document])+ model_with_tools = model.bind_tools([write_document])- # Stream tool calls with reduced latency- for chunk in model_with_tools.stream(- "Write a document about the benefits of streaming APIs"- ):- print(chunk)- ```+ # Stream tool calls with reduced latency+ for chunk in model_with_tools.stream(+ "Write a document about the benefits of streaming APIs"+ ):+ print(chunk)+ ```- !!! note+ !!! note- This is a beta feature that may return invalid or partial JSON inputs.+ This is a beta feature that may return invalid or partial JSON inputs.- Implement appropriate error handling for incomplete JSON, especially- when `max_tokens` is reached.+ Implement appropriate error handling for incomplete JSON, especially+ when `max_tokens` is reached.???+ example "Image input"- See the [multimodal guide](https://docs.langchain.com/oss/python/langchain/models#multimodal)+ See the [LangChain docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#multimodal)for more detail.- ```python- import base64+ ??? example "URL"- import httpx- from langchain_anthropic import ChatAnthropic- from langchain_core.messages import HumanMessage+ ```python+ from langchain_anthropic import ChatAnthropic+ from langchain_core.messages import HumanMessage- image_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"- image_data = base64.b64encode(httpx.get(image_url).content).decode("utf-8")+ model = ChatAnthropic(model="claude-sonnet-4-5-20250929")- model = ChatAnthropic(model="claude-sonnet-4-5-20250929")- message = HumanMessage(- content=[- {- "type": "text",- "text": "Can you highlight the differences between these two images?",- },- {- "type": "image",- "base64": image_data,- "mime_type": "image/jpeg",- },- {- "type": "image",- "url": image_url,- },- ],- )- ai_msg = model.invoke([message])- ai_msg.content- ```+ message = HumanMessage(+ content=[+ {"type": "text", "text": "Describe the image at the URL."},+ {+ "type": "image",+ "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",+ },+ ]+ )+ response = model.invoke([message])+ ```- ```python- "After examining both images carefully, I can see that they are actually identical."- ```+ ??? example "Base64 encoded"- ??? example "Upload with Files API"+ ```python+ import base64+ import httpx+ from langchain_anthropic import ChatAnthropic+ from langchain_core.messages import HumanMessage++ model = ChatAnthropic(model="claude-sonnet-4-5-20250929")++ image_url = "https://picsum.photos/id/237/200/300"+ image_data = base64.b64encode(httpx.get(image_url, follow_redirects=True).content).decode("utf-8")++ message = HumanMessage(+ content=[+ {"type": "text", "text": "Describe the image."},+ {+ "type": "image",+ "base64": image_data,+ "mime_type": "image/jpeg",+ },+ ]+ )+ response = model.invoke([message])+ ```++ ??? example "Files API"You can also pass in files that are managed through Anthropic's[Files API](https://platform.claude.com/docs/en/build-with-claude/files):```python+ import anthropicfrom langchain_anthropic import ChatAnthropic+ from langchain_core.messages import HumanMessage++ client = anthropic.Anthropic()+ file = client.beta.files.upload(+ file=("image.png", open("/path/to/image.png", "rb"), "image/png"),+ )model = ChatAnthropic(model="claude-sonnet-4-5-20250929",betas=["files-api-2025-04-14"],)- input_message = {- "role": "user",- "content": [- {- "type": "text",- "text": "Describe this document.",- },++ message = HumanMessage(+ content=[+ {"type": "text", "text": "Describe this image."},{"type": "image",- "id": "file_abc123...",+ "file_id": file.id,},- ],- }- model.invoke([input_message])+ ]+ )+ response = model.invoke([message])```???+ example "PDF input"- See the [multimodal guide](https://docs.langchain.com/oss/python/langchain/models#multimodal)+ See the [LangChain docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#multimodal)for more detail.- ```python- from base64 import b64encode- from langchain_anthropic import ChatAnthropic- from langchain_core.messages import HumanMessage- import requests+ ??? example "URL"- url = "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"- data = b64encode(requests.get(url).content).decode()+ ```python+ from langchain_anthropic import ChatAnthropic+ from langchain_core.messages import HumanMessage- model = ChatAnthropic(model="claude-sonnet-4-5-20250929")- ai_msg = model.invoke(- [- HumanMessage(- [- "Summarize this document.",- {- "type": "file",- "mime_type": "application/pdf",- "base64": data,- },- ]- )- ]- )- ai_msg.content- ```+ model = ChatAnthropic(model="claude-sonnet-4-5-20250929")- ```python- "This appears to be a simple document..."- ```+ message = HumanMessage(+ content=[+ {"type": "text", "text": "Summarize this document."},+ {+ "type": "file",+ "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",+ "mime_type": "application/pdf",+ },+ ]+ )+ response = model.invoke([message])+ ```++ ??? example "Base64 encoded"++ ```python+ import base64+ import httpx+ from langchain_anthropic import ChatAnthropic+ from langchain_core.messages import HumanMessage- ??? example "Upload with Files API"+ model = ChatAnthropic(model="claude-sonnet-4-5-20250929")++ pdf_url = "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"+ pdf_data = base64.b64encode(httpx.get(pdf_url).content).decode("utf-8")++ message = HumanMessage(+ content=[+ {"type": "text", "text": "Summarize this document."},+ {+ "type": "file",+ "base64": pdf_data,+ "mime_type": "application/pdf",+ },+ ]+ )+ response = model.invoke([message])+ ```++ ??? example "Files API"You can also pass in files that are managed through Anthropic's[Files API](https://platform.claude.com/docs/en/build-with-claude/files):```python+ import anthropicfrom langchain_anthropic import ChatAnthropic+ from langchain_core.messages import HumanMessage++ client = anthropic.Anthropic()+ file = client.beta.files.upload(+ file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),+ )model = ChatAnthropic(model="claude-sonnet-4-5-20250929",betas=["files-api-2025-04-14"],)- input_message = {- "role": "user",- "content": [- {- "type": "text",- "text": "Describe this document.",- },++ message = HumanMessage(+ content=[+ {"type": "text", "text": "Summarize this document."},{"type": "file",- "id": "file_abc123...",+ "file_id": file.id,},- ],- }- model.invoke([input_message])+ ]+ )+ response = model.invoke([message])```???+ example "Extended thinking"@@ -1064,13 +1120,16 @@ class ChatAnthropic(BaseChatModel):Certain [Claude models](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#supported-models)support an [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)feature, which will output the step-by-step reasoning process that led to its- final answer.+ final answer. See the [LangChain docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#extended-thinking)+ for more detail.- To use it, specify the `thinking` parameter when initializing `ChatAnthropic`.+ !!! warning "Differences in thinking across model versions"- It can also be passed in as a kwarg during invocation.+ The Claude Messages API handles thinking differently across Claude Sonnet+ 3.7 and Claude 4 models.- **You will need to specify a token budget** to use this feature.+ Refer to the [Claude docs](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#differences-in-thinking-across-model-versions)+ for more info.!!! example@@ -1098,18 +1157,12 @@ class ChatAnthropic(BaseChatModel):]```- !!! warning "Differences in thinking across model versions"-- The Claude Messages API handles thinking differently across Claude Sonnet- 3.7 and Claude 4 models.-- Refer to the [Claude docs](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#differences-in-thinking-across-model-versions)- for more info.-???+ example "Effort"Certain Claude models support an [effort](https://platform.claude.com/docs/en/build-with-claude/effort)- feature, which will control how many tokens Claude uses when responding.+ feature, which will control how many tokens Claude uses when responding. See the+ [LangChain docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#effort)+ for more detail.!!! example@@ -1126,18 +1179,11 @@ class ChatAnthropic(BaseChatModel):print(response.content)```- See the [Claude docs](https://platform.claude.com/docs/en/build-with-claude/effort)- for more detail on when to use different effort levels.-???+ example "Prompt caching"Prompt caching reduces processing time and costs for repetitive tasks or prompts- with consistent elements-- !!! note- Only certain models support prompt caching.- See the [Claude documentation](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#supported-models)- for a full list.+ with consistent elements. See the [LangChain docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#prompt-caching)+ for more detail.```python hl_lines="16"from langchain_anthropic import ChatAnthropic@@ -1236,6 +1282,23 @@ class ChatAnthropic(BaseChatModel):See [Claude documentation](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration-beta)for detail.+ ???+ example "Response metadata"++ ```python+ ai_msg = model.invoke(messages)+ ai_msg.response_metadata+ ```++ ```python+ {+ "id": "msg_013xU6FHEGEq76aP4RgFerVT",+ "model": "claude-sonnet-4-5-20250929",+ "stop_reason": "end_turn",+ "stop_sequence": None,+ "usage": {"input_tokens": 25, "output_tokens": 11},+ }+ ```+???+ example "Token usage metadata"```python@@ -1275,6 +1338,9 @@ class ChatAnthropic(BaseChatModel):with `#!json "citations": {"enabled": True}` included in the query, Claude maygenerate citations in its response.+ See the [LangChain docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#citations)+ for more detail.+```python hl_lines="9-19"from langchain_anthropic import ChatAnthropic@@ -1342,10 +1408,9 @@ class ChatAnthropic(BaseChatModel):???+ example "Context management"Anthropic supports a context editing feature that will automatically manage the- model's context window (e.g., by clearing tool results).-- See [Anthropic documentation](https://platform.claude.com/docs/en/build-with-claude/context-editing)- for details and configuration options.+ model's context window (e.g., by clearing tool results). See the+ [LangChain docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#context-management)+ for more detail.```python hl_lines="5-6"from langchain_anthropic import ChatAnthropic@@ -1359,27 +1424,12 @@ class ChatAnthropic(BaseChatModel):response = model_with_tools.invoke("Search for recent developments in AI")```- ???+ example "Response metadata"-- ```python- ai_msg = model.invoke(messages)- ai_msg.response_metadata- ```-- ```python- {- "id": "msg_013xU6FHEGEq76aP4RgFerVT",- "model": "claude-sonnet-4-5-20250929",- "stop_reason": "end_turn",- "stop_sequence": None,- "usage": {"input_tokens": 25, "output_tokens": 11},- }- ```-- ???+ example "Extended context windows (beta)"+ ???+ example "Extended context window"Claude Sonnet 4 supports a 1-million token context window, available in beta for- organizations in usage tier 4 and organizations with custom rate limits.+ organizations in usage tier 4 and organizations with custom rate limits. See+ the [LangChain docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#extended-context-window)+ for more detail.```python hl_lines="5"from langchain_anthropic import ChatAnthropic@@ -1408,11 +1458,11 @@ class ChatAnthropic(BaseChatModel):response = model.invoke(messages)```- See [Claude documentation](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window)- for detail.-???+ example "Structured output"+ See [`ChatAnthropic.with_structured_output()`][langchain_anthropic.chat_models.ChatAnthropic.with_structured_output]+ for more info, including strict output validation.+```python hl_lines="13"from typing import Optionalfrom pydantic import BaseModel, Field@@ -1438,72 +1488,39 @@ class ChatAnthropic(BaseChatModel):)```- See [`ChatAnthropic.with_structured_output()`][langchain_anthropic.chat_models.ChatAnthropic.with_structured_output]- for more info.-- !!! note "Native structured output"-- Anthropic supports a native structured output feature that guarantees- responses adhere to a given schema.-- See [`ChatAnthropic.with_structured_output()`][langchain_anthropic.chat_models.ChatAnthropic.with_structured_output]- for more info.-???+ example "Built-in tools"See LangChain [docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#built-in-tools)for more detail.- ??? example "Web search"-- ```python hl_lines="5-9"- from langchain_anthropic import ChatAnthropic-- model = ChatAnthropic(model="claude-3-5-haiku-20241022")-- tool = {- "type": "web_search_20250305",- "name": "web_search",- "max_uses": 3,- }- model_with_tools = model.bind_tools([tool])+ ??? example "Bash tool"- response = model_with_tools.invoke("How do I update a web app to TypeScript 5.5?")- ```-- See the [Claude docs](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)- for more info.-- ??? example "Web fetch (beta)"+ Claude supports a [bash tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool)+ that allows it to execute shell commands in a persistent bash session. See+ the LangChain [docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#bash-tool)+ for more detail.- ```python hl_lines="7-11"+ ```pythonfrom langchain_anthropic import ChatAnthropic- model = ChatAnthropic(- model="claude-3-5-haiku-20241022",- )+ model = ChatAnthropic(model="claude-sonnet-4-5-20250929")- tool = {- "type": "web_fetch_20250910",- "name": "web_fetch",- "max_uses": 3,+ bash_tool = {+ "type": "bash_20250124",+ "name": "bash",}- model_with_tools = model.bind_tools([tool])-- response = model_with_tools.invoke("Please analyze the content at https://example.com/article")- ```-- !!! note "Automatic beta header"-- The required `web-fetch-2025-09-10` beta header is automatically- appended to the request when using the `web_fetch_20250910` tool type.- You don't need to manually specify it in the `betas` parameter.- See the [Claude docs](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool)- for more info.+ model_with_bash = model.bind_tools([bash_tool])+ response = model_with_bash.invoke("List all Python files in the current directory")+ ```??? example "Code execution"+ Claude supports a [code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)+ that allows it to execute code snippets in a secure, sandboxed environment. See the+ LangChain [docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#code-execution)+ for more detail.+```python hl_lines="3-6"model = ChatAnthropic(model="claude-sonnet-4-5-20250929")@@ -1520,73 +1537,94 @@ class ChatAnthropic(BaseChatModel):!!! note "Automatic beta header"- The required `code-execution-2025-05-22` beta header is automatically- appended to the request when using the `code_execution_20250522` tool- type. You don't need to manually specify it in the `betas` parameter.+ The required `code-execution-2025-05-22` or `code-execution-2025-08-25`+ beta header is automatically appended to the request when using the+ `code_execution_20250522` or `code_execution_20250825` tool type,+ respectively. You don't need to manually specify it in the `betas`+ parameter.- See the [Claude docs](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)- for more info.+ ??? example "Computer use"- ??? example "Memory tool"+ Claude supports [computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool)+ capabilities, allowing it to interact with desktop environments through+ screenshots, mouse control, and keyboard input. See the LangChain+ [docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#computer-use)+ for more detail.- ```python hl_lines="5-8"+ ```pythonfrom langchain_anthropic import ChatAnthropicmodel = ChatAnthropic(model="claude-sonnet-4-5-20250929")- tool = {- "type": "memory_20250818",- "name": "memory",+ computer_tool = {+ "type": "computer_20250124",+ "name": "computer",+ "display_width_px": 1024,+ "display_height_px": 768,+ "display_number": 1,}- model_with_tools = model.bind_tools([tool])- response = model_with_tools.invoke("What are my interests?")+ model_with_computer = model.bind_tools([computer_tool])+ response = model_with_computer.invoke("Take a screenshot to see what's on the screen")++ # response.tool_calls contains the action Claude wants to perform+ # You must execute this action in your environment and pass the result back```!!! note "Automatic beta header"- The required `context-management-2025-06-27` beta header is automatically- appended to the request when using the `memory_20250818` tool type.- You don't need to manually specify it in the `betas` parameter.-- See the [Claude docs](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool)- for more info.+ The required beta header is automatically appended based on the tool+ version. For `computer_20250124` and `computer_20251124`, the respective+ `computer-use-2025-01-24` and `computer-use-2025-11-24` beta header is+ added automatically.??? example "Remote MCP"- ```python hl_lines="3-14 18-19"+ Claude can use a [MCP connector tool](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector)+ for model-generated calls to remote MCP servers. See the LangChain+ [docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#remote-mcp)+ for more detail.++ ```python hl_lines="3-14 18 23"from langchain_anthropic import ChatAnthropicmcp_servers = [{"type": "url",- "url": "https://mcp.deepwiki.com/mcp",- "name": "deepwiki",- "tool_configuration": { # optional configuration- "enabled": True,- "allowed_tools": ["ask_question"],- },- "authorization_token": "PLACEHOLDER", # optional authorization+ "url": "https://docs.langchain.com/mcp",+ "name": "LangChain Docs",+ # "tool_configuration": { # optional configuration+ # "enabled": True,+ # "allowed_tools": ["ask_question"],+ # },+ # "authorization_token": "PLACEHOLDER", # optional authorization}]model = ChatAnthropic(model="claude-sonnet-4-5-20250929",- betas=["mcp-client-2025-04-04"], # Enable MCP client beta- mcp_servers=mcp_servers, # Pass in MCP server configurations+ mcp_servers=mcp_servers,)response = model.invoke(- "What transport protocols does the 2025-03-26 version of the MCP "- "spec (modelcontextprotocol/modelcontextprotocol) support?"+ "What are LangChain content blocks?",+ tools=[{"type": "mcp_toolset", "mcp_server_name": "LangChain Docs"}],)```- See the [Claude docs](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector)- for more info.+ !!! note "Automatic beta header"++ The required `mcp-client-2025-11-20` beta header is automatically+ appended to the request when using `mcp_servers`. You don't need to+ manually specify it in the `betas` parameter.??? example "Text editor"+ Claude supports a [text editor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool)+ that allows it to read and modify files in a code repository. See the+ LangChain [docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#text-editor)+ for more detail.+```python hl_lines="5-8"from langchain_anthropic import ChatAnthropic@@ -1616,60 +1654,117 @@ class ChatAnthropic(BaseChatModel):'type': 'tool_call'}]```- See the [Claude docs](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool)+ ??? example "Web fetch"++ Claude can use a [web fetching tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool)+ to retrieve full content from specified web pages and PDF documents and+ ground its responses with citations. See the LangChain+ [docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#web-fetch)+ for more detail.++ ```python hl_lines="5-9"+ from langchain_anthropic import ChatAnthropic++ model = ChatAnthropic(model="claude-haiku-4-5-20251001")++ tool = {+ "type": "web_fetch_20250910",+ "name": "web_fetch",+ "max_uses": 3,+ }+ model_with_tools = model.bind_tools([tool])++ response = model_with_tools.invoke("Please analyze the content at https://docs.langchain.com/")+ ```++ !!! note "Automatic beta header"++ The required `web-fetch-2025-09-10` beta header is automatically+ appended to the request when using the `web_fetch_20250910` tool type.+ You don't need to manually specify it in the `betas` parameter.++ ??? example "Web search"++ Claude can use a [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)+ to run searches and ground its responses with citations. See the LangChain+ [docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#web-search)+ for more detail.++ ```python hl_lines="5-9"+ from langchain_anthropic import ChatAnthropic++ model = ChatAnthropic(model="claude-sonnet-4-5-20250929")++ tool = {+ "type": "web_search_20250305",+ "name": "web_search",+ "max_uses": 3,+ }+ model_with_tools = model.bind_tools([tool])++ response = model_with_tools.invoke("How do I update a web app to TypeScript 5.5?")+ ```++ ??? example "Memory tool"++ ```python hl_lines="5-8"+ from langchain_anthropic import ChatAnthropic++ model = ChatAnthropic(model="claude-sonnet-4-5-20250929")++ tool = {+ "type": "memory_20250818",+ "name": "memory",+ }+ model_with_tools = model.bind_tools([tool])++ response = model_with_tools.invoke("What are my interests?")+ ```++ !!! note "Automatic beta header"++ The required `context-management-2025-06-27` beta header is automatically+ appended to the request when using the `memory_20250818` tool type.+ You don't need to manually specify it in the `betas` parameter.++ See the [Claude docs](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool)for more info.??? example "Tool search"Tool search enables Claude to dynamically discover and load tools on-demand- instead of loading all tool definitions upfront. See the+ instead of loading all tool definitions upfront. Use the `extras` parameter to+ specify `defer_loading` on LangChain tools.++ See the[LangChain docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#tool-search)for more detail.- ```python hl_lines="8-11 26 36"+ ```python hl_lines="4 10"from langchain_anthropic import ChatAnthropic+ from langchain_core.tools import tool- model = ChatAnthropic(- model="claude-sonnet-4-5-20250929",- )+ @tool(extras={"defer_loading": True})+ def get_weather(location: str, unit: str = "fahrenheit") -> str:+ \"\"\"Get the current weather for a location.\"\"\"+ return f"Weather in {location}: Sunny, 72°{unit[0].upper()}"++ @tool(extras={"defer_loading": True})+ def search_files(query: str) -> str:+ \"\"\"Search through files in the workspace.\"\"\"+ return f"Found 3 files matching '{query}'"- tools = [+ model = ChatAnthropic(model="claude-sonnet-4-5-20250929")++ model_with_tools = model.bind_tools([{"type": "tool_search_tool_regex_20251119","name": "tool_search_tool_regex",},- {- "name": "get_weather",- "description": "Get the current weather for a location",- "input_schema": {- "type": "object",- "properties": {- "location": {"type": "string", "description": "City name"},- "unit": {- "type": "string",- "enum": ["celsius", "fahrenheit"],- },- },- "required": ["location"],- },- "defer_loading": True, # Tool is loaded on-demand- },- {- "name": "search_files",- "description": "Search through files in the workspace",- "input_schema": {- "type": "object",- "properties": {- "query": {"type": "string"},- },- "required": ["query"],- },- "defer_loading": True, # Tool is loaded on-demand- },- ...,- ]+ get_weather,+ search_files,+ ])- model_with_tools = model.bind_tools(tools)response = model_with_tools.invoke("What's the weather in San Francisco?")```@@ -1696,7 +1791,14 @@ class ChatAnthropic(BaseChatModel):"""Model name to use."""max_tokens: int | None = Field(default=None, alias="max_tokens_to_sample")- """Denotes the number of tokens to predict per generation."""+ """Denotes the number of tokens to predict per generation.++ If not specified, this is set dynamically using the model's `max_output_tokens`+ from its model profile.++ See docs on [model profiles](https://docs.langchain.com/oss/python/langchain/models#model-profiles)+ for more information.+ """temperature: float | None = None"""A non-negative float that tunes the degree of randomness in generation."""@@ -1815,6 +1917,16 @@ class ChatAnthropic(BaseChatModel):[context management](https://platform.claude.com/docs/en/build-with-claude/context-editing)."""+ reuse_last_container: bool | None = None+ """Automatically reuse container from most recent response (code execution).++ When using the built-in+ [code execution tool](https://docs.langchain.com/oss/python/integrations/chat/anthropic#code-execution),+ model responses will include container metadata. Set `reuse_last_container=True`+ to automatically reuse the container from the most recent response for subsequent+ invocations.+ """+@propertydef _llm_type(self) -> str:"""Return type of chat model."""@@ -2076,6 +2188,19 @@ class ChatAnthropic(BaseChatModel):else:payload["betas"] = ["structured-outputs-2025-11-13"]+ if self.reuse_last_container:+ # Check for most recent AIMessage with container set in response_metadata+ # and set as a top-level param on the request+ for message in reversed(messages):+ if (+ isinstance(message, AIMessage)+ and (container := message.response_metadata.get("container"))+ and isinstance(container, dict)+ and (container_id := container.get("id"))+ ):+ payload["container"] = container_id+ break+# Check if any tools have strict mode enabledif "tools" in payload and isinstance(payload["tools"], list):has_strict_tool = any(@@ -2094,18 +2219,33 @@ class ChatAnthropic(BaseChatModel):else:payload["betas"] = ["structured-outputs-2025-11-13"]- # Auto-append required betas for specific tool types+ # Auto-append required betas for specific tool types and input_examples+ has_input_examples = Falsefor tool in payload["tools"]:- if isinstance(tool, dict) and "type" in tool:- tool_type = tool["type"]- if tool_type in _TOOL_TYPE_TO_BETA:+ if isinstance(tool, dict):+ tool_type = tool.get("type")+ if tool_type and tool_type in _TOOL_TYPE_TO_BETA:required_beta = _TOOL_TYPE_TO_BETA[tool_type]if payload["betas"]:- # Append to existing betas if not already presentif required_beta not in payload["betas"]:- payload["betas"] = [*payload["betas"], required_beta]+ payload["betas"] = [+ *payload["betas"],+ required_beta,+ ]else:payload["betas"] = [required_beta]+ # Check for input_examples+ if tool.get("input_examples"):+ has_input_examples = True++ # Auto-append header for input_examples+ if has_input_examples:+ required_beta = "advanced-tool-use-2025-11-20"+ if payload["betas"]:+ if required_beta not in payload["betas"]:+ payload["betas"] = [*payload["betas"], required_beta]+ else:+ payload["betas"] = [required_beta]# Auto-append required beta for mcp_serversif payload.get("mcp_servers"):@@ -2225,6 +2365,14 @@ class ChatAnthropic(BaseChatModel):llm_output = {k: v for k, v in data_dict.items() if k not in ("content", "role", "type")}+ if (+ (container := llm_output.get("container"))+ and isinstance(container, dict)+ and (expires_at := container.get("expires_at"))+ and isinstance(expires_at, datetime.datetime)+ ):+ # TODO: dump all `data` with `mode="json"`+ llm_output["container"]["expires_at"] = expires_at.isoformat()response_metadata = {"model_provider": "anthropic"}if "model" in llm_output and "model_name" not in llm_output:llm_output["model_name"] = llm_output["model"]@@ -2316,13 +2464,13 @@ class ChatAnthropic(BaseChatModel):strict: bool | None = None,**kwargs: Any,) -> Runnable[LanguageModelInput, AIMessage]:- r"""Bind tool-like objects to this chat model.+ r"""Bind tool-like objects to `ChatAnthropic`.Args:tools: A list of tool definitions to bind to this chat model.Supports Anthropic format tool schemas and any tool definition handled- by `langchain_core.utils.function_calling.convert_to_openai_tool`.+ by [`convert_to_openai_tool`][langchain_core.utils.function_calling.convert_to_openai_tool].tool_choice: Which tool to require the model to call. Options are:- Name of the tool as a string or as dict `{"type": "tool", "name": "<<tool_name>>"}`: calls corresponding tool@@ -2335,7 +2483,7 @@ class ChatAnthropic(BaseChatModel):!!! version-added "Added in `langchain-anthropic` 0.3.2"strict: If `True`, Claude's schema adherence is applied to tool calls.- See the [Claude docs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#when-to-use-json-outputs-vs-strict-tool-use).+ See the [docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#strict-tool-use) for more info.kwargs: Any additional parameters are passed directly to `bind`.???+ example@@ -2547,60 +2695,6 @@ class ChatAnthropic(BaseChatModel):)```- ??? example "Computer use tool"-- Claude supports computer use capabilities, allowing it to interact with- desktop environments through screenshots, mouse control, and keyboard input.-- !!! warning "Execution environment required"-- LangChain handles the API integration, but **you must provide**:-- - A sandboxed computing environment (Docker, VM, etc.)- - A virtual display (e.g., Xvfb)- - Code to execute tool calls (screenshot, clicks, typing)- - An agent loop to pass results back to Claude-- Anthropic provides a [reference implementation](https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo).-- !!! note-- Computer use requires:-- - Claude Opus 4.5, Claude 4, or Claude Sonnet 3.7- - A sandboxed computing environment with virtual display-- See the [Claude docs](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool)- for setup instructions, model capability, and best practices.-- ```python- from langchain_anthropic import ChatAnthropic-- model = ChatAnthropic(model="claude-sonnet-4-5-20250929")-- # LangChain handles the API call and tool binding- computer_tool = {- "type": "computer_20250124",- "name": "computer",- "display_width_px": 1024,- "display_height_px": 768,- "display_number": 1,- }-- model_with_computer = model.bind_tools([computer_tool])- response = model_with_computer.invoke("Take a screenshot to see what's on the screen")-- # response.tool_calls contains the action Claude wants to perform- # You must execute this action in your environment and pass the result back- ```-- !!! note "Automatic beta header"-- The required beta header is automatically appended based on the tool- version. For `computer_20250124` and `computer_20251124`, the respective- `computer-use-2025-01-24` and `computer-use-2025-11-24` beta header is- added automatically.-??? example "Strict tool use"Strict tool use guarantees that tool names and arguments are validated@@ -2613,7 +2707,8 @@ class ChatAnthropic(BaseChatModel):- Claude Sonnet 4.5 or Opus 4.1- `langchain-anthropic>=1.1.0`- To enable strict tool use, specify `strict=True` when calling `bind_tools`.+ To enable strict tool use, specify `strict=True` when calling+ [`bind_tools`][langchain_anthropic.chat_models.ChatAnthropic.bind_tools].```python hl_lines="11"from langchain_anthropic import ChatAnthropic@@ -2685,6 +2780,9 @@ class ChatAnthropic(BaseChatModel):) -> Runnable[LanguageModelInput, dict | BaseModel]:"""Model wrapper that returns outputs formatted to match the given schema.+ See the [LangChain docs](https://docs.langchain.com/oss/python/integrations/chat/anthropic#structured-output)+ for more details and examples.+Args:schema: The output schema. Can be passed in as:@@ -2740,6 +2838,41 @@ class ChatAnthropic(BaseChatModel):depends on the `schema` as described above.- `'parsing_error'`: `BaseException | None`+ ???+ example "Native structured output with `method='json_schema'`"++ Anthropic supports a native structured output feature that guarantees+ responses adhere to a given schema.++ !!! note++ Native structured output requires:++ - Claude Sonnet 4.5 or Opus 4.1+ - `langchain-anthropic>=1.1.0`++ To enable native structured output, specify `method="json_schema"` when+ calling `with_structured_output`. (Under the hood, LangChain will+ append the required `structured-outputs-2025-11-13` beta header)++ ```python hl_lines="13"+ from langchain_anthropic import ChatAnthropic+ from pydantic import BaseModel, Field++ model = ChatAnthropic(model="claude-sonnet-4-5")++ class Movie(BaseModel):+ \"\"\"A movie with details.\"\"\"+ title: str = Field(..., description="The title of the movie")+ year: int = Field(..., description="The year the movie was released")+ director: str = Field(..., description="The director of the movie")+ rating: float = Field(..., description="The movie's rating out of 10")++ model_with_structure = model.with_structured_output(Movie, method="json_schema")+ response = model_with_structure.invoke("Provide details about the movie Inception")+ print(response)+ # -> Movie(title="Inception", year=2010, director="Christopher Nolan", rating=8.8)+ ```+??? example "Pydantic schema (`include_raw=False`)"```python@@ -2815,41 +2948,6 @@ class ChatAnthropic(BaseChatModel):# 'justification': 'Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume and density of the two substances differ.'# }```-- ??? example "Native structured output with `method='json_schema'`"-- Anthropic supports a native structured output feature that guarantees- responses adhere to a given schema.-- !!! note-- Native structured output requires:-- - Claude Sonnet 4.5 or Opus 4.1- - `langchain-anthropic>=1.1.0`-- To enable native structured output, specify `method="json_schema"` when- calling `with_structured_output`. (Under the hood, LangChain will- append the required `structured-outputs-2025-11-13` beta header)-- ```python hl_lines="13"- from langchain_anthropic import ChatAnthropic- from pydantic import BaseModel, Field-- model = ChatAnthropic(model="claude-sonnet-4-5")-- class Movie(BaseModel):- \"\"\"A movie with details.\"\"\"- title: str = Field(..., description="The title of the movie")- year: int = Field(..., description="The year the movie was released")- director: str = Field(..., description="The director of the movie")- rating: float = Field(..., description="The movie's rating out of 10")-- model_with_structure = model.with_structured_output(Movie, method="json_schema")- response = model_with_structure.invoke("Provide details about the movie Inception")- print(response)- # -> Movie(title="Inception", year=2010, director="Christopher Nolan", rating=8.8)- ```""" # noqa: E501if method == "json_mode":warning_message = (@@ -2927,6 +3025,8 @@ class ChatAnthropic(BaseChatModel):) -> int:"""Count tokens in a sequence of input messages.+ This uses Anthropic's official [token counting API](https://platform.claude.com/docs/en/build-with-claude/token-counting).+Args:messages: The message inputs to tokenize.tools: If provided, sequence of `dict`, `BaseModel`, function, or `BaseTool`@@ -2980,12 +3080,7 @@ class ChatAnthropic(BaseChatModel):```txt403```-- !!! warning "Behavior changed in `langchain-anthropic` 0.3.0"-- Uses Anthropic's [token counting API](https://platform.claude.com/docs/en/build-with-claude/token-counting) to count tokens in messages.-- """ # noqa: D214,E501+ """ # noqa: D214formatted_system, formatted_messages = _format_messages(messages)if isinstance(formatted_system, str):kwargs["system"] = formatted_system@@ -3044,6 +3139,16 @@ def convert_to_anthropic_tool(anthropic_formatted["description"] = oai_formatted["description"]if "strict" in oai_formatted and isinstance(strict, bool):anthropic_formatted["strict"] = oai_formatted["strict"]+ # Select params from tool.extras+ if (+ isinstance(tool, BaseTool)+ and hasattr(tool, "extras")+ and isinstance(tool.extras, dict)+ ):+ for key, value in tool.extras.items():+ if key in _ANTHROPIC_EXTRA_FIELDS:+ # all are populated top-level+ anthropic_formatted[key] = value # type: ignore[literal-required]return anthropic_formatted@@ -3077,6 +3182,7 @@ class _AnthropicToolUse(TypedDict):name: strinput: dictid: str+ caller: NotRequired[dict[str, Any]]def _lc_tool_calls_to_anthropic_tool_use_blocks(@@ -3173,11 +3279,19 @@ def _make_message_chunk_from_anthropic_event(content_block = event.content_block.model_dump()content_block["index"] = event.indexif event.content_block.type == "tool_use":+ if (+ parsed_args := getattr(event.content_block, "input", None)+ ) and isinstance(parsed_args, dict):+ # In some cases parsed args are represented in start event, with no+ # following input_json_delta events+ args = json.dumps(parsed_args)+ else:+ args = ""tool_call_chunk = create_tool_call_chunk(index=event.index,id=event.content_block.id,name=event.content_block.name,- args="",+ args=args,)tool_call_chunks = [tool_call_chunk]else:@@ -3249,6 +3363,9 @@ def _make_message_chunk_from_anthropic_event(}if context_management := getattr(event, "context_management", None):response_metadata["context_management"] = context_management.model_dump()+ message_delta = getattr(event, "delta", None)+ if message_delta and (container := getattr(message_delta, "container", None)):+ response_metadata["container"] = container.model_dump(mode="json")message_chunk = AIMessageChunk(content="" if coerce_content_to_string else [],usage_metadata=usage_metadata,diff --git a/libs/partners/anthropic/tests/cassettes/test_programmatic_tool_use.yaml.gz b/libs/partners/anthropic/tests/cassettes/test_programmatic_tool_use.yaml.gznew file mode 100644index 0000000000..98c32b29beBinary files /dev/null and b/libs/partners/anthropic/tests/cassettes/test_programmatic_tool_use.yaml.gz differdiff --git a/libs/partners/anthropic/tests/cassettes/test_programmatic_tool_use_streaming.yaml.gz b/libs/partners/anthropic/tests/cassettes/test_programmatic_tool_use_streaming.yaml.gznew file mode 100644index 0000000000..5cb26b1c09Binary files /dev/null and b/libs/partners/anthropic/tests/cassettes/test_programmatic_tool_use_streaming.yaml.gz differdiff --git a/libs/partners/anthropic/tests/cassettes/test_tool_search.yaml.gz b/libs/partners/anthropic/tests/cassettes/test_tool_search.yaml.gznew file mode 100644index 0000000000..1381e57f6aBinary files /dev/null and b/libs/partners/anthropic/tests/cassettes/test_tool_search.yaml.gz differdiff --git a/libs/partners/anthropic/tests/integration_tests/test_chat_models.py b/libs/partners/anthropic/tests/integration_tests/test_chat_models.pyindex ed6fa71c9b..ee941fa24b 100644--- a/libs/partners/anthropic/tests/integration_tests/test_chat_models.py+++ b/libs/partners/anthropic/tests/integration_tests/test_chat_models.py@@ -2080,72 +2080,228 @@ def test_context_management() -> None:assert full.response_metadata.get("context_management")-def test_tool_search() -> None:- """Test tool search functionality with both regex and BM25 variants."""- # Test with regex variant- llm = ChatAnthropic(- model="claude-opus-4-5-20251101", # type: ignore[call-arg][email protected]_cassette("test_tool_search.yaml.gz")[email protected]("output_version", ["v0", "v1"])+def test_tool_search(output_version: str) -> None:+ """Test tool search with LangChain tools using extras parameter."""++ @tool(extras={"defer_loading": True})+ def get_weather(location: str, unit: str = "fahrenheit") -> str:+ """Get the current weather for a location.++ Args:+ location: City name+ unit: Temperature unit (celsius or fahrenheit)+ """+ return f"The weather in {location} is sunny and 72°{unit[0].upper()}"++ @tool(extras={"defer_loading": True})+ def search_files(query: str) -> str:+ """Search through files in the workspace.++ Args:+ query: Search query+ """+ return f"Found 3 files matching '{query}'"++ model = ChatAnthropic(+ model="claude-opus-4-5-20251101", output_version=output_version)- # Define tools with defer_loading- tools = [- {- "type": "tool_search_tool_regex_20251119",- "name": "tool_search_tool_regex",- },- {- "name": "get_weather",- "description": "Get the current weather for a location",- "input_schema": {- "type": "object",- "properties": {- "location": {"type": "string", "description": "City name"},- "unit": {- "type": "string",- "enum": ["celsius", "fahrenheit"],- "description": "Temperature unit",- },- },- "required": ["location"],- },- "defer_loading": True,- },- {- "name": "search_files",- "description": "Search through files in the workspace",- "input_schema": {- "type": "object",- "properties": {- "query": {"type": "string", "description": "Search query"},- },- "required": ["query"],+ agent = create_agent( # type: ignore[var-annotated]+ model,+ tools=[+ {+ "type": "tool_search_tool_regex_20251119",+ "name": "tool_search_tool_regex",},- "defer_loading": True,- },- ]-- llm_with_tools = llm.bind_tools(tools) # type: ignore[arg-type]+ get_weather,+ search_files,+ ],+ )- # Test with a query that should trigger tool search+ # Test with actual API callinput_message = {"role": "user","content": "What's the weather in San Francisco?",}- response = llm_with_tools.invoke([input_message])+ result = agent.invoke({"messages": [input_message]})+ first_response = result["messages"][1]+ content_types = [block["type"] for block in first_response.content]+ if output_version == "v0":+ assert content_types == [+ "text",+ "server_tool_use",+ "tool_search_tool_result",+ "text",+ "tool_use",+ ]+ else:+ # v1+ assert content_types == [+ "text",+ "server_tool_call",+ "server_tool_result",+ "text",+ "tool_call",+ ]- # Verify response contains expected block types- assert all(isinstance(block, (str, dict)) for block in response.content)+ answer = result["messages"][-1]+ assert not answer.tool_calls+ assert answer.text- # Check for server_tool_use (tool search) and tool_result blocks- block_types = {- block["type"]- for block in response.content- if isinstance(block, dict) and "type" in block+[email protected]_cassette("test_programmatic_tool_use.yaml.gz")[email protected]("output_version", ["v0", "v1"])+def test_programmatic_tool_use(output_version: str) -> None:+ """Test programmatic tool use.++ Implicitly checks that `allowed_callers` in tool extras works.+ """++ @tool(extras={"allowed_callers": ["code_execution_20250825"]})+ def get_weather(location: str) -> str:+ """Get the weather at a location."""+ return "It's sunny."++ tools: list = [+ {"type": "code_execution_20250825", "name": "code_execution"},+ get_weather,+ ]++ model = ChatAnthropic(+ model="claude-sonnet-4-5",+ betas=["advanced-tool-use-2025-11-20"],+ reuse_last_container=True,+ output_version=output_version,+ )++ agent = create_agent(model, tools=tools) # type: ignore[var-annotated]++ input_query = {+ "role": "user",+ "content": "What's the weather in Boston?",}- # Response should contain server_tool_use for tool search- # and potentially tool_result with tool_reference blocks- assert "server_tool_use" in block_types or "tool_use" in block_types+ result = agent.invoke({"messages": [input_query]})+ assert len(result["messages"]) == 4+ tool_call_message = result["messages"][1]+ response_message = result["messages"][-1]++ if output_version == "v0":+ server_tool_use_block = next(+ block+ for block in tool_call_message.content+ if block["type"] == "server_tool_use"+ )+ assert server_tool_use_block++ tool_use_block = next(+ block for block in tool_call_message.content if block["type"] == "tool_use"+ )+ assert "caller" in tool_use_block++ code_execution_result = next(+ block+ for block in response_message.content+ if block["type"] == "code_execution_tool_result"+ )+ assert code_execution_result["content"]["return_code"] == 0+ else:+ server_tool_call_block = next(+ block+ for block in tool_call_message.content+ if block["type"] == "server_tool_call"+ )+ assert server_tool_call_block++ tool_call_block = next(+ block for block in tool_call_message.content if block["type"] == "tool_call"+ )+ assert "caller" in tool_call_block["extras"]++ server_tool_result = next(+ block+ for block in response_message.content+ if block["type"] == "server_tool_result"+ )+ assert server_tool_result["output"]["return_code"] == 0++[email protected]_cassette("test_programmatic_tool_use_streaming.yaml.gz")[email protected]("output_version", ["v0", "v1"])+def test_programmatic_tool_use_streaming(output_version: str) -> None:+ @tool(extras={"allowed_callers": ["code_execution_20250825"]})+ def get_weather(location: str) -> str:+ """Get the weather at a location."""+ return "It's sunny."++ tools: list = [+ {"type": "code_execution_20250825", "name": "code_execution"},+ get_weather,+ ]++ model = ChatAnthropic(+ model="claude-sonnet-4-5",+ betas=["advanced-tool-use-2025-11-20"],+ reuse_last_container=True,+ streaming=True,+ output_version=output_version,+ )++ agent = create_agent(model, tools=tools) # type: ignore[var-annotated]++ input_query = {+ "role": "user",+ "content": "What's the weather in Boston?",+ }++ result = agent.invoke({"messages": [input_query]})+ assert len(result["messages"]) == 4+ tool_call_message = result["messages"][1]+ response_message = result["messages"][-1]++ if output_version == "v0":+ server_tool_use_block = next(+ block+ for block in tool_call_message.content+ if block["type"] == "server_tool_use"+ )+ assert server_tool_use_block++ tool_use_block = next(+ block for block in tool_call_message.content if block["type"] == "tool_use"+ )+ assert "caller" in tool_use_block++ code_execution_result = next(+ block+ for block in response_message.content+ if block["type"] == "code_execution_tool_result"+ )+ assert code_execution_result["content"]["return_code"] == 0+ else:+ server_tool_call_block = next(+ block+ for block in tool_call_message.content+ if block["type"] == "server_tool_call"+ )+ assert server_tool_call_block++ tool_call_block = next(+ block for block in tool_call_message.content if block["type"] == "tool_call"+ )+ assert "caller" in tool_call_block["extras"]++ server_tool_result = next(+ block+ for block in response_message.content+ if block["type"] == "server_tool_result"+ )+ assert server_tool_result["output"]["return_code"] == 0def test_async_shared_client() -> None:diff --git a/libs/partners/anthropic/tests/unit_tests/test_chat_models.py b/libs/partners/anthropic/tests/unit_tests/test_chat_models.pyindex fee0fa177d..8c5a155f06 100644--- a/libs/partners/anthropic/tests/unit_tests/test_chat_models.py+++ b/libs/partners/anthropic/tests/unit_tests/test_chat_models.py@@ -2228,3 +2228,137 @@ def test_output_config_without_effort() -> None:assert payload.get("betas") is None or "effort-2025-11-24" not in payload.get("betas", [])+++def test_extras_with_defer_loading() -> None:+ """Test that extras with `defer_loading` are merged into tool definitions."""+ from langchain_core.tools import tool++ @tool(extras={"defer_loading": True})+ def get_weather(location: str) -> str:+ """Get weather for a location."""+ return f"Weather in {location}"++ model = ChatAnthropic(model=MODEL_NAME) # type: ignore[call-arg]+ model_with_tools = model.bind_tools([get_weather])++ # Get the payload to check if defer_loading was merged+ payload = model_with_tools._get_request_payload( # type: ignore[attr-defined]+ "test",+ **model_with_tools.kwargs, # type: ignore[attr-defined]+ )++ # Find the get_weather tool in the payload+ weather_tool = None+ for tool_def in payload["tools"]:+ if isinstance(tool_def, dict) and tool_def.get("name") == "get_weather":+ weather_tool = tool_def+ break++ assert weather_tool is not None+ assert weather_tool.get("defer_loading") is True+++def test_extras_with_cache_control() -> None:+ """Test that extras with `cache_control` are merged into tool definitions."""+ from langchain_core.tools import tool++ @tool(extras={"cache_control": {"type": "ephemeral"}})+ def search_files(query: str) -> str:+ """Search files."""+ return f"Results for {query}"++ model = ChatAnthropic(model=MODEL_NAME) # type: ignore[call-arg]+ model_with_tools = model.bind_tools([search_files])++ payload = model_with_tools._get_request_payload( # type: ignore[attr-defined]+ "test",+ **model_with_tools.kwargs, # type: ignore[attr-defined]+ )++ search_tool = None+ for tool_def in payload["tools"]:+ if isinstance(tool_def, dict) and tool_def.get("name") == "search_files":+ search_tool = tool_def+ break++ assert search_tool is not None+ assert search_tool.get("cache_control") == {"type": "ephemeral"}+++def test_extras_with_input_examples() -> None:+ """Test that extras with `input_examples` are merged into tool definitions."""+ from langchain_core.tools import tool++ @tool(+ extras={+ "input_examples": [+ {"location": "San Francisco, CA", "unit": "fahrenheit"},+ {"location": "Tokyo, Japan", "unit": "celsius"},+ ]+ }+ )+ def get_weather(location: str, unit: str = "fahrenheit") -> str:+ """Get weather for a location."""+ return f"Weather in {location}"++ model = ChatAnthropic(model=MODEL_NAME) # type: ignore[call-arg]+ model_with_tools = model.bind_tools([get_weather])++ payload = model_with_tools._get_request_payload( # type: ignore[attr-defined]+ "test",+ **model_with_tools.kwargs, # type: ignore[attr-defined]+ )++ weather_tool = None+ for tool_def in payload["tools"]:+ if isinstance(tool_def, dict) and tool_def.get("name") == "get_weather":+ weather_tool = tool_def+ break++ assert weather_tool is not None+ assert "input_examples" in weather_tool+ assert len(weather_tool["input_examples"]) == 2+ assert weather_tool["input_examples"][0] == {+ "location": "San Francisco, CA",+ "unit": "fahrenheit",+ }++ # Beta header is required+ assert "betas" in payload+ assert "advanced-tool-use-2025-11-20" in payload["betas"]+++def test_extras_with_multiple_fields() -> None:+ """Test that multiple extra fields can be specified together."""+ from langchain_core.tools import tool++ @tool(+ extras={+ "defer_loading": True,+ "cache_control": {"type": "ephemeral"},+ "input_examples": [{"query": "python files"}],+ }+ )+ def search_code(query: str) -> str:+ """Search code."""+ return f"Code for {query}"++ model = ChatAnthropic(model=MODEL_NAME) # type: ignore[call-arg]+ model_with_tools = model.bind_tools([search_code])++ payload = model_with_tools._get_request_payload( # type: ignore[attr-defined]+ "test",+ **model_with_tools.kwargs, # type: ignore[attr-defined]+ )++ tool_def = None+ for t in payload["tools"]:+ if isinstance(t, dict) and t.get("name") == "search_code":+ tool_def = t+ break++ assert tool_def is not None+ assert tool_def.get("defer_loading") is True+ assert tool_def.get("cache_control") == {"type": "ephemeral"}+ assert "input_examples" in tool_defdiff --git a/libs/partners/anthropic/uv.lock b/libs/partners/anthropic/uv.lockindex bfe614c81a..b4274b1ae5 100644--- a/libs/partners/anthropic/uv.lock+++ b/libs/partners/anthropic/uv.lock@@ -495,7 +495,7 @@ wheels = [[[package]]name = "langchain"-version = "1.1.2"+version = "1.1.3"source = { editable = "../../langchain_v1" }dependencies = [{ name = "langchain-core" },@@ -643,7 +643,7 @@ typing = [[[package]]name = "langchain-core"-version = "1.1.1"+version = "1.1.2"source = { editable = "../../core" }dependencies = [{ name = "jsonpatch" },