1"""Anthropic chat models."""23from __future__ import annotations45import copy6import datetime7import hashlib8import json9import re10import warnings11from collections.abc import AsyncIterator, Callable, Iterator, Mapping, Sequence12from functools import cached_property13from operator import itemgetter14from typing import Any, Final, Literal, NotRequired, Self, TypeGuard, cast1516import anthropic17from langchain_core.callbacks import (18 AsyncCallbackManagerForLLMRun,19 CallbackManagerForLLMRun,20)21from langchain_core.exceptions import (22 ContextOverflowError,23 ModelAPIError,24 ModelAuthenticationError,25 ModelConnectionError,26 ModelInvalidRequestError,27 ModelNotFoundError,28 ModelPermissionDeniedError,29 ModelRateLimitError,30 ModelTimeoutError,31 OutputParserException,32)33from langchain_core.language_models import (34 LanguageModelInput,35 ModelProfile,36 ModelProfileRegistry,37)38from langchain_core.language_models.chat_models import BaseChatModel, LangSmithParams39from langchain_core.messages import (40 AIMessage,41 AIMessageChunk,42 BaseMessage,43 HumanMessage,44 SystemMessage,45 ToolCall,46 ToolMessage,47 is_data_content_block,48)49from langchain_core.messages import content as types50from langchain_core.messages.ai import (51 InputTokenDetails,52 OutputTokenDetails,53 UsageMetadata,54)55from langchain_core.messages.tool import tool_call_chunk as create_tool_call_chunk56from langchain_core.output_parsers import (57 JsonOutputKeyToolsParser,58 JsonOutputParser,59 PydanticOutputParser,60 PydanticToolsParser,61)62from langchain_core.output_parsers.base import OutputParserLike63from langchain_core.outputs import ChatGeneration, ChatGenerationChunk, ChatResult64from langchain_core.runnables import Runnable, RunnableMap, RunnablePassthrough65from langchain_core.tools import BaseTool66from langchain_core.utils import from_env, get_pydantic_field_names67from langchain_core.utils._gateway import (68 GATEWAY_METADATA_RESPONSE_KEY,69 _apply_gateway_config,70 _gateway_headers,71 _langsmith_gateway_active,72 _parse_gateway_metadata,73 _with_gateway_headers,74)75from langchain_core.utils.function_calling import (76 convert_to_json_schema,77 convert_to_openai_tool,78)79from langchain_core.utils.pydantic import is_basemodel_subclass80from langchain_core.utils.utils import _build_model_kwargs81from pydantic import (82 BaseModel,83 ConfigDict,84 Field,85 PrivateAttr,86 SecretStr,87 model_validator,88)89from typing_extensions import TypedDict9091from langchain_anthropic import __version__92from langchain_anthropic._client_utils import (93 _get_default_async_httpx_client,94 _get_default_httpx_client,95)96from langchain_anthropic._compat import (97 _convert_from_v1_to_anthropic,98 _unwrap_non_standard,99)100from langchain_anthropic._sdk_compat import (101 _aparse,102 _route_unsupported_sampling_params,103)104from langchain_anthropic.data._profiles import _PROFILES105from langchain_anthropic.output_parsers import extract_tool_calls106107_message_type_lookups = {108 "human": "user",109 "ai": "assistant",110 "AIMessageChunk": "assistant",111 "HumanMessageChunk": "user",112}113114_MODEL_PROFILES = cast(ModelProfileRegistry, _PROFILES)115116_USER_AGENT: Final[str] = f"langchain-anthropic/{__version__}"117118119def _add_gateway_metadata(generation_info: dict[str, Any], raw_response: Any) -> None:120 """Add parsed LangSmith gateway metadata to `generation_info`, if present.121122 Args:123 generation_info: Generation info to mutate in place.124 raw_response: The raw provider response, or None.125 """126 headers = getattr(raw_response, "headers", None)127 if headers is None:128 return129 gateway_metadata = _parse_gateway_metadata(headers)130 if gateway_metadata is not None:131 generation_info[GATEWAY_METADATA_RESPONSE_KEY] = gateway_metadata132133134def _get_default_model_profile(model_name: str) -> ModelProfile:135 """Get the default profile for a model.136137 Args:138 model_name: The model identifier.139140 Returns:141 The model profile dictionary, or an empty dict if not found.142 """143 default = _MODEL_PROFILES.get(model_name)144 if default:145 return default.copy()146 return {}147148149_FALLBACK_MAX_OUTPUT_TOKENS: Final[int] = 4096150151152class AnthropicTool(TypedDict):153 """Anthropic tool definition for custom (user-defined) tools.154155 Custom tools use `name` and `input_schema` fields to define the tool's156 interface. These are converted from LangChain tool formats (functions, Pydantic157 models, `BaseTool` objects) via `convert_to_anthropic_tool`.158 """159160 name: str161162 input_schema: dict[str, Any]163164 description: NotRequired[str]165166 strict: NotRequired[bool]167168 cache_control: NotRequired[dict[str, str]]169170 defer_loading: NotRequired[bool]171172 input_examples: NotRequired[list[dict[str, Any]]]173174 allowed_callers: NotRequired[list[str]]175176177# ---------------------------------------------------------------------------178# Built-in Tool Support179# ---------------------------------------------------------------------------180# When Anthropic releases new built-in tools, two places may need updating:181#182# 1. _TOOL_TYPE_TO_BETA (below) - Add mapping if the tool requires a beta header.183# Not all tools need this; only add if the API requires a beta header.184#185# 2. _is_builtin_tool() - Add the tool type prefix to _BUILTIN_TOOL_PREFIXES.186# This ensures the tool dict is passed through to the API unchanged (instead187# of being converted via convert_to_anthropic_tool, which may fail).188# ---------------------------------------------------------------------------189190_TOOL_TYPE_TO_BETA: dict[str, str] = {191 "web_fetch_20250910": "web-fetch-2025-09-10",192 "code_execution_20250522": "code-execution-2025-05-22",193 "mcp_toolset": "mcp-client-2025-11-20",194 "memory_20250818": "context-management-2025-06-27",195 "computer_20250124": "computer-use-2025-01-24",196 "computer_20251124": "computer-use-2025-11-24",197 "tool_search_tool_regex_20251119": "advanced-tool-use-2025-11-20",198 "tool_search_tool_bm25_20251119": "advanced-tool-use-2025-11-20",199 "advisor_20260301": "advisor-tool-2026-03-01",200}201"""Mapping of tool type to required beta header.202203Some tool types require specific beta headers to be enabled.204"""205206_BUILTIN_TOOL_PREFIXES = [207 "text_editor_",208 "computer_",209 "bash_",210 "web_search_",211 "web_fetch_",212 "code_execution_",213 "mcp_toolset",214 "memory_",215 "tool_search_",216 "advisor_",217]218219_ANTHROPIC_EXTRA_FIELDS: set[str] = {220 "allowed_callers",221 "cache_control",222 "defer_loading",223 "eager_input_streaming",224 "input_examples",225}226"""Valid Anthropic-specific extra fields"""227228229def _is_builtin_tool(tool: Any) -> TypeGuard[dict[str, Any]]:230 """Check if a tool is a built-in (server-side) Anthropic tool.231232 `tool` must be a `dict` and have a `type` key starting with one of the known233 built-in tool prefixes.234235 [Claude docs](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview)236 """237 if not isinstance(tool, dict):238 return False239240 tool_type = tool.get("type")241 if not tool_type or not isinstance(tool_type, str):242 return False243244 return any(tool_type.startswith(prefix) for prefix in _BUILTIN_TOOL_PREFIXES)245246247def _format_image(url: str) -> dict:248 """Convert part["image_url"]["url"] strings (OpenAI format) to Anthropic format.249250 {251 "type": "base64",252 "media_type": "image/jpeg",253 "data": "/9j/4AAQSkZJRg...",254 }255256 Or257258 {259 "type": "url",260 "url": "https://example.com/image.jpg",261 }262 """263 # Base64 encoded image264 base64_regex = r"^data:(?P<media_type>image/.+);base64,(?P<data>.+)$"265 base64_match = re.match(base64_regex, url)266267 if base64_match:268 return {269 "type": "base64",270 "media_type": base64_match.group("media_type"),271 "data": base64_match.group("data"),272 }273274 # Url275 url_regex = r"^https?://.*$"276 url_match = re.match(url_regex, url)277278 if url_match:279 return {280 "type": "url",281 "url": url,282 }283284 msg = (285 "Malformed url parameter."286 " Must be either an image URL (https://example.com/image.jpg)"287 " or base64 encoded string (data:image/png;base64,'/9j/4AAQSk'...)"288 )289 raise ValueError(290 msg,291 )292293294_TOOL_CALL_ID_PATTERN = re.compile(r"^[a-zA-Z0-9_-]+$")295"""Anthropic requires `tool_use`/`tool_result` IDs to match this pattern."""296297298def _normalize_tool_call_id(tool_call_id: str | None) -> str | None:299 """Map a tool-call ID to an Anthropic-compatible form if needed.300301 Anthropic rejects `tool_use`/`tool_result` IDs that don't match302 `^[a-zA-Z0-9_-]+$`. IDs minted by other providers can violate this when a303 thread is replayed across providers (e.g. Fireworks/Kimi emits304 `functions.write_todos:0`, whose `.` and `:` are invalid). Valid IDs are305 returned unchanged; invalid ones are hashed deterministically so that a306 rewritten `tool_use.id` and its paired `tool_use_id` resolve to the same307 value, both within a request and across turns.308309 Empty and `None` IDs are passed through unchanged so that a genuinely310 malformed request surfaces as a clear error from Anthropic rather than311 being masked by a synthesized ID.312313 Args:314 tool_call_id: The tool-call ID to normalize.315316 Returns:317 The original ID if it is empty, `None`, or already valid; otherwise a318 deterministic Anthropic-compatible replacement.319 """320 if not tool_call_id or _TOOL_CALL_ID_PATTERN.match(tool_call_id):321 return tool_call_id322 digest = hashlib.sha256(tool_call_id.encode()).hexdigest()323 return f"toolu_{digest[:24]}"324325326def _normalize_block_tool_use_id(block: dict) -> dict:327 """Return `block` with its `tool_use_id` normalized, if it carries one.328329 Mirrors `_normalize_tool_call_id` for `tool_result`-style content blocks so330 that a `tool_use_id` arriving pre-structured (e.g. on a `ToolMessage` whose331 content is already a list of `tool_result` blocks) stays consistent with its332 paired, normalized `tool_use.id`. A no-op for already-valid IDs.333 """334 if "tool_use_id" in block:335 return {**block, "tool_use_id": _normalize_tool_call_id(block["tool_use_id"])}336 return block337338339def _merge_messages(340 messages: Sequence[BaseMessage],341) -> list[SystemMessage | AIMessage | HumanMessage]:342 """Merge runs of human/tool messages into single human messages with content blocks.""" # noqa: E501343 merged: list = []344 for curr in messages:345 if isinstance(curr, ToolMessage):346 if (347 isinstance(curr.content, list)348 and curr.content349 and all(350 isinstance(block, dict) and block.get("type") == "tool_result"351 for block in curr.content352 )353 ):354 curr = HumanMessage(curr.content) # type: ignore[misc]355 else:356 tool_content = curr.content357 cache_ctrl = None358 # Extract cache_control from content blocks and hoist it359 # to the tool_result level. Anthropic's API does not360 # support cache_control on tool_result content sub-blocks.361 if isinstance(tool_content, list):362 cleaned = []363 for block in tool_content:364 if isinstance(block, dict) and "cache_control" in block:365 cache_ctrl = block["cache_control"]366 block = {367 k: v for k, v in block.items() if k != "cache_control"368 }369 cleaned.append(block)370 tool_content = cleaned371 tool_result: dict = {372 "type": "tool_result",373 "content": tool_content,374 "tool_use_id": _normalize_tool_call_id(curr.tool_call_id),375 "is_error": curr.status == "error",376 }377 if cache_ctrl:378 tool_result["cache_control"] = cache_ctrl379 curr = HumanMessage( # type: ignore[misc]380 [tool_result],381 )382 last = merged[-1] if merged else None383 if any(384 all(isinstance(m, c) for m in (curr, last))385 for c in (SystemMessage, HumanMessage)386 ):387 if isinstance(cast("BaseMessage", last).content, str):388 new_content: list = [389 {"type": "text", "text": cast("BaseMessage", last).content},390 ]391 else:392 new_content = copy.copy(cast("list", cast("BaseMessage", last).content))393 if isinstance(curr.content, str):394 new_content.append({"type": "text", "text": curr.content})395 else:396 new_content.extend(curr.content)397 merged[-1] = curr.model_copy(update={"content": new_content})398 else:399 merged.append(curr)400 return merged401402403def _format_data_content_block(block: dict) -> dict:404 """Format standard data content block to format expected by Anthropic."""405 if block["type"] == "image":406 if "url" in block:407 if block["url"].startswith("data:"):408 # Data URI409 formatted_block = {410 "type": "image",411 "source": _format_image(block["url"]),412 }413 else:414 formatted_block = {415 "type": "image",416 "source": {"type": "url", "url": block["url"]},417 }418 elif "base64" in block or block.get("source_type") == "base64":419 formatted_block = {420 "type": "image",421 "source": {422 "type": "base64",423 "media_type": block["mime_type"],424 "data": block.get("base64") or block.get("data", ""),425 },426 }427 elif "file_id" in block:428 formatted_block = {429 "type": "image",430 "source": {431 "type": "file",432 "file_id": block["file_id"],433 },434 }435 elif block.get("source_type") == "id":436 formatted_block = {437 "type": "image",438 "source": {439 "type": "file",440 "file_id": block["id"],441 },442 }443 else:444 msg = (445 "Anthropic only supports 'url', 'base64', or 'id' keys for image "446 "content blocks."447 )448 raise ValueError(449 msg,450 )451452 elif block["type"] == "file":453 if "url" in block:454 formatted_block = {455 "type": "document",456 "source": {457 "type": "url",458 "url": block["url"],459 },460 }461 elif "base64" in block or block.get("source_type") == "base64":462 formatted_block = {463 "type": "document",464 "source": {465 "type": "base64",466 "media_type": block.get("mime_type") or "application/pdf",467 "data": block.get("base64") or block.get("data", ""),468 },469 }470 elif block.get("source_type") == "text":471 formatted_block = {472 "type": "document",473 "source": {474 "type": "text",475 "media_type": block.get("mime_type") or "text/plain",476 "data": block["text"],477 },478 }479 elif "file_id" in block:480 formatted_block = {481 "type": "document",482 "source": {483 "type": "file",484 "file_id": block["file_id"],485 },486 }487 elif block.get("source_type") == "id":488 formatted_block = {489 "type": "document",490 "source": {491 "type": "file",492 "file_id": block["id"],493 },494 }495 else:496 msg = (497 "Anthropic only supports 'url', 'base64', or 'id' keys for file "498 "content blocks."499 )500 raise ValueError(msg)501502 elif block["type"] == "text-plain":503 formatted_block = {504 "type": "document",505 "source": {506 "type": "text",507 "media_type": block.get("mime_type") or "text/plain",508 "data": block["text"],509 },510 }511512 else:513 msg = f"Block of type {block['type']} is not supported."514 raise ValueError(msg)515516 if formatted_block:517 for key in ["cache_control", "citations", "title", "context"]:518 if key in block:519 formatted_block[key] = block[key]520 elif (metadata := block.get("extras")) and key in metadata:521 formatted_block[key] = metadata[key]522 elif (metadata := block.get("metadata")) and key in metadata:523 # Backward compat524 formatted_block[key] = metadata[key]525526 return formatted_block527528529def _format_text_block(block: dict) -> dict:530 """Narrow a text content block to fields supported by Anthropic's API.531532 Drops LangChain-internal fields (e.g. the ``id`` minted by533 ``create_text_block``) that Anthropic rejects as extra inputs.534 """535 formatted_block = {536 k: v537 for k, v in block.items()538 if k in ("type", "text", "cache_control", "citations")539 }540 # Clean up citations to remove null file_id fields541 if formatted_block.get("citations"):542 cleaned_citations = []543 for citation in formatted_block["citations"]:544 cleaned_citation = {545 k: v for k, v in citation.items() if not (k == "file_id" and v is None)546 }547 cleaned_citations.append(cleaned_citation)548 formatted_block["citations"] = cleaned_citations549 return formatted_block550551552_TOOL_CHANGE_BLOCK_TYPES = ("tool_addition", "tool_removal")553"""Anthropic-native system content blocks that change the tool set mid-conversation."""554555_MID_CONVERSATION_TOOL_CHANGES_BETA = "mid-conversation-tool-changes-2026-07-01"556"""Beta header required to send `tool_addition` / `tool_removal` blocks."""557558_INLINE_TOOLS_BETA = "inline-tools-2026-09-15"559"""Beta header required to define a tool in a `tool_addition` block."""560561562def _is_tool_change_block(block: object) -> bool:563 """Return whether a content block changes the tool set, in either spelling."""564 return (565 isinstance(block, dict)566 and _unwrap_non_standard(block).get("type") in _TOOL_CHANGE_BLOCK_TYPES567 )568569570def _has_tool_change_block(content: object) -> bool:571 """Return whether any block in `content` changes the tool set."""572 return isinstance(content, list) and any(_is_tool_change_block(b) for b in content)573574575def _has_inline_tool_definition(content: object) -> bool:576 """Return whether `content` defines a tool in a `tool_addition` block."""577 if not isinstance(content, list):578 return False579 return any(580 isinstance(block, dict)581 and block.get("type") == "tool_addition"582 and isinstance(tool := block.get("tool"), dict)583 and tool.get("type") == "tool_definition"584 for block in content585 )586587588def _format_system_content(589 content: str | list[Any],590 *,591 model: str | None = None,592 preserve_tool_changes: bool = False,593 stacklevel: int = 3,594) -> str | list[dict]:595 """Narrow system message content to what Anthropic accepts.596597 String content is passed through unchanged; promoting it to a single-element598 block array would invalidate existing callers' prompt caches.599600 Anthropic documents a closed set of system content blocks: `text` anywhere, plus601 `tool_addition` / `tool_removal` on a mid-conversation `system` turn. Anything602 else is rejected by the API, so it is dropped with a warning rather than603 forwarded. Blocks wrapped in core's `non_standard` escape hatch are unwrapped604 first, so both spellings behave identically.605606 Args:607 content: The system message's content.608 model: The model the request targets, used only in warning text.609 preserve_tool_changes: Whether tool-change blocks should be forwarded instead610 of dropped.611 stacklevel: Frames to skip when attributing a warning, so it points at the612 caller of `_format_messages` rather than at this module. The default613 suits a direct call; a caller reached through a helper adds a frame.614615 Returns:616 Content narrowed to the blocks Anthropic accepts in this position.617 """618 if not isinstance(content, list):619 return content620621 formatted: list[dict] = []622 for raw_block in content:623 if not isinstance(raw_block, dict):624 formatted.append({"type": "text", "text": raw_block})625 continue626627 block = _unwrap_non_standard(raw_block)628 block_type = block.get("type")629 if block_type == "text":630 formatted.append(_format_text_block(block))631 elif block_type in _TOOL_CHANGE_BLOCK_TYPES:632 if preserve_tool_changes:633 formatted.append(block)634 else:635 warnings.warn(636 f"Tool-change block {block_type!r} was dropped: it is only "637 "valid on a `SystemMessage` sent in place, and this one was "638 "hoisted into the top-level `system` field. Use a model whose "639 "profile sets `mid_conversation_system_messages` and place "640 "the message after a human or tool message, either last or "641 f"before an AI message (model: {model!r}).",642 UserWarning,643 stacklevel=stacklevel,644 )645 else:646 warnings.warn(647 f"Unrecognized system content block {block_type!r} was dropped. "648 "Anthropic accepts `text` in any system message, plus "649 "`tool_addition` and `tool_removal` on a mid-conversation one.",650 UserWarning,651 stacklevel=stacklevel,652 )653 return formatted654655656def _warn_system_message_hoisted(model: str | None) -> None:657 """Warn that a non-leading system message was hoisted."""658 warnings.warn(659 "A non-leading `SystemMessage` was moved to the top-level `system` field "660 "and now applies to the entire conversation. To send it in place, use a "661 "model whose profile sets `mid_conversation_system_messages` and place "662 "it after a human or tool message, either last or before an AI message "663 f"(model: {model!r}).",664 UserWarning,665 stacklevel=3,666 )667668669def _is_server_tool_result_block(block: object) -> bool:670 """Return whether a content block is a server-side tool result."""671 return (672 isinstance(block, dict)673 and isinstance(block.get("type"), str)674 and block["type"].endswith("_tool_result")675 )676677678def _previous_turn_allows_system(previous_turn: dict | None) -> bool:679 """Return whether a system message may follow the formatted turn."""680 if previous_turn is None:681 return False682683 previous_role = previous_turn.get("role")684 previous_content = previous_turn.get("content")685 return previous_role == "user" or (686 previous_role == "assistant"687 and isinstance(previous_content, list)688 and bool(previous_content)689 and _is_server_tool_result_block(previous_content[-1])690 )691692693def _format_in_place_system_messages(694 pending_system: Sequence[BaseMessage],695 *,696 model: str | None,697) -> list[dict]:698 """Format system messages that keep their position in the message array.699700 A message whose content is narrowed away entirely is omitted: Anthropic701 rejects a `system` turn with empty content, and the dropped blocks have702 already been warned about.703704 Args:705 pending_system: System messages awaiting emission, in order.706 model: The model the request targets, used only in warning text.707708 Returns:709 Formatted `system`-role turns.710 """711 turns: list[dict] = []712 for pending in pending_system:713 content = _format_system_content(714 pending.content,715 model=model,716 preserve_tool_changes=True,717 # This helper sits between `_format_messages` and the warning site.718 stacklevel=4,719 )720 if content == []:721 continue722 turns.append({"role": "system", "content": content})723 return turns724725726def _format_messages(727 messages: Sequence[BaseMessage],728 *,729 model: str | None,730 mid_conversation_system_messages: bool = False,731) -> tuple[str | list[dict] | None, list[dict]]:732 """Format messages for Anthropic's API.733734 Args:735 messages: Messages to format.736 model: The model the request targets, used only in warning text.737 mid_conversation_system_messages: Whether a non-leading system message738 may be sent in place. When `False`, it is hoisted into `system`.739 """740 system: str | list[dict] | None = None741 formatted_messages: list[dict] = []742 toolsets: dict[str, str] = {}743 merged_messages = _merge_messages(messages)744 last_non_system_index = max(745 (i for i, m in enumerate(merged_messages) if m.type != "system"),746 default=-1,747 )748 pending_system: list[BaseMessage] = []749 for _i, message in enumerate(merged_messages):750 if message.type == "system":751 if _i == 0:752 system = _format_system_content(753 message.content,754 model=model,755 preserve_tool_changes=True,756 )757 continue758 if mid_conversation_system_messages and (759 pending_system760 or _previous_turn_allows_system(761 formatted_messages[-1] if formatted_messages else None762 )763 ):764 pending_system.append(message)765 continue766 if system is not None:767 msg = "Received multiple non-consecutive system messages."768 raise ValueError(msg)769 system = _format_system_content(message.content, model=model)770 _warn_system_message_hoisted(model)771 continue772773 role = _message_type_lookups[message.type]774 content: str | list775776 if not isinstance(message.content, str):777 # parse as dict778 if not isinstance(message.content, list):779 msg = "Anthropic message content must be str or list of dicts"780 raise ValueError(781 msg,782 )783784 # populate content785 content = []786 for block in message.content:787 if isinstance(block, str):788 content.append({"type": "text", "text": block})789 elif isinstance(block, dict):790 if "type" not in block:791 msg = "Dict content block must have a type key"792 raise ValueError(msg)793 if block["type"] in ("reasoning", "function_call") and (794 not isinstance(message, AIMessage)795 or message.response_metadata.get("model_provider")796 != "anthropic"797 ):798 continue799 # The Messages API has no refusal input block.800 if block["type"] == "refusal":801 continue802 if block["type"] == "image_url":803 # convert format804 source = _format_image(block["image_url"]["url"])805 content.append({"type": "image", "source": source})806 elif is_data_content_block(block):807 content.append(_format_data_content_block(block))808 elif block["type"] == "tool_use":809 # If a tool_call with the same id as a tool_use content block810 # exists, the tool_call is preferred.811 if (812 isinstance(message, AIMessage)813 and (block["id"] in [tc["id"] for tc in message.tool_calls])814 and not block.get("caller")815 ):816 overlapping = [817 tc818 for tc in message.tool_calls819 if tc["id"] == block["id"]820 ]821 tool_blocks = _lc_tool_calls_to_anthropic_tool_use_blocks(822 overlapping,823 )824 if toolset_name := block.get("toolset_name"):825 for tool_block in tool_blocks:826 tool_block["toolset_name"] = toolset_name827 content.extend(tool_blocks)828 else:829 if tool_input := block.get("input"):830 args = tool_input831 elif "partial_json" in block:832 try:833 args = json.loads(block["partial_json"] or "{}")834 except json.JSONDecodeError:835 args = {}836 else:837 args = {}838 tool_use_block = _AnthropicToolUse(839 type="tool_use",840 name=block["name"],841 input=args,842 id=cast("str", _normalize_tool_call_id(block["id"])),843 )844 if caller := block.get("caller"):845 tool_use_block["caller"] = caller846 if toolset_name := block.get("toolset_name"):847 tool_use_block["toolset_name"] = toolset_name848 content.append(tool_use_block)849 elif block["type"] in ("server_tool_use", "mcp_tool_use"):850 formatted_block = {851 k: v852 for k, v in block.items()853 if k854 in (855 "type",856 "id",857 "input",858 "name",859 "server_name", # for mcp_tool_use860 "cache_control",861 )862 }863 caller = block.get("caller")864 if caller and caller.get("type") != "direct":865 formatted_block["caller"] = caller866 # Attempt to parse streamed output867 if block.get("input") == {} and "partial_json" in block:868 try:869 input_ = json.loads(block["partial_json"])870 if input_:871 formatted_block["input"] = input_872 except json.JSONDecodeError:873 pass874 content.append(formatted_block)875 elif block["type"] == "text":876 text = block.get("text", "")877 # Only add non-empty strings for now as empty ones are not878 # accepted.879 # https://github.com/anthropics/anthropic-sdk-python/issues/461880 if text.strip():881 content.append(_format_text_block(block))882 elif block["type"] == "thinking":883 formatted_thinking = {884 k: v885 for k, v in block.items()886 if k in ("type", "thinking", "cache_control", "signature")887 }888 if "signature" in formatted_thinking:889 formatted_thinking.setdefault("thinking", "")890 content.append(formatted_thinking)891 elif block["type"] == "redacted_thinking":892 content.append(893 {894 k: v895 for k, v in block.items()896 if k in ("type", "cache_control", "data")897 },898 )899 elif (900 block["type"] == "tool_result"901 and isinstance(block.get("content"), list)902 and any(903 isinstance(item, dict)904 and item.get("type") == "tool_reference"905 for item in block["content"]906 )907 ):908 # Tool search results with tool_reference blocks909 content.append(910 _normalize_block_tool_use_id(911 {912 k: v913 for k, v in block.items()914 if k915 in (916 "type",917 "content",918 "tool_use_id",919 "cache_control",920 )921 },922 ),923 )924 elif block["type"] == "tool_search_tool_result":925 # Omit streaming-only fields, such as `index`, from results.926 content.append(927 _normalize_block_tool_use_id(928 {929 k: v930 for k, v in block.items()931 if k932 in (933 "type",934 "content",935 "tool_use_id",936 "cache_control",937 )938 or (939 k == "caller"940 and v941 and v.get("type") != "direct"942 )943 },944 ),945 )946 elif block["type"] == "tool_result":947 # Regular tool results that need content formatting948 tool_content = _format_messages(949 [HumanMessage(block["content"])],950 model=None,951 )[1][0]["content"]952 content.append(953 _normalize_block_tool_use_id(954 {**block, "content": tool_content},955 ),956 )957 elif block["type"] in (958 "code_execution_tool_result",959 "bash_code_execution_tool_result",960 "text_editor_code_execution_tool_result",961 "mcp_tool_result",962 "web_search_tool_result",963 "web_fetch_tool_result",964 ):965 content.append(966 _normalize_block_tool_use_id(967 {968 k: v969 for k, v in block.items()970 if k971 in (972 "type",973 "content",974 "tool_use_id",975 "is_error", # for mcp_tool_result976 "cache_control",977 "retrieved_at", # for web_fetch_tool_result978 )979 or (980 k == "caller"981 and v982 and v.get("type") != "direct"983 )984 },985 ),986 )987 elif block["type"] in ("advisor_tool_result", "compaction"):988 content.append({k: v for k, v in block.items() if k != "index"})989 else:990 content.append(block)991 else:992 msg = (993 f"Content blocks must be str or dict, instead was: "994 f"{type(block)}"995 )996 raise ValueError(997 msg,998 )999 else:1000 content = message.content10011002 if isinstance(message, AIMessage) and (1003 message.tool_calls or message.invalid_tool_calls1004 ):1005 content = content or []1006 content = (1007 [{"type": "text", "text": message.content}]1008 if isinstance(content, str) and content1009 else content1010 )1011 tool_use_ids = [1012 cast("dict", block)["id"]1013 for block in content1014 if cast("dict", block)["type"] == "tool_use"1015 ]1016 # `tool_use_ids` are already normalized via the branches above, so1017 # compare against the normalized tool-call ID to avoid emitting a1018 # duplicate `tool_use` block when the original ID was rewritten.1019 missing_tool_calls = [1020 tc1021 for tc in message.tool_calls1022 if _normalize_tool_call_id(tc["id"]) not in tool_use_ids1023 ]1024 cast("list", content).extend(1025 _lc_tool_calls_to_anthropic_tool_use_blocks(missing_tool_calls),1026 )1027 tool_use_ids.extend(1028 cast("str", _normalize_tool_call_id(tc["id"]))1029 for tc in missing_tool_calls1030 )1031 for invalid_call in message.invalid_tool_calls:1032 tool_call_id = invalid_call.get("id")1033 tool_name = invalid_call.get("name")1034 if not tool_call_id or not tool_name:1035 continue1036 normalized_id = _normalize_tool_call_id(tool_call_id)1037 if normalized_id in tool_use_ids:1038 continue1039 try:1040 args = json.loads(invalid_call.get("args") or "{}")1041 except json.JSONDecodeError:1042 args = {}1043 cast("list", content).append(1044 _AnthropicToolUse(1045 type="tool_use",1046 name=tool_name,1047 input=args if isinstance(args, dict) else {},1048 id=cast("str", normalized_id),1049 )1050 )1051 tool_use_ids.append(normalized_id)10521053 if role == "assistant" and _i == last_non_system_index:1054 if isinstance(content, str):1055 content = content.rstrip()1056 elif (1057 isinstance(content, list)1058 and content1059 and isinstance(content[-1], dict)1060 and content[-1].get("type") == "text"1061 ):1062 content[-1]["text"] = content[-1]["text"].rstrip()10631064 if not content and role == "assistant" and _i < last_non_system_index:1065 # anthropic.BadRequestError: Error code: 400: all messages must have1066 # non-empty content except for the optional final assistant message1067 continue1068 if pending_system:1069 if role == "assistant":1070 formatted_messages.extend(1071 _format_in_place_system_messages(pending_system, model=model)1072 )1073 else:1074 for pending in pending_system:1075 if system is not None:1076 msg = "Received multiple non-consecutive system messages."1077 raise ValueError(msg)1078 system = _format_system_content(pending.content, model=model)1079 _warn_system_message_hoisted(model)1080 pending_system = []1081 if isinstance(content, list):1082 for block in content:1083 if not isinstance(block, dict):1084 continue1085 if block.get("type") == "tool_use" and block.get("toolset_name"):1086 toolsets[block["id"]] = block["toolset_name"]1087 elif block.get("type") == "tool_result" and (1088 toolset_name := toolsets.get(block.get("tool_use_id", ""))1089 ):1090 block.setdefault("toolset_name", toolset_name)1091 formatted_messages.append({"role": role, "content": content})10921093 formatted_messages.extend(1094 _format_in_place_system_messages(pending_system, model=model)1095 )1096 return system, formatted_messages109710981099def _container_id(container: Any) -> str | None:1100 """Return the container ID from either accepted `container` shape."""1101 if isinstance(container, str):1102 return container1103 if isinstance(container, dict):1104 return container.get("id")1105 return None110611071108def _collect_code_execution_tool_ids(formatted_messages: list[dict]) -> set[str]:1109 """Collect `tool_use` IDs that were called by `code_execution`.11101111 These blocks cannot have `cache_control` applied per Anthropic API1112 requirements.1113 """1114 code_execution_tool_ids: set[str] = set()11151116 for message in formatted_messages:1117 if message.get("role") != "assistant":1118 continue1119 content = message.get("content", [])1120 if not isinstance(content, list):1121 continue1122 for block in content:1123 if not isinstance(block, dict):1124 continue1125 if block.get("type") != "tool_use":1126 continue1127 caller = block.get("caller")1128 if isinstance(caller, dict):1129 caller_type = caller.get("type", "")1130 if caller_type.startswith("code_execution"):1131 tool_id = block.get("id")1132 if tool_id:1133 code_execution_tool_ids.add(tool_id)11341135 return code_execution_tool_ids113611371138def _is_code_execution_related_block(1139 block: dict,1140 code_execution_tool_ids: set[str],1141) -> bool:1142 """Return whether a content block is related to `code_execution`.11431144 Returns `True` for blocks that should NOT have `cache_control` applied.1145 """1146 if not isinstance(block, dict):1147 return False11481149 block_type = block.get("type")11501151 if block_type == "tool_use":1152 caller = block.get("caller")1153 if isinstance(caller, dict):1154 caller_type = caller.get("type", "")1155 if caller_type.startswith("code_execution"):1156 return True11571158 if block_type == "tool_result":1159 tool_use_id = block.get("tool_use_id")1160 if tool_use_id and tool_use_id in code_execution_tool_ids:1161 return True11621163 return False116411651166def _reasoning_effort_levels(profile: object) -> tuple[str, ...]:1167 """Return the reasoning-effort levels declared in a model's profile, if any.11681169 Defensive against a missing/malformed profile: an absent `profile`, a1170 non-mapping value, or a missing/non-list `reasoning_effort_levels` value is1171 treated as "no levels declared" rather than raising.1172 """1173 if not isinstance(profile, Mapping):1174 return ()1175 levels = profile.get("reasoning_effort_levels")1176 if not isinstance(levels, (list, tuple)):1177 return ()1178 return tuple(levels)117911801181def _supports_forced_tool_choice(model: str) -> bool:1182 """Return whether the model accepts `tool_choice` types `any` and `tool`."""1183 return not model.startswith(1184 (1185 "claude-fable-5-1",1186 "claude-fable-5-2",1187 "claude-mythos-5-2",1188 "claude-opus-5-5",1189 "claude-sonnet-5-5",1190 )1191 )119211931194def _is_direct_anthropic_llm_type(llm_type: object) -> bool:1195 """Return whether an `_llm_type` reaches Claude via the direct Anthropic API.11961197 Only the direct API accepts the top-level `cache_control` request param.1198 Subclasses that route through other transports (Bedrock, future backends)1199 override `_llm_type` and must expand `cache_control` kwargs into1200 block-level breakpoints instead.12011202 Non-string `_llm_type` values return `False` rather than raising, so a1203 misbehaving subclass falls through to the safer non-direct branch.1204 """1205 return llm_type == "anthropic-chat"120612071208def _apply_cache_control_to_last_eligible_block(1209 formatted_messages: list[dict],1210 cache_control: Any,1211 code_execution_tool_ids: set[str],1212) -> bool:1213 """Place `cache_control` on the last block eligible for a breakpoint.12141215 Walks messages newest-to-oldest and, within each, blocks newest-to-oldest,1216 skipping `code_execution`-related blocks (Anthropic rejects breakpoints1217 there). String message content is promoted to a single text block so the1218 breakpoint can be attached.12191220 Returns:1221 `True` if a breakpoint was applied, `False` if every candidate was1222 `code_execution`-related (caller should warn and drop the kwarg).1223 """1224 for formatted_message in reversed(formatted_messages):1225 content = formatted_message.get("content")1226 if isinstance(content, list) and content:1227 for block in reversed(content):1228 if not isinstance(block, dict):1229 continue1230 if _is_code_execution_related_block(block, code_execution_tool_ids):1231 continue1232 block["cache_control"] = cache_control1233 return True1234 elif isinstance(content, str):1235 formatted_message["content"] = [1236 {1237 "type": "text",1238 "text": content,1239 "cache_control": cache_control,1240 }1241 ]1242 return True1243 return False124412451246class AnthropicContextOverflowError(anthropic.BadRequestError, ContextOverflowError):1247 """BadRequestError raised when input exceeds Anthropic's context limit."""124812491250class AnthropicAuthenticationError(1251 anthropic.AuthenticationError, ModelAuthenticationError1252):1253 """Anthropic authentication error classified as a LangChain model error."""125412551256class AnthropicPermissionDeniedError(1257 anthropic.PermissionDeniedError, ModelPermissionDeniedError1258):1259 """Anthropic permission error classified as a LangChain model error."""126012611262class AnthropicInvalidRequestError(anthropic.BadRequestError, ModelInvalidRequestError):1263 """Anthropic bad-request error classified as a LangChain model error."""126412651266class AnthropicModelNotFoundError(anthropic.NotFoundError, ModelNotFoundError):1267 """Anthropic not-found error classified as a LangChain model error."""126812691270class AnthropicRateLimitError(anthropic.RateLimitError, ModelRateLimitError):1271 """Anthropic rate-limit error classified as a LangChain model error."""127212731274class AnthropicAPIError(anthropic.InternalServerError, ModelAPIError):1275 """Anthropic server error classified as a LangChain model error."""127612771278class AnthropicOverloadedError(anthropic.OverloadedError, ModelAPIError):1279 """Anthropic overloaded error (HTTP 529) classified as a LangChain model error."""128012811282class AnthropicConnectionError(anthropic.APIConnectionError, ModelConnectionError):1283 """Anthropic connection error classified as a LangChain model error."""128412851286class AnthropicTimeoutError(anthropic.APITimeoutError, ModelTimeoutError):1287 """Anthropic timeout error classified as a LangChain model error."""128812891290def _raise_if_authentication_error(e: TypeError) -> None:1291 """Re-raise anthropic SDK's missing-credentials `TypeError` with guidance."""1292 if "Could not resolve authentication method" in str(e):1293 msg = (1294 "Anthropic authentication failed: no API key or authorization "1295 "credentials were provided. Set the ANTHROPIC_API_KEY environment "1296 "variable, pass api_key=... to ChatAnthropic, or provide "1297 'credentials via default_headers={"Authorization": ...}. If you '1298 "are routing through the LangSmith gateway, set LANGSMITH_GATEWAY "1299 "and LANGSMITH_GATEWAY_API_KEY."1300 )1301 raise TypeError(msg) from e130213031304def _handle_anthropic_bad_request(e: anthropic.BadRequestError) -> None:1305 """Handle Anthropic BadRequestError."""1306 if "prompt is too long" in e.message:1307 raise AnthropicContextOverflowError(1308 message=e.message, response=e.response, body=e.body1309 ) from e1310 if ("messages: at least one message is required") in e.message:1311 message = "Received only system message(s). "1312 warnings.warn(message, stacklevel=2)1313 raise AnthropicInvalidRequestError(1314 message=e.message, response=e.response, body=e.body1315 ) from e131613171318def _handle_anthropic_api_error(e: anthropic.APIError) -> None:1319 """Re-raise an Anthropic SDK error as its LangChain-classified equivalent."""1320 if isinstance(e, anthropic.AuthenticationError):1321 raise AnthropicAuthenticationError(1322 message=e.message, response=e.response, body=e.body1323 ) from e1324 if isinstance(e, anthropic.PermissionDeniedError):1325 raise AnthropicPermissionDeniedError(1326 message=e.message, response=e.response, body=e.body1327 ) from e1328 if isinstance(e, anthropic.NotFoundError):1329 raise AnthropicModelNotFoundError(1330 message=e.message, response=e.response, body=e.body1331 ) from e1332 if isinstance(e, anthropic.RateLimitError):1333 raise AnthropicRateLimitError(1334 message=e.message, response=e.response, body=e.body1335 ) from e1336 if isinstance(e, anthropic.OverloadedError):1337 raise AnthropicOverloadedError(1338 message=e.message, response=e.response, body=e.body1339 ) from e1340 if isinstance(e, anthropic.InternalServerError):1341 raise AnthropicAPIError(1342 message=e.message, response=e.response, body=e.body1343 ) from e1344 # `APITimeoutError` subclasses `APIConnectionError`, so check it first.1345 if isinstance(e, anthropic.APITimeoutError):1346 raise AnthropicTimeoutError(e.request) from e1347 if isinstance(e, anthropic.APIConnectionError):1348 raise AnthropicConnectionError(message=e.message, request=e.request) from e1349 raise135013511352class ChatAnthropic(BaseChatModel):1353 """Anthropic (Claude) chat models.13541355 See the [LangChain docs for `ChatAnthropic`](https://docs.langchain.com/oss/python/integrations/chat/anthropic)1356 for tutorials, feature walkthroughs, and examples.13571358 See the [Claude Platform docs](https://platform.claude.com/docs/en/about-claude/models/overview)1359 for a list of the latest models, their capabilities, and pricing.13601361 Example:1362 ```python1363 # pip install -U langchain-anthropic1364 # export ANTHROPIC_API_KEY="your-api-key"13651366 from langchain_anthropic import ChatAnthropic13671368 model = ChatAnthropic(1369 model="claude-sonnet-4-5-20250929",1370 # temperature=,1371 # max_tokens=,1372 # timeout=,1373 # max_retries=,1374 # base_url="...",1375 # Refer to API reference for full list of parameters1376 )1377 ```13781379 Example: Add a tool mid-conversation1380 ```python1381 from langchain_core.messages import HumanMessage, SystemMessage1382 from langchain_anthropic import ChatAnthropic13831384 model = ChatAnthropic(model="claude-opus-5-5")1385 model.invoke(1386 [1387 HumanMessage("What time is it?"),1388 SystemMessage(1389 [1390 {1391 "type": "tool_addition",1392 "tool": {1393 "type": "tool_definition",1394 "definition": {1395 "name": "get_time",1396 "description": "Get the current time.",1397 "input_schema": {1398 "type": "object",1399 "properties": {},1400 },1401 },1402 },1403 }1404 ]1405 ),1406 ]1407 )1408 ```14091410 Note:1411 Any param which is not explicitly supported will be passed directly to1412 [`Anthropic.messages.create(...)`](https://platform.claude.com/docs/en/api/python/messages/create)1413 each time to the model is invoked.1414 """14151416 model_config = ConfigDict(1417 populate_by_name=True,1418 )14191420 model: str = Field(alias="model_name")1421 """Model name to use."""14221423 max_tokens: int | None = Field(default=None, alias="max_tokens_to_sample")1424 """Denotes the number of tokens to predict per generation.14251426 If not specified, this is set dynamically using the model's `max_output_tokens`1427 from its model profile.14281429 See docs on [model profiles](https://docs.langchain.com/oss/python/langchain/models#model-profiles)1430 for more information.1431 """14321433 temperature: float | None = None1434 """A non-negative float that tunes the degree of randomness in generation."""14351436 top_k: int | None = None1437 """Number of most likely tokens to consider at each step."""14381439 top_p: float | None = None1440 """Total probability mass of tokens to consider at each step."""14411442 default_request_timeout: float | None = Field(None, alias="timeout")1443 """Timeout for requests to Claude API."""14441445 # sdk default = 2: https://github.com/anthropics/anthropic-sdk-python?tab=readme-ov-file#retries1446 max_retries: int = 21447 """Number of retries allowed for requests sent to the Claude API."""14481449 stop_sequences: list[str] | None = Field(None, alias="stop")1450 """Default stop sequences."""14511452 anthropic_api_url: str | None = Field(default=None, alias="base_url")1453 """Base URL for API requests. Only specify if using a proxy or service emulator.14541455 If a value isn't passed in, will attempt to read the value first from1456 `ANTHROPIC_API_URL` and if that is not set, `ANTHROPIC_BASE_URL`.14571458 If `LANGSMITH_GATEWAY` is set, it is used as a fallback after those env vars.1459 """14601461 anthropic_api_key: SecretStr = Field(default=SecretStr(""), alias="api_key")1462 """Automatically read from env var `ANTHROPIC_API_KEY` if not provided.14631464 If `LANGSMITH_GATEWAY` is enabled and the base URL points at the gateway,1465 `LANGSMITH_GATEWAY_API_KEY` is used instead.1466 """14671468 anthropic_proxy: str | None = Field(1469 default_factory=from_env("ANTHROPIC_PROXY", default=None)1470 )1471 """Proxy to use for the Anthropic clients, will be used for every API call.14721473 If not provided, will attempt to read from the `ANTHROPIC_PROXY` environment1474 variable.1475 """14761477 default_headers: Mapping[str, str] | None = None1478 """Headers to pass to the Anthropic clients, will be used for every API call."""14791480 _langsmith_gateway_headers: dict[str, str] | None = PrivateAttr(default=None)1481 """Headers from `langsmith_gateway`, sent by the client but never serialized."""14821483 betas: list[str] | None = None1484 """List of beta features to enable. If specified, invocations will be routed1485 through `client.beta.messages.create`.14861487 Example: `#!python betas=["token-efficient-tools-2025-02-19"]`1488 """1489 # Can also be passed in w/ model_kwargs, but having it as a param makes better devx1490 #1491 # Precedence order:1492 # 1. Call-time kwargs (e.g., llm.invoke(..., betas=[...]))1493 # 2. model_kwargs (e.g., ChatAnthropic(model_kwargs={"betas": [...]}))1494 # 3. Direct parameter (e.g., ChatAnthropic(betas=[...]))14951496 model_kwargs: dict[str, Any] = Field(default_factory=dict)14971498 streaming: bool = False1499 """Whether to use streaming or not."""15001501 stream_usage: bool = True1502 """Whether to include usage metadata in streaming output.15031504 If `True`, additional message chunks will be generated during the stream including1505 usage metadata.1506 """15071508 thinking: dict[str, Any] | None = Field(default=None)1509 """Parameters for Claude reasoning.15101511 Examples:15121513 - `#!python {"type": "enabled", "budget_tokens": 10_000}` (pre-4.7 models)1514 - `#!python {"type": "adaptive"}` (Opus 4.6+, Opus 5, Opus 5.5, Sonnet 5)1515 - `#!python {"type": "adaptive", "display": "summarized"}` (Opus 4.7+,1516 Opus 5, Opus 5.5, Sonnet 5)1517 - `#!python {"type": "disabled"}` (Opus 5 and Sonnet 5, where adaptive1518 thinking is on by default)15191520 !!! note "Claude Opus 4.7+, Opus 5, Opus 5.5, and Sonnet 5"15211522 `budget_tokens` is removed on these models — use `{"type": "adaptive"}`1523 with `output_config.effort` to control reasoning effort. The default1524 `display` is `"omitted"`; set it to `"summarized"` to receive1525 summarized reasoning in the response. On Opus 5, disabled thinking is1526 supported only at `"high"` effort or below. On Opus 5.5, thinking1527 can't be disabled; omit `thinking` and use `output_config.effort`.1528 """15291530 output_config: dict[str, Any] | None = None1531 """Configuration options for the model's output.15321533 Supports the following keys:15341535 - `effort`: Controls how many tokens Claude uses when responding.1536 One of `"max"`, `"xhigh"`, `"high"`, `"medium"`, or `"low"`.1537 - `format`: Structured output format configuration (typically set via1538 `with_structured_output`).1539 - `task_budget`: Advisory token budget for an agentic loop (beta).1540 E.g., `#!python {"type": "tokens", "total": 128_000}`.15411542 Example:15431544 .. code-block:: python15451546 ChatAnthropic(1547 model="claude-opus-4-7",1548 output_config={1549 "effort": "xhigh",1550 "task_budget": {"type": "tokens", "total": 128_000},1551 },1552 )15531554 See Anthropic docs on1555 [extended output](https://platform.claude.com/docs/en/api/go/beta/messages/create).1556 """15571558 reasoning_effort: Literal["max", "xhigh", "high", "medium", "low"] | None = Field(1559 default=None,1560 alias="effort",1561 )1562 """Reasoning effort.15631564 Configures `output_config.effort`. If `thinking` isn't set explicitly,1565 defaults it to `{"type": "adaptive", "display": "summarized"}`. Can also1566 be passed at call time (for example,1567 `model.invoke(..., reasoning_effort="high")`).15681569 !!! note "`effort` alias"15701571 `effort` is also accepted as an alias for this field, at both1572 construction and call time. If both `effort` and `reasoning_effort` are1573 set, `effort` wins (Pydantic's alias-resolution precedence).15741575 !!! note15761577 On most models, setting `reasoning_effort` to `'high'` produces exactly1578 the same behavior as omitting the parameter altogether. On Opus 5.5 the1579 default is `'medium'`.15801581 Example: `reasoning_effort="medium"`1582 """15831584 mcp_servers: list[dict[str, Any]] | None = None1585 """List of MCP servers to use for the request.15861587 Example: `#!python mcp_servers=[{"type": "url", "url": "https://mcp.example.com/mcp",1588 "name": "example-mcp"}]`1589 """15901591 context_management: dict[str, Any] | None = None1592 """Configuration for1593 [context management](https://platform.claude.com/docs/en/build-with-claude/context-editing).1594 """15951596 container: dict[str, Any] | str | None = None1597 """Code execution container for the request.15981599 Either a container ID from a previous response, or a dict of container1600 parameters — notably1601 [skills](https://platform.claude.com/docs/en/build-with-claude/skills-guide)1602 to load into the container. Skills require a1603 [code execution](https://docs.langchain.com/oss/python/integrations/chat/anthropic#code-execution)1604 tool to be bound.16051606 ```python1607 model = ChatAnthropic(1608 model="claude-opus-5",1609 container={1610 "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]1611 },1612 ).bind_tools([{"type": "code_execution_20260521", "name": "code_execution"}])1613 ```16141615 Can also be passed at call time, which overrides the value set here.1616 """16171618 reuse_last_container: bool | None = None1619 """Automatically reuse container from most recent response (code execution).16201621 When using the built-in1622 [code execution tool](https://docs.langchain.com/oss/python/integrations/chat/anthropic#code-execution),1623 model responses will include container metadata. Set `reuse_last_container=True`1624 to automatically reuse the container from the most recent response for subsequent1625 invocations.1626 """16271628 inference_geo: str | None = None1629 """Controls where model inference runs. See Anthropic's1630 [data residency](https://platform.claude.com/docs/en/build-with-claude/data-residency)1631 docs for more information.1632 """16331634 user_profile_id: str | None = None1635 """User profile ID to attribute the request to.16361637 Use when acting on behalf of a party other than your organization. Setting this1638 automatically enables the required `user-profiles` beta, routing the request1639 through `client.beta.messages.create`.16401641 Can also be passed at call time, which overrides the value set here (for example,1642 `model.invoke(..., user_profile_id="uprof_...")`).1643 """16441645 @property1646 def effort(self) -> Literal["max", "xhigh", "high", "medium", "low"] | None:1647 """Alias for `reasoning_effort`."""1648 return self.reasoning_effort16491650 @property1651 def _llm_type(self) -> str:1652 """Return type of chat model."""1653 return "anthropic-chat"16541655 @property1656 def _uses_gateway(self) -> bool:1657 """Whether requests are routed through the LangSmith gateway."""1658 return self.anthropic_api_key.get_secret_value().startswith("lsv2_")16591660 @property1661 def lc_secrets(self) -> dict[str, str]:1662 """Return a mapping of secret keys to environment variables."""1663 return {1664 "anthropic_api_key": "ANTHROPIC_API_KEY",1665 "mcp_servers": "ANTHROPIC_MCP_SERVERS",1666 }16671668 @classmethod1669 def is_lc_serializable(cls) -> bool:1670 """Whether the class is serializable in langchain."""1671 return True16721673 @classmethod1674 def get_lc_namespace(cls) -> list[str]:1675 """Get the namespace of the LangChain object.16761677 Returns:1678 `["langchain", "chat_models", "anthropic"]`1679 """1680 return ["langchain", "chat_models", "anthropic"]16811682 @property1683 def _identifying_params(self) -> dict[str, Any]:1684 """Get the identifying parameters."""1685 output_config = dict(self.output_config or {})1686 if self.reasoning_effort:1687 output_config["effort"] = self.reasoning_effort1688 return {1689 "model": self.model,1690 "max_tokens": self.max_tokens,1691 "temperature": self.temperature,1692 "top_k": self.top_k,1693 "top_p": self.top_p,1694 "model_kwargs": self.model_kwargs,1695 "streaming": self.streaming,1696 "max_retries": self.max_retries,1697 "default_request_timeout": self.default_request_timeout,1698 "thinking": self.thinking,1699 "output_config": output_config or self.output_config,1700 }17011702 def _get_ls_params(1703 self,1704 stop: list[str] | None = None,1705 **kwargs: Any,1706 ) -> LangSmithParams:1707 """Get standard params for tracing."""1708 params = self._get_invocation_params(stop=stop, **kwargs)1709 ls_params = LangSmithParams(1710 ls_provider="anthropic",1711 ls_model_name=params.get("model", self.model),1712 ls_model_type="chat",1713 ls_temperature=params.get("temperature", self.temperature),1714 )1715 if ls_max_tokens := params.get("max_tokens", self.max_tokens):1716 ls_params["ls_max_tokens"] = ls_max_tokens1717 if ls_stop := stop or params.get("stop", None):1718 ls_params["ls_stop"] = ls_stop1719 return ls_params17201721 @model_validator(mode="before")1722 @classmethod1723 def set_default_max_tokens(cls, values: dict[str, Any]) -> Any:1724 """Set default `max_tokens` from model profile with fallback."""1725 if values.get("max_tokens") is None:1726 model = values.get("model") or values.get("model_name")1727 profile = _get_default_model_profile(model) if model else {}1728 values["max_tokens"] = profile.get(1729 "max_output_tokens", _FALLBACK_MAX_OUTPUT_TOKENS1730 )1731 return values17321733 @model_validator(mode="before")1734 @classmethod1735 def build_extra(cls, values: dict) -> Any:1736 """Build model kwargs."""1737 all_required_field_names = get_pydantic_field_names(cls)1738 return _build_model_kwargs(values, all_required_field_names)17391740 @model_validator(mode="after")1741 def _set_anthropic_version(self) -> Self:1742 """Set package version in metadata."""1743 self._add_version("langchain-anthropic", __version__)1744 return self17451746 @model_validator(mode="after")1747 def _set_langsmith_gateway_headers(self) -> Self:1748 """Keep `langsmith_gateway` headers for the lazily built clients."""1749 if self._langsmith_gateway_headers is None:1750 self._langsmith_gateway_headers = _gateway_headers()1751 return self17521753 @model_validator(mode="before")1754 @classmethod1755 def _resolve_gateway(cls, values: Any) -> Any:1756 """Resolve the base URL and API key, applying LangSmith gateway settings.17571758 An explicit ``base_url``/``api_key`` always wins. Otherwise the base URL1759 falls back to ``ANTHROPIC_API_URL``/``ANTHROPIC_BASE_URL``, then the1760 LangSmith gateway, then the Anthropic default. The gateway key is1761 preferred only when the base URL came from the gateway; for any other1762 endpoint the provider key wins, and the gateway key is a candidate only1763 when the gateway is enabled.1764 """1765 if isinstance(values, dict):1766 if _langsmith_gateway_active():1767 values["anthropic_proxy"] = None1768 _apply_gateway_config(1769 values,1770 cls,1771 base_url_field="anthropic_api_url",1772 api_key_field="anthropic_api_key",1773 provider_path="anthropic",1774 base_url_env=["ANTHROPIC_API_URL", "ANTHROPIC_BASE_URL"],1775 api_key_env="ANTHROPIC_API_KEY",1776 default_base_url="https://api.anthropic.com",1777 )1778 return values17791780 def _resolve_model_profile(self) -> ModelProfile | None:1781 profile = _get_default_model_profile(self.model) or None1782 if profile is not None and self.betas and "context-1m-2025-08-07" in self.betas:1783 profile["max_input_tokens"] = 1_000_0001784 return profile17851786 @cached_property1787 def _client_params(self) -> dict[str, Any]:1788 # Merge User-Agent with user-provided headers (user headers take precedence)1789 default_headers = {1790 "User-Agent": _USER_AGENT,1791 "anthropic-version": "2023-06-01",1792 }1793 if self.default_headers:1794 default_headers.update(self.default_headers)1795 default_headers = dict(1796 _with_gateway_headers(1797 default_headers, self._langsmith_gateway_headers or {}1798 )1799 or {}1800 )18011802 client_params: dict[str, Any] = {1803 "api_key": self.anthropic_api_key.get_secret_value(),1804 "base_url": self.anthropic_api_url,1805 "max_retries": self.max_retries,1806 "default_headers": default_headers,1807 }1808 # value <= 0 indicates the param should be ignored. None is a meaningful value1809 # for Anthropic client and treated differently than not specifying the param at1810 # all.1811 if self.default_request_timeout is None or self.default_request_timeout > 0:1812 client_params["timeout"] = self.default_request_timeout18131814 return client_params18151816 @cached_property1817 def _client(self) -> anthropic.Client:1818 client_params = self._client_params1819 http_client_params = {"base_url": client_params["base_url"]}1820 if "timeout" in client_params:1821 http_client_params["timeout"] = client_params["timeout"]1822 if self.anthropic_proxy:1823 http_client_params["anthropic_proxy"] = self.anthropic_proxy1824 http_client = _get_default_httpx_client(**http_client_params)1825 params = {1826 **client_params,1827 "http_client": http_client,1828 }1829 return anthropic.Client(**params)18301831 @cached_property1832 def _async_client(self) -> anthropic.AsyncClient:1833 client_params = self._client_params1834 http_client_params = {"base_url": client_params["base_url"]}1835 if "timeout" in client_params:1836 http_client_params["timeout"] = client_params["timeout"]1837 if self.anthropic_proxy:1838 http_client_params["anthropic_proxy"] = self.anthropic_proxy1839 http_client = _get_default_async_httpx_client(**http_client_params)1840 params = {1841 **client_params,1842 "http_client": http_client,1843 }1844 return anthropic.AsyncClient(**params)18451846 def _assert_valid_model_configuration(self, kwargs: Mapping[str, Any]) -> None:1847 """Validate resolved request configuration against model-specific invariants."""1848 request_config = {**self.model_kwargs, **kwargs}1849 thinking = request_config.get("thinking")1850 if self.thinking is not None:1851 thinking = self.thinking18521853 output_config = dict(self.output_config or {})1854 if self.reasoning_effort:1855 output_config["effort"] = self.reasoning_effort1856 request_output_config = request_config.get("output_config")1857 if isinstance(request_output_config, dict):1858 output_config.update(request_output_config)1859 effort = request_config.get("effort")1860 if effort is None:1861 effort = request_config.get("reasoning_effort")1862 if effort:1863 output_config["effort"] = effort18641865 is_fable_model = self.model.startswith(("claude-fable-5", "claude-mythos-5-2"))1866 is_sonnet_55 = self.model.startswith("claude-sonnet-5-5")1867 if is_fable_model or is_sonnet_55:1868 top_k = request_config.get("top_k", self.top_k)1869 top_p = request_config.get("top_p", self.top_p)1870 temperature = request_config.get("temperature", self.temperature)1871 if top_k is not None:1872 msg = f"`top_k` is not supported for {self.model}."1873 raise ValueError(msg)1874 if top_p is not None and top_p != 1:1875 msg = (1876 f"`top_p` is not supported for {self.model} at non-default values."1877 )1878 raise ValueError(msg)1879 if temperature is not None and temperature != 1:1880 msg = (1881 f"`temperature` is not supported for {self.model} at "1882 "non-default values."1883 )1884 raise ValueError(msg)1885 if isinstance(thinking, Mapping) and thinking.get("type") == "disabled":1886 msg = (1887 '`thinking={"type": "disabled"}` is not supported for '1888 f"{self.model}; omit `thinking` to use adaptive thinking."1889 )1890 raise ValueError(msg)18911892 if (1893 (self.model.startswith("claude-opus-5") or is_fable_model or is_sonnet_55)1894 and isinstance(thinking, Mapping)1895 and thinking.get("type") == "enabled"1896 ):1897 msg = (1898 '`thinking={"type": "enabled", "budget_tokens": ...}` is not '1899 f"supported for {self.model}; use adaptive thinking and "1900 "`output_config.effort` instead."1901 )1902 raise ValueError(msg)19031904 if (1905 self.model.startswith("claude-opus-5")1906 and isinstance(thinking, Mapping)1907 and thinking.get("type") == "disabled"1908 and output_config.get("effort") in {"xhigh", "max"}1909 ):1910 msg = (1911 '`thinking={"type": "disabled"}` is not supported for '1912 f"{self.model} with "1913 f"`output_config.effort={output_config['effort']!r}`; use adaptive "1914 "thinking, omit `thinking`, or set effort to `high` or below."1915 )1916 raise ValueError(msg)19171918 def _get_request_payload(1919 self,1920 input_: LanguageModelInput,1921 *,1922 stop: list[str] | None = None,1923 **kwargs: Any,1924 ) -> dict:1925 """Get the request payload for the Anthropic API."""1926 self._assert_valid_model_configuration(kwargs)1927 messages = self._convert_input(input_).to_messages()19281929 for idx, message in enumerate(messages):1930 # Translate v1 content1931 if (1932 isinstance(message, AIMessage)1933 and message.response_metadata.get("output_version") == "v1"1934 ):1935 tcs: list[types.ToolCall] = [1936 {1937 "type": "tool_call",1938 "name": tool_call["name"],1939 "args": tool_call["args"],1940 "id": tool_call.get("id"),1941 }1942 for tool_call in message.tool_calls1943 ]1944 messages[idx] = message.model_copy(1945 update={1946 "content": _convert_from_v1_to_anthropic(1947 cast(list[types.ContentBlock], message.content),1948 tcs,1949 message.response_metadata.get("model_provider"),1950 )1951 }1952 )19531954 system, formatted_messages = _format_messages(1955 messages,1956 model=self.model,1957 mid_conversation_system_messages=bool(1958 (self.profile or {}).get("mid_conversation_system_messages")1959 ),1960 )1961 if isinstance(system, list) and not system:1962 # Every block was narrowed away (or the message was empty to begin1963 # with). An empty block array carries no instructions, so drop the1964 # field rather than sending it. `_format_messages` has already1965 # claimed the slot, so a second hoisted system message still errors.1966 system = None19671968 # Only the direct Anthropic API accepts top-level `cache_control`.1969 # Subclasses that route through other transports (e.g. Bedrock) expand1970 # `cache_control` kwargs into block-level breakpoints, the only form1971 # those transports accept.1972 if not _is_direct_anthropic_llm_type(getattr(self, "_llm_type", None)):1973 cache_control = kwargs.pop("cache_control", None)1974 # Empty `formatted_messages` has nothing to attach a breakpoint to;1975 # skip silently. The warning below is reserved for the surprising1976 # case where messages exist but every candidate block is ineligible.1977 if cache_control and formatted_messages:1978 code_execution_tool_ids = _collect_code_execution_tool_ids(1979 formatted_messages1980 )1981 applied = _apply_cache_control_to_last_eligible_block(1982 formatted_messages, cache_control, code_execution_tool_ids1983 )1984 if not applied:1985 warnings.warn(1986 "`cache_control` kwarg was dropped: no eligible "1987 "content block found (all candidates are "1988 "`code_execution`-related, which Anthropic forbids "1989 "breakpoints on).",1990 UserWarning,1991 stacklevel=2,1992 )19931994 payload = {1995 "model": self.model,1996 "max_tokens": self.max_tokens,1997 "messages": formatted_messages,1998 "temperature": self.temperature,1999 "top_k": self.top_k,2000 "top_p": self.top_p,
Findings
✓ No findings reported for this file.