haystack-ai 3.2.0.dev20260902000321__tar.gz → 3.2.0.dev20260903000331__tar.gz

{haystack_ai-3.2.0.dev20260902000321 → haystack_ai-3.2.0.dev20260903000331}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: haystack-ai
-Version: 3.2.0.dev20260902000321
+Version: 3.2.0.dev20260903000331
 Summary: LLM framework to build customizable, production-ready LLM applications. Connect components (models, vector DBs, file converters) to pipelines or agents that can interact with your data.
 Project-URL: CI: GitHub, https://github.com/deepset-ai/haystack/actions
 Project-URL: Docs: RTD, https://haystack.deepset.ai/overview/intro

haystack_ai-3.2.0.dev20260903000331/VERSION.txt

@@ -0,0 +1 @@
+3.2.0.dev20260903000331

{haystack_ai-3.2.0.dev20260902000321 → haystack_ai-3.2.0.dev20260903000331}/haystack/components/converters/output_adapter.py

@@ -136,8 +136,12 @@ class OutputAdapter:
             # we try to evaluate it and would fail.
             # This must be done cause the output could be different literal structures.
             # This doesn't support any user types.
+            # When the declared output_type is str we skip literal evaluation so that a
+            # rendered string that happens to be a valid Python literal (e.g. "1,000" -> (1, 0),
+            # "42" -> 42, "None" -> None) is returned unchanged instead of being coerced to
+            # another type, which would violate the declared output_type.
             with contextlib.suppress(Exception):
-                if not self._unsafe:
+                if not self._unsafe and self.output_type is not str:
                     output_result = ast.literal_eval(output_result)
 
             adapted_outputs["output"] = output_result

{haystack_ai-3.2.0.dev20260902000321 → haystack_ai-3.2.0.dev20260903000331}/haystack/components/generators/chat/openai_responses.py

@@ -16,6 +16,7 @@ from haystack import component, default_from_dict, default_to_dict, logging
 from haystack.components.generators.utils import _normalize_messages, _serialize_object
 from haystack.dataclasses import (
     ChatMessage,
+    ChatRole,
     ComponentInfo,
     FileContent,
     ImageContent,
@@ -992,10 +993,13 @@ def _convert_chat_message_to_responses_api_format(message: ChatMessage) -> list[
     reasonings = message.reasonings
     files = message.files
 
-    if not any([text_contents, tool_calls, tool_call_results, images, reasonings, files]):
+    has_content = any([text_contents, tool_calls, tool_call_results, images, reasonings, files])
+    # We convert an assistant message with no content part into a message with empty content, which the API accepts
+    if not has_content and not message.is_from(ChatRole.ASSISTANT):
         raise ValueError(
-            """A `ChatMessage` must contain at least one `TextContent`, `ToolCall`, `ToolCallResult`,
-              `ImageContent`, `FileContent`, or `ReasoningContent`."""
+            f"A `ChatMessage` from `{message._role.value}` must contain at least one `TextContent`, `ToolCall`, "
+            "`ToolCallResult`, `ImageContent`, `FileContent`, or `ReasoningContent`. Only assistant messages can "
+            "be empty."
         )
     if len(tool_call_results) > 0 and len(message._content) > 1:
         raise ValueError(
@@ -1068,7 +1072,7 @@ def _convert_chat_message_to_responses_api_format(message: ChatMessage) -> list[
         formatted_messages.extend(formatted_tool_calls)
 
     # system and assistant messages
-    if text_contents:
+    if text_contents or not formatted_messages:
         openai_msg["content"] = " ".join(text_contents)
         formatted_messages.append(openai_msg)
 

{haystack_ai-3.2.0.dev20260902000321 → haystack_ai-3.2.0.dev20260903000331}/haystack/components/preprocessors/recursive_splitter.py

@@ -350,17 +350,11 @@ class RecursiveDocumentSplitter:
             if current_chunk:
                 chunks.append("".join(current_chunk))
 
-            if self.split_overlap > 0:
-                chunks = self._apply_overlap(chunks)
-
             if chunks:
                 return chunks
 
         # if no separator worked, fall back to word- or character-level chunking
-        chunks = self._fall_back_to_fixed_chunking(text, self.split_units)
-        if self.split_overlap > 0:
-            chunks = self._apply_overlap(chunks)
-        return chunks
+        return self._fall_back_to_fixed_chunking(text, self.split_units)
 
     def _fall_back_to_fixed_chunking(self, text: str, split_units: Literal["word", "char", "token"]) -> list[str]:
         """
@@ -429,6 +423,12 @@ class RecursiveDocumentSplitter:
     def _run_one(self, doc: Document) -> list[Document]:
         chunks = self._chunk_text(doc.content)  # type: ignore # the caller already check for a non-empty doc.content
         chunks = chunks[:-1] if len(chunks[-1]) == 0 else chunks  # remove last empty chunk if it exists
+
+        # apply the overlap once, on the fully chunked list, so that chunks produced
+        # at inner recursion levels don't get the overlap applied a second time
+        if self.split_overlap > 0:
+            chunks = self._apply_overlap(chunks)
+
         current_position = 0
         current_page = 1
 

{haystack_ai-3.2.0.dev20260902000321 → haystack_ai-3.2.0.dev20260903000331}/haystack/components/routers/conditional_router.py

@@ -458,8 +458,12 @@ class ConditionalRouter:
                         # we try to evaluate it and would fail.
                         # This must be done cause the output could be different literal structures.
                         # This doesn't support any user types.
+                        # When the declared output_type is str we skip literal evaluation so that a
+                        # rendered string that happens to be a valid Python literal (e.g. "1,000" -> (1, 0),
+                        # "42" -> 42, "None" -> None) is returned unchanged instead of being coerced to
+                        # another type, which would violate the declared output_type.
                         with contextlib.suppress(Exception):
-                            if not self._unsafe:
+                            if not self._unsafe and output_type is not str:
                                 output_value = ast.literal_eval(output_value)
 
                     # Validate output type if needed

{haystack_ai-3.2.0.dev20260902000321 → haystack_ai-3.2.0.dev20260903000331}/haystack/dataclasses/chat_message.py

@@ -646,10 +646,12 @@ class ChatMessage:
             If the message format is invalid, or if `require_tool_call_ids` is True and any Tool Call is missing an
             `id` attribute.
         """
-        if not self.texts and not self.tool_calls and not self.tool_call_results and not self.images and not self.files:
+        has_content = bool(self.texts or self.tool_calls or self.tool_call_results or self.images or self.files)
+        # We convert an assistant message with no content part into a message with empty content, which the API accepts
+        if not has_content and not self.is_from(ChatRole.ASSISTANT):
             raise ValueError(
-                "A `ChatMessage` must contain at least one `TextContent`, `ToolCall`, "
-                "`ToolCallResult`, `ImageContent`, or `FileContent`."
+                f"A `ChatMessage` from `{self._role.value}` must contain at least one `TextContent`, `ToolCall`, "
+                "`ToolCallResult`, `ImageContent`, or `FileContent`. Only assistant messages can be empty."
             )
         if len(self.tool_call_results) > 0 and len(self._content) > 1:
             raise ValueError(
@@ -745,6 +747,9 @@ class ChatMessage:
                     raise ValueError("`ToolCall` must have a non-null `id` attribute to be used with OpenAI.")
                 openai_tool_calls.append(openai_tool_call)
             openai_msg["tool_calls"] = openai_tool_calls
+        # The API rejects a message carrying neither content nor tool calls, so send empty content for it.
+        if "content" not in openai_msg and "tool_calls" not in openai_msg:
+            openai_msg["content"] = ""
         return openai_msg
 
     @staticmethod
@@ -766,7 +771,9 @@ class ChatMessage:
             raise ValueError(f"Unsupported role: {role}")
 
         if role == "assistant":
-            if not content and not tool_calls:
+            # An empty string is valid content for an assistant message: that is how a reply with nothing to send
+            # is serialized. Other falsy content requires tool calls.
+            if not content and content != "" and not tool_calls:
                 raise ValueError("For assistant messages, either `content` or `tool_calls` must be present.")
             if tool_calls:
                 for tc in tool_calls:

{haystack_ai-3.2.0.dev20260902000321 → haystack_ai-3.2.0.dev20260903000331}/haystack/hooks/tool_result_offloading/hooks.py

@@ -2,23 +2,28 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+import base64
 import json
+import mimetypes
+from pathlib import Path
 from typing import Any
 
 from haystack import logging
 from haystack.components.agents.state.state import State
 from haystack.components.agents.state.state_utils import replace_values
 from haystack.core.serialization import default_from_dict, default_to_dict
-from haystack.dataclasses import ChatMessage, TextContent
-from haystack.dataclasses.chat_message import ToolCallResultContentT
+from haystack.dataclasses import ChatMessage, FileContent, ImageContent, TextContent
 from haystack.hooks.tool_result_offloading.types import OffloadPolicy, ToolResultStore
 from haystack.utils.deserialization import deserialize_component_inplace
 
+# Extension used for a binary block whose MIME type is unknown or maps to no known extension.
+_FALLBACK_EXTENSION = ".bin"
+
 logger = logging.getLogger(__name__)
 
-# Meta key marking an already-offloaded tool-result message (its value is the store reference). The offloaded pointer
-# is itself a tool result in the trailing block the hook scans, so this marker stops a second offload hook registered
-# under `after_tool` from offloading the pointer text again and writing a junk file.
+# Meta key marking an already-offloaded tool-result message; its value is the list of store references written.
+# Stops a second `after_tool` offload hook from offloading the pointer text again, since the pointer is itself a
+# tool result.
 _OFFLOADED_META_KEY = "tool_result_offloaded"
 
 # Key under which a per-run store override may be supplied via the Agent's `hook_context` (e.g. a request-scoped
@@ -26,24 +31,6 @@ _OFFLOADED_META_KEY = "tool_result_offloaded"
 RESULT_STORE_CONTEXT_KEY = "tool_result_store"
 
 
-def _result_store_key(tool_name: str, tool_call_id: str | None, step: int, index: int) -> str:
-    """
-    Build a per-result store key that is stable and unique within a run.
-
-    Combining the step, tool name, and tool call id keeps results from different tools and different steps from
-    colliding. When the tool call carries no id (it is optional and not every generator sets it), the result's
-    position in the step's batch is used instead, so two id-less calls to the same tool in the same step do not
-    collide.
-
-    :param tool_name: The name of the tool that produced the result.
-    :param tool_call_id: The id of the originating tool call, or None when the call carried no id.
-    :param step: The Agent's current step count.
-    :param index: The result's position within this step's batch of tool results, used when `tool_call_id` is None.
-    :returns: A file-name-like key for the store, e.g. `2_web_search_call-123.txt`.
-    """
-    return f"{step}_{tool_name}_{tool_call_id or f'call{index}'}.txt"
-
-
 def _fresh_tool_results_start(messages: list[ChatMessage]) -> int:
     """
     Return the index at which the trailing run of tool-result messages begins.
@@ -62,23 +49,18 @@ def _fresh_tool_results_start(messages: list[ChatMessage]) -> int:
     return index
 
 
-def _offloadable_text(content: ToolCallResultContentT) -> str | None:
+def _content_block_payload(content_block: TextContent | ImageContent | FileContent) -> str:
     """
-    Return the text of a tool result if it can be offloaded as text, otherwise None.
+    Return the string a content block contributes to the conversation.
 
-    A plain string is returned as-is; a non-empty sequence made up entirely of `TextContent` blocks is concatenated
-    into a single string. Anything else (e.g. a result containing image or file content) returns None and is left in
-    context.
+    For an image or a file this is the base64 payload, which is what actually occupies the context window.
 
-    :param content: The tool result content to inspect.
-    :returns: The offloadable text, or None when the content is not purely text.
+    :param content_block: The content block to inspect.
+    :returns: The content block's text or base64 payload.
     """
-    if isinstance(content, str):
-        return content
-    texts = [block.text for block in content if isinstance(block, TextContent)]
-    if texts and len(texts) == len(content):
-        return "".join(texts)
-    return None
+    if isinstance(content_block, TextContent):
+        return content_block.text
+    return content_block.base64_image if isinstance(content_block, ImageContent) else content_block.base64_data
 
 
 def _serialize_offload_strategies(strategies: dict[str | tuple[str, ...], OffloadPolicy]) -> dict[str, Any]:
@@ -158,10 +140,10 @@ class ToolResultOffloadHook:
     any tool without a more specific entry. More specific keys win. A tool with no matching key (and no `"*"`) is not
     offloaded.
 
-    Only successful, text tool output is offloaded. Error results (including `before_tool` human-in-the-loop
-    rejections) are always left in context. Non-text results (image or file content) are also left in context, and a
-    warning is logged when such a result has a matching offload policy; supporting only text is a deliberate choice
-    for now. Each result is offloaded at most once, even though the hook runs on every tool step.
+    Only successful tool output is offloaded; error results are always left in context. Each part of a result is
+    written to its own store entry and the pointer says where each one went. Image and file content is only offloaded
+    to a store that sets `supports_binary_content`; with a text-only store the result stays in context and a warning
+    is logged. Each result is offloaded at most once, even though the hook runs on every tool step.
 
     The hook keeps no mutable state, so a single instance can be shared across concurrent runs. The constructor
     `store`, however, is shared by every run that does not override it — fine for single-user or local use, but in a
@@ -187,8 +169,9 @@ class ToolResultOffloadHook:
         :param store: Where offloaded results are written. Can be overridden per run via `hook_context`.
         :param offload_strategies: Mapping of tool name (or a tuple of tool names, or the wildcard `"*"`) to the
             `OffloadPolicy` that decides whether that tool's results are offloaded.
-        :param preview_chars: Number of leading characters of the original result to include in the pointer left in
-            the conversation, so the model knows roughly what was offloaded.
+        :param preview_chars: Number of leading characters of each offloaded text to include in the pointer left in
+            the conversation, so the model knows roughly what was offloaded. Image and file blocks are described by
+            their MIME type and size instead.
         """
         self.store = store
         self.offload_strategies = offload_strategies
@@ -217,29 +200,25 @@ class ToolResultOffloadHook:
         :returns: None. The hook mutates `state` in place.
         """
         messages = state.data.get("messages") or []
-        start = _fresh_tool_results_start(messages)
+        start = _fresh_tool_results_start(messages=messages)
         if start == len(messages):
             return
-        store = self._resolve_store(state)
+
+        # The hook instance is shared across concurrent runs, so a run isolates itself by carrying its own store in
+        # `hook_context`.
+        hook_context = state.data.get("hook_context") or {}
+        store = hook_context.get(RESULT_STORE_CONTEXT_KEY, self.store)
+
         rewritten: list[ChatMessage] = list(messages[:start])
         changed = False
         for index, message in enumerate(messages[start:]):
-            new_message = self._maybe_offload(message, store, state, index)
+            new_message = self._maybe_offload(message=message, store=store, state=state, index=index)
             rewritten.append(new_message)
             changed = changed or new_message is not message
-        if changed:
-            state.set("messages", rewritten, handler_override=replace_values)
-
-    def _resolve_store(self, state: State) -> ToolResultStore:
-        """
-        Return the store to write to for this run.
 
-        :param state: The Agent's live `State`, whose `hook_context` may carry a per-run store override under
-            `RESULT_STORE_CONTEXT_KEY`.
-        :returns: The per-run store from `hook_context` if provided, otherwise the store the hook was built with.
-        """
-        context = state.data.get("hook_context") or {}
-        return context.get(RESULT_STORE_CONTEXT_KEY, self.store)
+        # Only write back to state when at least one message changed
+        if changed:
+            state.set(key="messages", value=rewritten, handler_override=replace_values)
 
     def _policy_for(self, tool_name: str) -> OffloadPolicy | None:
         """
@@ -264,11 +243,12 @@ class ToolResultOffloadHook:
 
         A message is left as-is when it is not a tool result, when the result is an error (including `before_tool`
         human-in-the-loop rejections), when it was already offloaded (e.g. another offload hook under `after_tool`
-        handled it), when no policy applies, when the result is non-text (contains image or file content), or when the
-        policy declines to offload.
+        handled it), when no policy applies, when the result is empty, when the result carries image or file content
+        that `store` cannot store, or when the policy declines to offload.
 
-        Otherwise the result text is written to `store` and the message is rebuilt with a pointer in place of the full
-        result, preserving its origin and error flag and marking it offloaded.
+        Otherwise the result is written to `store` and the message is rebuilt with a pointer in place of the full
+        result, preserving its origin and error flag and marking it offloaded. Each part of the result goes to its own
+        store entry.
 
         :param message: The message to consider offloading.
         :param store: The store to write the result to.
@@ -283,48 +263,115 @@ class ToolResultOffloadHook:
             return message
 
         tool_name = result.origin.tool_name
-        policy = self._policy_for(tool_name)
+        policy = self._policy_for(tool_name=tool_name)
 
         # If no policy applies, leave the result in context
         if policy is None:
             return message
 
-        # A policy matched, so an offload was wanted. Offloading only supports text results (a string or a sequence
-        # of TextContent) for now, by design; leave image/file content in context and warn since the intent was to
-        # offload it.
-        text = _offloadable_text(result.result)
-        if text is None:
+        # A plain string result is handled as a single text block, so everything below has one shape to work with.
+        content_blocks: list[TextContent | ImageContent | FileContent] = (
+            [TextContent(text=result.result)] if isinstance(result.result, str) else list(result.result)
+        )
+        if not content_blocks:
+            return message
+
+        # Check whether the store can store binary content before offloading an image or file result. A text-only store
+        # leaves the result in context and logs a warning.
+        if not getattr(store, "supports_binary_content", False) and not all(
+            isinstance(content_block, TextContent) for content_block in content_blocks
+        ):
             logger.warning(
-                "Tool '{tool}' produced a non-text result; leaving it in context. Result offloading currently "
-                "supports text results only.",
+                "Tool '{tool}' produced a result with image or file content, but {store} does not support binary "
+                "content; leaving the result in context.",
                 tool=tool_name,
+                store=type(store).__name__,
             )
             return message
 
-        # If the policy declines to offload, leave the result in context
-        if not policy.should_offload(tool_name, text, state):
+        # The policy sizes up the result by the string it occupies in the conversation, which for an image or a file
+        # block is its base64 payload.
+        payload = "".join(_content_block_payload(content_block=content_block) for content_block in content_blocks)
+        if not policy.should_offload(tool_name=tool_name, result=payload, state=state):
             return message
 
-        key = _result_store_key(tool_name, result.origin.id, state.data.get("step_count", 0), index)
-        reference = store.write(key=key, content=text)
+        # Step, tool name, and call id keep results from different tools and steps from colliding. A tool call id is
+        # optional, so an id-less call falls back to its position in this step's batch.
+        step = state.data.get("step_count", 0)
+        prefix = f"{step}_{tool_name}_{result.origin.id or f'call{index}'}"
+        references, pointer = self._offload_content_blocks(content_blocks=content_blocks, store=store, prefix=prefix)
+
         return ChatMessage.from_tool(
-            tool_result=self._pointer(reference, text),
+            tool_result=pointer,
             origin=result.origin,
             error=result.error,
-            meta={**message.meta, _OFFLOADED_META_KEY: reference},
+            meta={**message.meta, _OFFLOADED_META_KEY: references},
         )
 
-    def _pointer(self, reference: str, result: str) -> str:
+    def _offload_content_blocks(
+        self, content_blocks: list[TextContent | ImageContent | FileContent], store: ToolResultStore, prefix: str
+    ) -> tuple[list[str], str]:
+        """
+        Write a result's content blocks to the store and build the pointer that replaces them in the conversation.
+
+        Every content block goes to its own store entry. A single block keeps `prefix` as its key and gets a one-line
+        pointer; several blocks get position-suffixed keys and one numbered pointer line each.
+
+        :param content_blocks: The result's content blocks, in order.
+        :param store: The store to write to.
+        :param prefix: The result's store key prefix, as described above.
+        :returns: The store references written, and the pointer text for the conversation.
+        """
+        references: list[str] = []
+        descriptions: list[str] = []
+        single = len(content_blocks) == 1
+        for position, content_block in enumerate(content_blocks):
+            reference, description = self._offload_content_block(
+                content_block=content_block, store=store, key_prefix=prefix if single else f"{prefix}_{position}"
+            )
+            references.append(reference)
+            descriptions.append(description)
+
+        if len(descriptions) == 1:
+            return references, f"Tool result offloaded to {descriptions[0]}"
+
+        numbered = [f"{position}. {description}" for position, description in enumerate(descriptions, start=1)]
+        return references, "\n".join([f"Tool result offloaded to {len(descriptions)} files:", *numbered])
+
+    def _offload_content_block(
+        self, content_block: TextContent | ImageContent | FileContent, store: ToolResultStore, key_prefix: str
+    ) -> tuple[str, str]:
         """
-        Build the compact pointer that replaces a full result in the conversation.
+        Write a single content block to the store and describe where it went.
 
-        :param reference: The store reference the result was written to.
-        :param result: The original result string, used for its length and a leading preview.
-        :returns: A one-line pointer carrying the reference, the result length, and a `preview_chars`-long preview.
+        :param content_block: The content block to offload.
+        :param store: The store to write to.
+        :param key_prefix: The content block's store key without its extension.
+        :returns: The store reference the content block was written to, and a one-line description for the pointer.
         """
-        ellip = "..." if len(result) > self.preview_chars else ""
-        preview = result[: self.preview_chars]
-        return f"Tool result offloaded to '{reference}' ({len(result)} characters). Preview: {preview}{ellip}"
+        if isinstance(content_block, TextContent):
+            text = content_block.text
+            reference = store.write(key=f"{key_prefix}.txt", content=text)
+            # An ellipsis marks a preview that was cut short, so the model can tell it is not the whole text.
+            preview = f"{text[: self.preview_chars]}{'...' if len(text) > self.preview_chars else ''}"
+            return reference, f"text ({len(text)} characters) at '{reference}'. Preview: {preview}"
+
+        if isinstance(content_block, ImageContent):
+            data = base64.b64decode(content_block.base64_image)
+            label = content_block.mime_type or "image"
+            filename = None
+        else:
+            data = base64.b64decode(content_block.base64_data)
+            label = content_block.mime_type or "file"
+            filename = content_block.filename
+
+        # What the tool called the file wins over its MIME type. Only the suffix is taken.
+        mime_extension = mimetypes.guess_extension(content_block.mime_type) if content_block.mime_type else None
+        extension = (Path(filename).suffix if filename else "") or mime_extension or _FALLBACK_EXTENSION
+        reference = store.write(key=f"{key_prefix}{extension}", content=data)
+
+        named = f" named '{filename}'" if filename else ""
+        return reference, f"{label}{named} ({len(data)} bytes) at '{reference}'"
 
     def to_dict(self) -> dict[str, Any]:
         """
@@ -335,7 +382,7 @@ class ToolResultOffloadHook:
         return default_to_dict(
             self,
             store=self.store.to_dict(),
-            offload_strategies=_serialize_offload_strategies(self.offload_strategies),
+            offload_strategies=_serialize_offload_strategies(strategies=self.offload_strategies),
             preview_chars=self.preview_chars,
         )
 
@@ -351,5 +398,5 @@ class ToolResultOffloadHook:
         if init_params.get("store") is not None:
             deserialize_component_inplace(init_params, key="store")
         if init_params.get("offload_strategies") is not None:
-            init_params["offload_strategies"] = _deserialize_offload_strategies(init_params["offload_strategies"])
+            init_params["offload_strategies"] = _deserialize_offload_strategies(data=init_params["offload_strategies"])
         return default_from_dict(cls, data)

{haystack_ai-3.2.0.dev20260902000321 → haystack_ai-3.2.0.dev20260903000331}/haystack/hooks/tool_result_offloading/stores.py

@@ -20,8 +20,13 @@ class FileSystemToolResultStore(ToolResultStore):
     reference = store.write(key="search_1.txt", content="...")
     store.read(reference)
     ```
+
+    Binary content is supported too: `write` takes bytes (an offloaded image or file) and `read` returns them
+    unchanged.
     """
 
+    supports_binary_content = True
+
     def __init__(self, root: str | Path) -> None:
         """
         Initialize the store with the root directory results are written under.
@@ -49,35 +54,47 @@ class FileSystemToolResultStore(ToolResultStore):
             raise ValueError(f"{subject} '{path_like}' resolves outside the store root '{root}'.")
         return resolved
 
-    def write(self, *, key: str, content: str) -> str:
+    def write(self, *, key: str, content: str | bytes) -> str:
         """
         Write `content` to `<root>/<key>`, creating parent directories, and return the file path.
 
+        Text is written UTF-8 encoded; bytes (an offloaded image or file) are written verbatim.
+
         The resolved target must stay within the root directory: a `key` that escapes it (e.g. containing `../` or an
         absolute path) is rejected, so a tool-provided key cannot write outside the store.
 
         :param key: Relative file name for the result within the store root.
-        :param content: The tool result to persist.
+        :param content: The tool result to persist, as text or as raw bytes.
         :returns: The absolute path the content was written to, as a string, for use with `read`.
         :raises ValueError: If `key` resolves to a location outside the store root.
         """
         path = self._resolve_in_root(key, subject="Result key")
         path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_text(content, encoding="utf-8")
+        if isinstance(content, bytes):
+            path.write_bytes(content)
+        else:
+            path.write_text(content, encoding="utf-8")
         return str(path)
 
-    def read(self, reference: str) -> str:
+    def read(self, reference: str) -> str | bytes:
         """
         Read back the content previously written to `reference`.
 
-        The resolved reference must stay within the store root: callers must treat it as an opaque
-        store-scoped reference, not as an arbitrary filesystem path.
+        A file whose bytes are valid UTF-8 is returned as a string, so text results round trip unchanged; anything
+        else (an offloaded image or file) is returned as raw bytes.
+
+        The resolved reference must stay within the store root: it is a store-scoped reference returned by `write`,
+        to be passed back unchanged, not an arbitrary filesystem path callers can build themselves.
 
         :param reference: A store reference returned by `write`.
-        :returns: The stored content.
+        :returns: The stored content, as text when it decodes as UTF-8 and as bytes otherwise.
         :raises ValueError: If `reference` resolves to a location outside the store root.
         """
-        return self._resolve_in_root(reference, subject="Result reference").read_text(encoding="utf-8")
+        data = self._resolve_in_root(reference, subject="Result reference").read_bytes()
+        try:
+            return data.decode("utf-8")
+        except UnicodeDecodeError:
+            return data
 
     def to_dict(self) -> dict[str, Any]:
         """

{haystack_ai-3.2.0.dev20260902000321 → haystack_ai-3.2.0.dev20260903000331}/haystack/hooks/tool_result_offloading/types/protocol.py

@@ -13,25 +13,42 @@ class ToolResultStore(Protocol):
     A place a `ToolResultOffloadHook` writes offloaded tool results to, and reads them back from.
 
     Implementations decide where and how the content lives (local disk, an isolated sandbox filesystem, object
-    storage, ...). `write` returns an opaque reference string that the Agent puts in the conversation in place of the
-    full result; `read` resolves that reference back to the original content.
+    storage, ...). `write` returns a reference string that the Agent puts in the conversation in place of the full
+    result; `read` resolves that reference back to the original content. Only the store interprets a reference -
+    callers pass it back to `read` unchanged.
+
+    A store that sets `supports_binary_content` takes bytes in `write` and gives them back from `read`. One that
+    leaves it False is only ever given text, and image and file results stay in the conversation instead.
 
     Implement both `to_dict` and `from_dict` to make a custom store serializable; the default implementations below
     cover stores whose constructor takes no arguments.
     """
 
-    def write(self, *, key: str, content: str) -> str:
+    # Whether the store handles binary content: `write` accepting bytes and `read` returning them. When False, the
+    # store is only ever given text, and the image and file content of a tool result stays in the conversation.
+    supports_binary_content: bool = False
+
+    def write(self, *, key: str, content: str | bytes) -> str:
         """
-        Persist `content` under `key` and return an opaque reference to it.
+        Persist `content` under `key` and return a reference to it.
 
-        :param key: A stable, per-result identifier the hook derives from the tool call (e.g. a file name).
-        :param content: The tool result to persist.
+        :param key: A stable, per-result identifier the hook derives from the tool call (e.g. a file name). It carries
+            an extension matching the content, so a store that maps keys to files can use it as-is.
+        :param content: The tool result to persist. Text arrives as a string. Image and file content arrives as the
+            decoded bytes of its base64 payload, and only when the store sets `supports_binary_content` to True - a
+            text-only store may narrow this parameter to `str`.
         :returns: A reference string (e.g. a path or URI) that `read` can later resolve.
         """
         ...
 
-    def read(self, reference: str) -> str:
-        """Return the content previously stored under `reference`."""
+    def read(self, reference: str) -> str | bytes:
+        """
+        Return the content previously stored under `reference`.
+
+        :param reference: A reference string returned by `write`.
+        :returns: The stored content: a string for content written as text, bytes for binary content such as an
+            offloaded image or file. A store that does not support binary content only ever returns a string.
+        """
         ...
 
     def to_dict(self) -> dict[str, Any]:
@@ -60,7 +77,9 @@ class OffloadPolicy(Protocol):
         Return whether the given tool result should be offloaded.
 
         :param tool_name: The name of the tool that produced the result.
-        :param result: The tool result as a string (the content that would otherwise stay in the conversation).
+        :param result: The tool result as a string (the content that would otherwise stay in the conversation). For a
+            result carrying image or file blocks, this is the text and base64 payloads of all its blocks joined
+            together, so its length reflects the context the result actually occupies.
         :param state: The Agent's live `State`, for policies that decide based on run context.
         :returns: True to offload the result to the store, False to leave it in context.
         """

{haystack_ai-3.2.0.dev20260902000321 → haystack_ai-3.2.0.dev20260903000331}/haystack/utils/hf.py

@@ -5,7 +5,7 @@
 from typing import Any
 
 from haystack import logging
-from haystack.dataclasses import ChatMessage, ImageContent, ReasoningContent, TextContent
+from haystack.dataclasses import ChatMessage, ChatRole, ImageContent, ReasoningContent, TextContent
 from haystack.lazy_imports import LazyImport
 
 with LazyImport(message="Run 'pip install \"transformers[torch]\"'") as torch_import:
@@ -69,9 +69,12 @@ def convert_message_to_hf_format(message: ChatMessage) -> dict[str, Any]:
     # ReasoningContent is for human transparency only, not sent to the API
     non_reasoning_content = [c for c in message._content if not isinstance(c, ReasoningContent)]
 
-    if not text_contents and not tool_calls and not tool_call_results and not images:
+    has_content = bool(text_contents or tool_calls or tool_call_results or images)
+    # We convert an assistant message with no content part into a message with empty content, which the API accepts
+    if not has_content and not message.is_from(ChatRole.ASSISTANT):
         raise ValueError(
-            "A `ChatMessage` must contain at least one `TextContent`, `ToolCall`, `ToolCallResult`, or `ImageContent`."
+            f"A `ChatMessage` from `{message._role.value}` must contain at least one `TextContent`, `ToolCall`, "
+            "`ToolCallResult`, or `ImageContent`. Only assistant messages can be empty."
         )
     if len(tool_call_results) > 0 and len(non_reasoning_content) > 1:
         raise ValueError(