fix(vertexai): convert file content blocks to Anthropic documents (#2057)

Anthropic has no `file` content type, so LangChain `file` blocks sent
through `ChatAnthropicVertex` (e.g. a base64 PDF from a user or a tool)
were forwarded as-is and rejected by the API.

This converts `file` and `text-plain` blocks to Anthropic `document`
blocks in user messages and tool results, ported from
`langchain-anthropic`'s `_format_data_content_block` (no dependency on
that package, matching how image blocks are already handled here).

## References

- [Slack
thread](https://langchain.slack.com/archives/C07D416CCTU/p1791902852491299?thread_ts=1791902852.491299&cid=C07D416CCTU)

Made by [Open SWE](https://github.com/langchain-ai/open-swe) · [view
thread](https://openswe.langchain.dev/agents/3932fde8-b58e-574f-9224-29be66a96034)
· openai:gpt-6.1-sol (low)

---------

Co-authored-by: Mason Daugherty <mdrxy@users.noreply.github.com>
Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>

Author: mdrxy

libs/vertexai/langchain_google_vertexai/_anthropic_utils.py

@@ -190,6 +190,16 @@ def _format_message_anthropic(
                     content.append(_format_image_content_block(block, project))
                     continue
 
+                if block["type"] in ("file", "text-plain"):
+                    content.append(_format_document_content_block(block))
+                    continue
+
+                # Tool results may nest LangChain file/image blocks (e.g. a PDF
+                # returned by a tool), which Anthropic rejects unconverted
+                if block["type"] == "tool_result":
+                    content.append(_clean_content_block(block))
+                    continue
+
                 if block["type"] == "text":
                     text: str = block.get("text", "")
                     # Only add non-empty strings for now as empty ones are not
@@ -394,24 +404,139 @@ def _format_image_content_block(block: dict, project: str | None = None) -> dict
     raise ValueError(msg)
 
 
+def _text_document_source(block: dict) -> dict[str, Any]:
+    """Build an Anthropic plain-text document source.
+
+    Raises:
+        ValueError: If the block has no inline `text`, since Anthropic text
+            document sources cannot reference a URL, file ID, or base64 payload.
+    """
+    if "text" not in block:
+        msg = (
+            "Anthropic plain-text document sources require an inline 'text' field; "
+            f"got keys {sorted(block)}."
+        )
+        raise ValueError(msg)
+    return {
+        "type": "text",
+        "media_type": block.get("mime_type") or "text/plain",
+        "data": block["text"],
+    }
+
+
+def _format_document_source(block: dict) -> dict[str, Any]:
+    """Build the Anthropic document source for a LangChain file block.
+
+    Follows `langchain_anthropic`, accepting both standard and legacy
+    (`source_type`) block shapes, but validates sources more strictly: non-PDF
+    base64 or URL files and empty base64 payloads are rejected locally rather
+    than failing at the API.
+
+    `url` and `file_id` sources are still converted for parity, although Claude
+    on Vertex AI does not currently support URL or Files API input sources, so
+    the API is expected to reject them.
+
+    Raises:
+        ValueError: If a `file` block has no supported data field, a base64 or
+            URL `file` block is not a PDF, a base64 payload is empty, or a
+            plain-text block has no inline `text`.
+    """
+    if block["type"] == "text-plain":
+        return _text_document_source(block)
+    if "url" in block:
+        # Anthropic URL document sources only accept PDFs; `mime_type` is
+        # optional on URL blocks, so only reject an explicit mismatch
+        mime_type = block.get("mime_type")
+        if mime_type and mime_type != "application/pdf":
+            msg = (
+                "Anthropic only supports URL file content blocks with mime_type "
+                f"'application/pdf', got {mime_type!r}. Use an 'image' block for "
+                "image URLs."
+            )
+            raise ValueError(msg)
+        return {"type": "url", "url": block["url"]}
+    if "base64" in block or block.get("source_type") == "base64":
+        media_type = block.get("mime_type") or "application/pdf"
+        # Anthropic base64 document sources only accept PDFs
+        if media_type != "application/pdf":
+            msg = (
+                "Anthropic only supports base64 file content blocks with mime_type "
+                f"'application/pdf', got {media_type!r}. Use a 'text-plain' block "
+                "for plain text or an 'image' block for images."
+            )
+            raise ValueError(msg)
+        data = block["base64"] if "base64" in block else block.get("data")
+        if not data:
+            msg = "Base64 file content block is missing its 'base64' or 'data' payload."
+            raise ValueError(msg)
+        return {"type": "base64", "media_type": media_type, "data": data}
+    if block.get("source_type") == "text":
+        return _text_document_source(block)
+    if "file_id" in block:
+        return {"type": "file", "file_id": block["file_id"]}
+    if block.get("source_type") == "id" and "id" in block:
+        return {"type": "file", "file_id": block["id"]}
+    msg = (
+        "Anthropic file content blocks require a 'url', 'base64', or 'file_id' "
+        "key (or legacy source_type 'base64', 'text', or 'id'). Use a "
+        "'text-plain' block for plain text."
+    )
+    raise ValueError(msg)
+
+
+def _format_document_content_block(block: dict) -> dict:
+    """Convert LangChain `file` and `text-plain` blocks to Anthropic documents.
+
+    Anthropic has no `file` content type, so these blocks must be converted
+    before reaching the API.
+
+    Raises:
+        ValueError: If the block cannot be converted to an Anthropic document
+            source.
+    """
+    formatted_block: dict[str, Any] = {
+        "type": "document",
+        "source": _format_document_source(block),
+    }
+    for key in ("cache_control", "citations", "title", "context"):
+        if key in block:
+            formatted_block[key] = block[key]
+        elif key in (block.get("extras") or {}):
+            formatted_block[key] = block["extras"][key]
+        elif key in (block.get("metadata") or {}):
+            formatted_block[key] = block["metadata"][key]
+    return formatted_block
+
+
 def _clean_content_block(block: Any) -> Any:
-    """Remove streaming metadata fields from content blocks.
+    """Prepare a content block to be sent back to the Anthropic API.
 
     Anthropic's streaming API adds `index` and `partial_json` fields to content blocks
     during streaming. These fields must be removed before sending back to the API.
+    LangChain `image`, `file`, and `text-plain` blocks are also converted to Anthropic
+    wire format, including when nested inside `tool_result` content.
 
     Args:
         block: Content block (`dict`, `str`, or other type)
 
     Returns:
         Cleaned content block with streaming metadata removed
+
+    Raises:
+        ValueError: If a LangChain `image`, `file`, or `text-plain` block cannot be
+            converted to Anthropic wire format.
     """
     if not isinstance(block, dict):
         return block
 
-    # Convert LangChain image blocks to Anthropic wire format
+    # Convert LangChain image, file, and text-plain blocks to Anthropic wire format
     if block.get("type") == "image":
         return _format_image_content_block(block)
+    if block.get("type") in ("file", "text-plain"):
+        return _format_document_content_block(block)
+    # Tool results may nest LangChain blocks that also need converting
+    if block.get("type") == "tool_result" and "content" in block:
+        block = {**block, "content": _clean_content(block["content"])}
 
     # Remove known streaming metadata fields
     # 'index' - added during streaming to track block position

libs/vertexai/tests/unit_tests/test_anthropic_utils.py

@@ -1,6 +1,7 @@
 """Unit tests for _anthropic_utils.py."""
 
 import base64
+from typing import Any
 from unittest.mock import patch
 
 import pytest
@@ -1582,6 +1583,168 @@ def test_format_image(image_url: str, expected_media_type: str) -> None:
         mock_loader_instance.load_bytes.assert_called_once_with(image_url)
 
 
+@pytest.mark.parametrize("message_kind", ["user", "tool", "nested_tool", "nested_user"])
+def test_format_messages_base64_pdf_file(message_kind: str) -> None:
+    pdf_block = {
+        "type": "file",
+        "base64": "cGRm",
+        "mime_type": "application/pdf",
+        "id": "lc-file-id",
+        "title": "Report",
+        "extras": {"citations": {"enabled": True}, "context": "Quarterly report"},
+    }
+    native_document = {
+        "type": "document",
+        "source": {
+            "type": "base64",
+            "media_type": "application/pdf",
+            "data": "bmF0aXZl",
+        },
+        "title": "Native report",
+        "citations": {"enabled": True},
+    }
+    content: list[str | dict[str, Any]] = [
+        {"type": "text", "text": "Report attached"},
+        pdf_block,
+        native_document,
+    ]
+    tool_result = {
+        "type": "tool_result",
+        "tool_use_id": "call_1",
+        "content": content,
+        "is_error": True,
+        "cache_control": {"type": "ephemeral"},
+    }
+    message: HumanMessage | ToolMessage
+    if message_kind == "user":
+        message = HumanMessage(content=content)
+    elif message_kind == "nested_user":
+        message = HumanMessage(content=[tool_result])
+    else:
+        message = ToolMessage(
+            content=[tool_result] if message_kind == "nested_tool" else content,
+            tool_call_id="call_1",
+            status="error",
+            additional_kwargs={"cache_control": {"type": "ephemeral"}},
+        )
+    original = message.model_copy(deep=True)
+
+    _, formatted = _format_messages_anthropic([message], project="test-project")
+
+    expected_content = [
+        content[0],
+        {
+            "type": "document",
+            "source": {
+                "type": "base64",
+                "media_type": "application/pdf",
+                "data": "cGRm",
+            },
+            "title": "Report",
+            "citations": {"enabled": True},
+            "context": "Quarterly report",
+        },
+        native_document,
+    ]
+    if message_kind == "user":
+        assert formatted == [{"role": "user", "content": expected_content}]
+    else:
+        assert formatted == [
+            {"role": "user", "content": [{**tool_result, "content": expected_content}]}
+        ]
+    assert message == original
+
+
+def test_format_messages_pdf_file_defaults() -> None:
+    message = HumanMessage(content=[{"type": "file", "base64": "cGRm"}])
+
+    _, formatted = _format_messages_anthropic([message], project="test-project")
+
+    assert formatted[0]["content"] == [
+        {
+            "type": "document",
+            "source": {
+                "type": "base64",
+                "media_type": "application/pdf",
+                "data": "cGRm",
+            },
+        }
+    ]
+
+
+def test_format_messages_file_legacy_metadata() -> None:
+    message = HumanMessage(
+        content=[
+            {
+                "type": "file",
+                "source_type": "base64",
+                "data": "cGRm",
+                "metadata": {"title": "Report"},
+                "cache_control": {"type": "ephemeral"},
+            }
+        ]
+    )
+
+    _, formatted = _format_messages_anthropic([message], project="test-project")
+
+    assert formatted[0]["content"] == [
+        {
+            "type": "document",
+            "source": {
+                "type": "base64",
+                "media_type": "application/pdf",
+                "data": "cGRm",
+            },
+            "title": "Report",
+            "cache_control": {"type": "ephemeral"},
+        }
+    ]
+
+
+@pytest.mark.parametrize(
+    ("block", "expected_source"),
+    [
+        (
+            {"type": "file", "url": "https://example.com/report.pdf"},
+            {"type": "url", "url": "https://example.com/report.pdf"},
+        ),
+        (
+            {"type": "file", "file_id": "file_123"},
+            {"type": "file", "file_id": "file_123"},
+        ),
+        (
+            {"type": "file", "source_type": "id", "id": "file_123"},
+            {"type": "file", "file_id": "file_123"},
+        ),
+        (
+            {"type": "file", "source_type": "text", "text": "notes"},
+            {"type": "text", "media_type": "text/plain", "data": "notes"},
+        ),
+        (
+            {"type": "text-plain", "text": "notes", "mime_type": "text/markdown"},
+            {"type": "text", "media_type": "text/markdown", "data": "notes"},
+        ),
+    ],
+)
+def test_format_messages_document_sources(
+    block: dict[str, Any], expected_source: dict[str, Any]
+) -> None:
+    message = HumanMessage(content=[block])
+
+    _, formatted = _format_messages_anthropic([message], project="test-project")
+
+    assert formatted[0]["content"] == [{"type": "document", "source": expected_source}]
+
+
+def test_format_messages_file_without_data_raises() -> None:
+    message = HumanMessage(
+        content=[{"type": "file", "id": "lc-file-id", "mime_type": "application/pdf"}]
+    )
+
+    with pytest.raises(ValueError, match="file content blocks"):
+        _format_messages_anthropic([message], project="test-project")
+
+
 def test_format_messages_anthropic_system_not_first() -> None:
     """Test that system messages are accepted when not at position 0.