haystack-experimental 0.15.2__tar.gz → 0.16.0__tar.gz

{haystack_experimental-0.15.2 → haystack_experimental-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: haystack-experimental
-Version: 0.15.2
+Version: 0.16.0
 Summary: Experimental components and features for the Haystack LLM framework.
 Project-URL: CI: GitHub, https://github.com/deepset-ai/haystack-experimental/actions
 Project-URL: GitHub: issues, https://github.com/deepset-ai/haystack-experimental/issues
@@ -17,15 +17,13 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Requires-Dist: haystack-ai
-Requires-Dist: lazy-imports<1.2.0
 Requires-Dist: rich
 Description-Content-Type: text/markdown
 
@@ -74,7 +72,6 @@ that includes it. Once it reaches the end of its lifespan, the experiment will b
 
 | Name                                                                                                                                                                                    | Type                                  | Expected End Date | Dependencies | Cookbook                                                                                                                                                                                                                                                   | Discussion    |
 |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------|-------------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
-| [`EmbeddingBasedDocumentSplitter`][8]                                                                                                                                                   | EmbeddingBasedDocumentSplitter        | August 2025       | None         | None                                                                                                                                                                                                                                                       | [Discuss][7]  |
 | [`OpenAIChatGenerator`][9]                                                                                                                                                              | Chat Generator Component              | November 2025     | None         | <a href="https://colab.research.google.com/github/deepset-ai/haystack-cookbook/blob/main/notebooks/hallucination_score_calculator.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>        | [Discuss][10] |
 | [`MarkdownHeaderLevelInferrer`][15]                                                                                                                                                     | Preprocessor                          | January 2025      | None         | None                                                                                                                                                                                                                                                       | [Discuss][16] |
 | [`Agent`][17]; [Confirmation Policies][18]; [ConfirmationUIs][19]; [ConfirmationStrategies][20]; [`ConfirmationUIResult` and `ToolExecutionDecision`][21] [HITLBreakpointException][22] | Human in the Loop                     | December 2025     | rich         | None                                                                                                                                                                                                                                                       | [Discuss][23] |
@@ -85,8 +82,6 @@ that includes it. Once it reaches the end of its lifespan, the experiment will b
 [2]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/retrievers/chat_message_retriever.py
 [3]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/writers/chat_message_writer.py
 [4]: https://github.com/deepset-ai/haystack-experimental/discussions/75
-[7]: https://github.com/deepset-ai/haystack-experimental/discussions/356
-[8]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/preprocessors/embedding_based_document_splitter.py
 [9]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/generators/chat/openai.py
 [10]: https://github.com/deepset-ai/haystack-experimental/discussions/361
 [15]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/preprocessors/md_header_level_inferrer.py  
@@ -112,10 +107,10 @@ that includes it. Once it reaches the end of its lifespan, the experiment will b
 | `SuperComponent`                                                                                                                                                                                                                           | Simplify Pipeline development            | 0.8.0         |
 | `Pipeline`                                                                                                                                                                                                                                 | Pipeline breakpoints for debugging       | 0.12.0        |
 | `ImageContent`; Image Converters; multimodal support in `OpenAIChatGenerator` and `AmazonBedrockChatGenerator`; `ChatPromptBuilder` refactoring; `SentenceTransformersDocumentImageEmbedder`; `LLMDocumentContentExtractor`; new `Routers` | Multimodality                            | 0.12.0        |
-| `QueryExpander`                                                                                                                                                                                                                            | Query Expansion Component                | 0.14.3       |
-| `MultiQueryEmbeddingRetriever`                                                                                                                                                                                                             | MultiQueryEmbeddingRetriever             | 0.14.3       |
-| `MultiQueryTextRetriever`                                                                                                                                                                                                                  | MultiQueryTextRetriever                  | 0.14.3       |
-
+| `QueryExpander`                                                                                                                                                                                                                            | Query Expansion Component                | 0.14.3        |
+| `MultiQueryEmbeddingRetriever`                                                                                                                                                                                                             | MultiQueryEmbeddingRetriever             | 0.14.3        |
+| `MultiQueryTextRetriever`                                                                                                                                                                                                                  | MultiQueryTextRetriever                  | 0.14.3        |
+| `EmbeddingBasedDocumentSplitter`                                                                                                                                                                                                             | Document Splitting                       | 0.15.2        |
 
 ### Discontinued experiments
 

{haystack_experimental-0.15.2 → haystack_experimental-0.16.0}/README.md

@@ -43,7 +43,6 @@ that includes it. Once it reaches the end of its lifespan, the experiment will b
 
 | Name                                                                                                                                                                                    | Type                                  | Expected End Date | Dependencies | Cookbook                                                                                                                                                                                                                                                   | Discussion    |
 |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------|-------------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
-| [`EmbeddingBasedDocumentSplitter`][8]                                                                                                                                                   | EmbeddingBasedDocumentSplitter        | August 2025       | None         | None                                                                                                                                                                                                                                                       | [Discuss][7]  |
 | [`OpenAIChatGenerator`][9]                                                                                                                                                              | Chat Generator Component              | November 2025     | None         | <a href="https://colab.research.google.com/github/deepset-ai/haystack-cookbook/blob/main/notebooks/hallucination_score_calculator.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>        | [Discuss][10] |
 | [`MarkdownHeaderLevelInferrer`][15]                                                                                                                                                     | Preprocessor                          | January 2025      | None         | None                                                                                                                                                                                                                                                       | [Discuss][16] |
 | [`Agent`][17]; [Confirmation Policies][18]; [ConfirmationUIs][19]; [ConfirmationStrategies][20]; [`ConfirmationUIResult` and `ToolExecutionDecision`][21] [HITLBreakpointException][22] | Human in the Loop                     | December 2025     | rich         | None                                                                                                                                                                                                                                                       | [Discuss][23] |
@@ -54,8 +53,6 @@ that includes it. Once it reaches the end of its lifespan, the experiment will b
 [2]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/retrievers/chat_message_retriever.py
 [3]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/writers/chat_message_writer.py
 [4]: https://github.com/deepset-ai/haystack-experimental/discussions/75
-[7]: https://github.com/deepset-ai/haystack-experimental/discussions/356
-[8]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/preprocessors/embedding_based_document_splitter.py
 [9]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/generators/chat/openai.py
 [10]: https://github.com/deepset-ai/haystack-experimental/discussions/361
 [15]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/preprocessors/md_header_level_inferrer.py  
@@ -81,10 +78,10 @@ that includes it. Once it reaches the end of its lifespan, the experiment will b
 | `SuperComponent`                                                                                                                                                                                                                           | Simplify Pipeline development            | 0.8.0         |
 | `Pipeline`                                                                                                                                                                                                                                 | Pipeline breakpoints for debugging       | 0.12.0        |
 | `ImageContent`; Image Converters; multimodal support in `OpenAIChatGenerator` and `AmazonBedrockChatGenerator`; `ChatPromptBuilder` refactoring; `SentenceTransformersDocumentImageEmbedder`; `LLMDocumentContentExtractor`; new `Routers` | Multimodality                            | 0.12.0        |
-| `QueryExpander`                                                                                                                                                                                                                            | Query Expansion Component                | 0.14.3       |
-| `MultiQueryEmbeddingRetriever`                                                                                                                                                                                                             | MultiQueryEmbeddingRetriever             | 0.14.3       |
-| `MultiQueryTextRetriever`                                                                                                                                                                                                                  | MultiQueryTextRetriever                  | 0.14.3       |
-
+| `QueryExpander`                                                                                                                                                                                                                            | Query Expansion Component                | 0.14.3        |
+| `MultiQueryEmbeddingRetriever`                                                                                                                                                                                                             | MultiQueryEmbeddingRetriever             | 0.14.3        |
+| `MultiQueryTextRetriever`                                                                                                                                                                                                                  | MultiQueryTextRetriever                  | 0.14.3        |
+| `EmbeddingBasedDocumentSplitter`                                                                                                                                                                                                             | Document Splitting                       | 0.15.2        |
 
 ### Discontinued experiments
 

{haystack_experimental-0.15.2 → haystack_experimental-0.16.0}/haystack_experimental/chat_message_stores/in_memory.py

@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 from dataclasses import replace
-from typing import Any, Iterable, Optional
+from typing import Any, Iterable
 
 from haystack import default_from_dict, default_to_dict
 from haystack.dataclasses import ChatMessage, ChatRole
@@ -42,7 +42,7 @@ class InMemoryChatMessageStore:
     ```
     """
 
-    def __init__(self, skip_system_messages: bool = True, last_k: Optional[int] = 10) -> None:
+    def __init__(self, skip_system_messages: bool = True, last_k: int | None = 10) -> None:
         """
         Create an InMemoryChatMessageStore.
 
@@ -135,7 +135,7 @@ class InMemoryChatMessageStore:
 
         return len(messages_to_write)
 
-    def retrieve_messages(self, chat_history_id: str, last_k: Optional[int] = None) -> list[ChatMessage]:
+    def retrieve_messages(self, chat_history_id: str, last_k: int | None = None) -> list[ChatMessage]:
         """
         Retrieves all stored chat messages.
 

{haystack_experimental-0.15.2 → haystack_experimental-0.16.0}/haystack_experimental/chat_message_stores/types.py

@@ -2,7 +2,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-from typing import Any, Optional, Protocol
+from typing import Any, Protocol
 
 from haystack.dataclasses import ChatMessage
 
@@ -74,7 +74,7 @@ class ChatMessageStore(Protocol):
         """
         ...
 
-    def retrieve_messages(self, chat_history_id: str, last_k: Optional[int] = None) -> list[ChatMessage]:
+    def retrieve_messages(self, chat_history_id: str, last_k: int | None = None) -> list[ChatMessage]:
         """
         Retrieves chat messages from the ChatMessageStore.
 

{haystack_experimental-0.15.2 → haystack_experimental-0.16.0}/haystack_experimental/components/agents/agent.py

@@ -7,7 +7,7 @@
 
 import inspect
 from dataclasses import dataclass
-from typing import Any, Optional, Union
+from typing import Any
 
 # Monkey patch Haystack's AgentSnapshot with our extended version
 import haystack.dataclasses.breakpoints as hdb
@@ -28,11 +28,13 @@ from haystack.components.agents.agent import _ExecutionContext as Haystack_Execu
 from haystack.components.agents.agent import _schema_from_dict
 from haystack.components.agents.state import replace_values, State
 from haystack.components.generators.chat.types import ChatGenerator
-from haystack.core.errors import PipelineRuntimeError
+from haystack.core.errors import BreakpointException, PipelineRuntimeError
 from haystack.core.pipeline import AsyncPipeline, Pipeline
 from haystack.core.pipeline.breakpoint import (
     _create_pipeline_snapshot_from_chat_generator,
     _create_pipeline_snapshot_from_tool_invoker,
+    _save_pipeline_snapshot,
+    _should_trigger_tool_invoker_breakpoint,
 )
 from haystack.core.pipeline.utils import _deepcopy_with_exceptions
 from haystack.core.serialization import default_from_dict, import_class_by_name
@@ -75,8 +77,8 @@ class _ExecutionContext(Haystack_ExecutionContext):
         parameter in their `run()` and `run_async()` methods.
     """
 
-    tool_execution_decisions: Optional[list[ToolExecutionDecision]] = None
-    confirmation_strategy_context: Optional[dict[str, Any]] = None
+    tool_execution_decisions: list[ToolExecutionDecision] | None = None
+    confirmation_strategy_context: dict[str, Any] | None = None
 
 
 class Agent(HaystackAgent):
@@ -134,16 +136,16 @@ class Agent(HaystackAgent):
         self,
         *,
         chat_generator: ChatGenerator,
-        tools: Optional[ToolsType] = None,
-        system_prompt: Optional[str] = None,
-        exit_conditions: Optional[list[str]] = None,
-        state_schema: Optional[dict[str, Any]] = None,
+        tools: ToolsType | None = None,
+        system_prompt: str | None = None,
+        exit_conditions: list[str] | None = None,
+        state_schema: dict[str, Any] | None = None,
         max_agent_steps: int = 100,
-        streaming_callback: Optional[StreamingCallbackT] = None,
+        streaming_callback: StreamingCallbackT | None = None,
         raise_on_tool_invocation_failure: bool = False,
-        confirmation_strategies: Optional[dict[str, ConfirmationStrategy]] = None,
-        tool_invoker_kwargs: Optional[dict[str, Any]] = None,
-        chat_message_store: Optional[ChatMessageStore] = None,
+        confirmation_strategies: dict[str, ConfirmationStrategy] | None = None,
+        tool_invoker_kwargs: dict[str, Any] | None = None,
+        chat_message_store: ChatMessageStore | None = None,
     ) -> None:
         """
         Initialize the agent component.
@@ -188,14 +190,14 @@ class Agent(HaystackAgent):
     def _initialize_fresh_execution(
         self,
         messages: list[ChatMessage],
-        streaming_callback: Optional[StreamingCallbackT],
+        streaming_callback: StreamingCallbackT | None,
         requires_async: bool,
         *,
-        system_prompt: Optional[str] = None,
-        generation_kwargs: Optional[dict[str, Any]] = None,
-        tools: Optional[Union[ToolsType, list[str]]] = None,
-        confirmation_strategy_context: Optional[dict[str, Any]] = None,
-        chat_message_store_kwargs: Optional[dict[str, Any]] = None,
+        system_prompt: str | None = None,
+        generation_kwargs: dict[str, Any] | None = None,
+        tools: ToolsType | list[str] | None = None,
+        confirmation_strategy_context: dict[str, Any] | None = None,
+        chat_message_store_kwargs: dict[str, Any] | None = None,
         **kwargs: dict[str, Any],
     ) -> _ExecutionContext:
         """
@@ -262,12 +264,12 @@ class Agent(HaystackAgent):
     def _initialize_from_snapshot(  # type: ignore[override]
         self,
         snapshot: AgentSnapshot,
-        streaming_callback: Optional[StreamingCallbackT],
+        streaming_callback: StreamingCallbackT | None,
         requires_async: bool,
         *,
-        generation_kwargs: Optional[dict[str, Any]] = None,
-        tools: Optional[Union[ToolsType, list[str]]] = None,
-        confirmation_strategy_context: Optional[dict[str, Any]] = None,
+        generation_kwargs: dict[str, Any] | None = None,
+        tools: ToolsType | list[str] | None = None,
+        confirmation_strategy_context: dict[str, Any] | None = None,
     ) -> _ExecutionContext:
         """
         Initialize execution context from an AgentSnapshot.
@@ -315,18 +317,18 @@ class Agent(HaystackAgent):
             confirmation_strategy_context=confirmation_strategy_context,
         )
 
-    def run(  # type: ignore[override]  # noqa: PLR0915
+    def run(  # type: ignore[override]  # noqa: PLR0915 PLR0912
         self,
         messages: list[ChatMessage],
-        streaming_callback: Optional[StreamingCallbackT] = None,
+        streaming_callback: StreamingCallbackT | None = None,
         *,
-        generation_kwargs: Optional[dict[str, Any]] = None,
-        break_point: Optional[AgentBreakpoint] = None,
-        snapshot: Optional[AgentSnapshot] = None,
-        system_prompt: Optional[str] = None,
-        tools: Optional[Union[ToolsType, list[str]]] = None,
-        confirmation_strategy_context: Optional[dict[str, Any]] = None,
-        chat_message_store_kwargs: Optional[dict[str, Any]] = None,
+        generation_kwargs: dict[str, Any] | None = None,
+        break_point: AgentBreakpoint | None = None,
+        snapshot: AgentSnapshot | None = None,
+        system_prompt: str | None = None,
+        tools: ToolsType | list[str] | None = None,
+        confirmation_strategy_context: dict[str, Any] | None = None,
+        chat_message_store_kwargs: dict[str, Any] | None = None,
         **kwargs: Any,
     ) -> dict[str, Any]:
         """
@@ -360,8 +362,6 @@ class Agent(HaystackAgent):
         :raises RuntimeError: If the Agent component wasn't warmed up before calling `run()`.
         :raises BreakpointException: If an agent breakpoint is triggered.
         """
-        # We pop parent_snapshot from kwargs to avoid passing it into State.
-        parent_snapshot = kwargs.pop("parent_snapshot", None)
         agent_inputs = {
             "messages": messages,
             "streaming_callback": streaming_callback,
@@ -369,13 +369,9 @@ class Agent(HaystackAgent):
             "snapshot": snapshot,
             **kwargs,
         }
-        # The PR https://github.com/deepset-ai/haystack/pull/9987 removed the unused snapshot parameter from
-        # _runtime_checks. This change will be released in Haystack 2.20.0.
-        # To maintain compatibility with Haystack 2.19 we check the number of parameters and call accordingly.
-        if len(inspect.signature(self._runtime_checks).parameters) == 2:
-            self._runtime_checks(break_point, snapshot)  # type: ignore[call-arg]  # pylint: disable=too-many-function-args
-        else:
-            self._runtime_checks(break_point)  # type: ignore[call-arg]  # pylint: disable=no-value-for-parameter
+        # TODO Probably good to add a warning in runtime checks that BreakpointConfirmationStrategy will take
+        #  precedence over passing a ToolBreakpoint
+        self._runtime_checks(break_point)
 
         if snapshot:
             exe_context = self._initialize_from_snapshot(
@@ -403,10 +399,6 @@ class Agent(HaystackAgent):
             span.set_content_tag("haystack.agent.input", _deepcopy_with_exceptions(agent_inputs))
 
             while exe_context.counter < self.max_agent_steps:
-                # Handle breakpoint and ChatGenerator call
-                Agent._check_chat_generator_breakpoint(
-                    execution_context=exe_context, break_point=break_point, parent_snapshot=parent_snapshot
-                )
                 # We skip the chat generator when restarting from a snapshot from a ToolBreakpoint
                 if exe_context.skip_chat_generator:
                     llm_messages = exe_context.state.get("messages", [])[-1:]
@@ -423,14 +415,26 @@ class Agent(HaystackAgent):
                             },
                             component_visits=exe_context.component_visits,
                             parent_span=span,
+                            break_point=break_point.break_point if isinstance(break_point, AgentBreakpoint) else None,
                         )
-                    except PipelineRuntimeError as e:
-                        pipeline_snapshot = _create_pipeline_snapshot_from_chat_generator(
-                            agent_name=getattr(self, "__component_name__", None),
-                            execution_context=exe_context,
-                            parent_snapshot=parent_snapshot,
+                    except (BreakpointException, PipelineRuntimeError) as e:
+                        if isinstance(e, BreakpointException):
+                            agent_name = break_point.agent_name if break_point else None
+                            saved_bp = break_point
+                        else:
+                            agent_name = getattr(self, "__component_name__", None)
+                            saved_bp = None
+
+                        e.pipeline_snapshot = _create_pipeline_snapshot_from_chat_generator(
+                            agent_name=agent_name, execution_context=exe_context, break_point=saved_bp
                         )
-                        e.pipeline_snapshot = pipeline_snapshot
+                        if isinstance(e, BreakpointException):
+                            e._break_point = e.pipeline_snapshot.break_point
+                        # If Agent is not in a pipeline, we save the snapshot to a file.
+                        # Checked by __component_name__ not being set.
+                        if getattr(self, "__component_name__", None) is None:
+                            full_file_path = _save_pipeline_snapshot(pipeline_snapshot=e.pipeline_snapshot)
+                            e.pipeline_snapshot_file_path = full_file_path
                         raise e
 
                     llm_messages = result["replies"]
@@ -441,6 +445,19 @@ class Agent(HaystackAgent):
                     exe_context.counter += 1
                     break
 
+                # We only pass down the breakpoint if the tool name matches the tool call in the LLM messages
+                resolved_break_point = None
+                break_point_to_pass = None
+                if (
+                    break_point
+                    and isinstance(break_point.break_point, ToolBreakpoint)
+                    and _should_trigger_tool_invoker_breakpoint(
+                        break_point=break_point.break_point, llm_messages=llm_messages
+                    )
+                ):
+                    resolved_break_point = break_point
+                    break_point_to_pass = resolved_break_point.break_point
+
                 # Apply confirmation strategies and update State and messages sent to ToolInvoker
                 try:
                     # Run confirmation strategies to get updated tool call messages and modified chat history
@@ -452,8 +469,8 @@ class Agent(HaystackAgent):
                     # Replace the chat history in state with the modified one
                     exe_context.state.set(key="messages", value=new_chat_history, handler_override=replace_values)
                 except HITLBreakpointException as tbp_error:
-                    # We create a break_point to pass into _check_tool_invoker_breakpoint
-                    break_point = AgentBreakpoint(
+                    # We create a break_point to pass to Pipeline._run_component
+                    resolved_break_point = AgentBreakpoint(
                         agent_name=getattr(self, "__component_name__", ""),
                         break_point=ToolBreakpoint(
                             component_name="tool_invoker",
@@ -462,11 +479,9 @@ class Agent(HaystackAgent):
                             snapshot_file_path=tbp_error.snapshot_file_path,
                         ),
                     )
-
-                # Handle breakpoint
-                Agent._check_tool_invoker_breakpoint(
-                    execution_context=exe_context, break_point=break_point, parent_snapshot=parent_snapshot
-                )
+                    break_point_to_pass = resolved_break_point.break_point
+                    # If we hit a HITL breakpoint, we skip passing modified messages to ToolInvoker
+                    modified_tool_call_messages = llm_messages
 
                 # Run ToolInvoker
                 try:
@@ -481,19 +496,28 @@ class Agent(HaystackAgent):
                         },
                         component_visits=exe_context.component_visits,
                         parent_span=span,
+                        break_point=break_point_to_pass,
                     )
-                except PipelineRuntimeError as e:
-                    # Access the original Tool Invoker exception
-                    original_error = e.__cause__
-                    tool_name = getattr(original_error, "tool_name", None)
-
-                    pipeline_snapshot = _create_pipeline_snapshot_from_tool_invoker(
-                        tool_name=tool_name,
-                        agent_name=getattr(self, "__component_name__", None),
-                        execution_context=exe_context,
-                        parent_snapshot=parent_snapshot,
+                except (BreakpointException, PipelineRuntimeError) as e:
+                    if isinstance(e, BreakpointException):
+                        agent_name = resolved_break_point.agent_name if resolved_break_point else None
+                        tool_name = e.break_point.tool_name if isinstance(e.break_point, ToolBreakpoint) else None
+                        saved_bp = resolved_break_point
+                    else:
+                        agent_name = getattr(self, "__component_name__", None)
+                        tool_name = getattr(e.__cause__, "tool_name", None)
+                        saved_bp = None
+
+                    e.pipeline_snapshot = _create_pipeline_snapshot_from_tool_invoker(
+                        tool_name=tool_name, agent_name=agent_name, execution_context=exe_context, break_point=saved_bp
                     )
-                    e.pipeline_snapshot = pipeline_snapshot
+                    if isinstance(e, BreakpointException):
+                        e._break_point = e.pipeline_snapshot.break_point
+                    # If Agent is not in a pipeline, we save the snapshot to a file.
+                    # Checked by __component_name__ not being set.
+                    if getattr(self, "__component_name__", None) is None:
+                        full_file_path = _save_pipeline_snapshot(pipeline_snapshot=e.pipeline_snapshot)
+                        e.pipeline_snapshot_file_path = full_file_path
                     raise e
 
                 # Set execution context tool execution decisions to empty after applying them b/c they should only
@@ -531,18 +555,18 @@ class Agent(HaystackAgent):
 
         return result
 
-    async def run_async(  # type: ignore[override]
+    async def run_async(  # type: ignore[override] # noqa: PLR0915
         self,
         messages: list[ChatMessage],
-        streaming_callback: Optional[StreamingCallbackT] = None,
+        streaming_callback: StreamingCallbackT | None = None,
         *,
-        generation_kwargs: Optional[dict[str, Any]] = None,
-        break_point: Optional[AgentBreakpoint] = None,
-        snapshot: Optional[AgentSnapshot] = None,
-        system_prompt: Optional[str] = None,
-        tools: Optional[Union[ToolsType, list[str]]] = None,
-        confirmation_strategy_context: Optional[dict[str, Any]] = None,
-        chat_message_store_kwargs: Optional[dict[str, Any]] = None,
+        generation_kwargs: dict[str, Any] | None = None,
+        break_point: AgentBreakpoint | None = None,
+        snapshot: AgentSnapshot | None = None,
+        system_prompt: str | None = None,
+        tools: ToolsType | list[str] | None = None,
+        confirmation_strategy_context: dict[str, Any] | None = None,
+        chat_message_store_kwargs: dict[str, Any] | None = None,
         **kwargs: Any,
     ) -> dict[str, Any]:
         """
@@ -579,8 +603,6 @@ class Agent(HaystackAgent):
         :raises RuntimeError: If the Agent component wasn't warmed up before calling `run_async()`.
         :raises BreakpointException: If an agent breakpoint is triggered.
         """
-        # We pop parent_snapshot from kwargs to avoid passing it into State.
-        parent_snapshot = kwargs.pop("parent_snapshot", None)
         agent_inputs = {
             "messages": messages,
             "streaming_callback": streaming_callback,
@@ -588,13 +610,7 @@ class Agent(HaystackAgent):
             "snapshot": snapshot,
             **kwargs,
         }
-        # The PR https://github.com/deepset-ai/haystack/pull/9987 removed the unused snapshot parameter from
-        # _runtime_checks. This change will be released in Haystack 2.20.0.
-        # To maintain compatibility with Haystack 2.19 we check the number of parameters and call accordingly.
-        if len(inspect.signature(self._runtime_checks).parameters) == 2:
-            self._runtime_checks(break_point, snapshot)  # type: ignore[call-arg]  # pylint: disable=too-many-function-args
-        else:
-            self._runtime_checks(break_point)  # type: ignore[call-arg]  # pylint: disable=no-value-for-parameter
+        self._runtime_checks(break_point)
 
         if snapshot:
             exe_context = self._initialize_from_snapshot(
@@ -622,26 +638,39 @@ class Agent(HaystackAgent):
             span.set_content_tag("haystack.agent.input", _deepcopy_with_exceptions(agent_inputs))
 
             while exe_context.counter < self.max_agent_steps:
-                # Handle breakpoint and ChatGenerator call
-                self._check_chat_generator_breakpoint(
-                    execution_context=exe_context, break_point=break_point, parent_snapshot=parent_snapshot
-                )
                 # We skip the chat generator when restarting from a snapshot from a ToolBreakpoint
                 if exe_context.skip_chat_generator:
                     llm_messages = exe_context.state.get("messages", [])[-1:]
                     # Set to False so the next iteration will call the chat generator
                     exe_context.skip_chat_generator = False
                 else:
-                    result = await AsyncPipeline._run_component_async(
-                        component_name="chat_generator",
-                        component={"instance": self.chat_generator},
-                        component_inputs={
-                            "messages": exe_context.state.data["messages"],
-                            **exe_context.chat_generator_inputs,
-                        },
-                        component_visits=exe_context.component_visits,
-                        parent_span=span,
-                    )
+                    try:
+                        result = await AsyncPipeline._run_component_async(
+                            component_name="chat_generator",
+                            component={"instance": self.chat_generator},
+                            component_inputs={
+                                "messages": exe_context.state.data["messages"],
+                                **exe_context.chat_generator_inputs,
+                            },
+                            component_visits=exe_context.component_visits,
+                            parent_span=span,
+                            break_point=break_point.break_point if isinstance(break_point, AgentBreakpoint) else None,
+                        )
+                    except BreakpointException as e:
+                        e.pipeline_snapshot = _create_pipeline_snapshot_from_chat_generator(
+                            agent_name=break_point.agent_name if break_point else None,
+                            execution_context=exe_context,
+                            break_point=break_point,
+                        )
+                        e._break_point = e.pipeline_snapshot.break_point
+                        # We check if the agent is part of a pipeline by checking for __component_name__
+                        # If it is not in a pipeline, we save the snapshot to a file.
+                        in_pipeline = getattr(self, "__component_name__", None) is not None
+                        if not in_pipeline:
+                            full_file_path = _save_pipeline_snapshot(pipeline_snapshot=e.pipeline_snapshot)
+                            e.pipeline_snapshot_file_path = full_file_path
+                        raise e
+
                     llm_messages = result["replies"]
                     exe_context.state.set("messages", llm_messages)
 
@@ -650,6 +679,19 @@ class Agent(HaystackAgent):
                     exe_context.counter += 1
                     break
 
+                # We only pass down the breakpoint if the tool name matches the tool call in the LLM messages
+                resolved_break_point = None
+                break_point_to_pass = None
+                if (
+                    break_point
+                    and isinstance(break_point.break_point, ToolBreakpoint)
+                    and _should_trigger_tool_invoker_breakpoint(
+                        break_point=break_point.break_point, llm_messages=llm_messages
+                    )
+                ):
+                    resolved_break_point = break_point
+                    break_point_to_pass = resolved_break_point.break_point
+
                 # Apply confirmation strategies and update State and messages sent to ToolInvoker
                 try:
                     # Run confirmation strategies to get updated tool call messages and modified chat history (async)
@@ -662,7 +704,7 @@ class Agent(HaystackAgent):
                     exe_context.state.set(key="messages", value=new_chat_history, handler_override=replace_values)
                 except HITLBreakpointException as tbp_error:
                     # We create a break_point to pass into _check_tool_invoker_breakpoint
-                    break_point = AgentBreakpoint(
+                    resolved_break_point = AgentBreakpoint(
                         agent_name=getattr(self, "__component_name__", ""),
                         break_point=ToolBreakpoint(
                             component_name="tool_invoker",
@@ -671,25 +713,38 @@ class Agent(HaystackAgent):
                             snapshot_file_path=tbp_error.snapshot_file_path,
                         ),
                     )
+                    break_point_to_pass = resolved_break_point.break_point
+                    # If we hit a HITL breakpoint, we skip passing modified messages to ToolInvoker
+                    modified_tool_call_messages = llm_messages
 
-                # Handle breakpoint
-                Agent._check_tool_invoker_breakpoint(
-                    execution_context=exe_context, break_point=break_point, parent_snapshot=parent_snapshot
-                )
-
-                # Run ToolInvoker
-                # We only send the messages from the LLM to the tool invoker
-                tool_invoker_result = await AsyncPipeline._run_component_async(
-                    component_name="tool_invoker",
-                    component={"instance": self._tool_invoker},
-                    component_inputs={
-                        "messages": modified_tool_call_messages,
-                        "state": exe_context.state,
-                        **exe_context.tool_invoker_inputs,
-                    },
-                    component_visits=exe_context.component_visits,
-                    parent_span=span,
-                )
+                try:
+                    # We only send the messages from the LLM to the tool invoker
+                    tool_invoker_result = await AsyncPipeline._run_component_async(
+                        component_name="tool_invoker",
+                        component={"instance": self._tool_invoker},
+                        component_inputs={
+                            "messages": modified_tool_call_messages,
+                            "state": exe_context.state,
+                            **exe_context.tool_invoker_inputs,
+                        },
+                        component_visits=exe_context.component_visits,
+                        parent_span=span,
+                        break_point=break_point_to_pass,
+                    )
+                except BreakpointException as e:
+                    e.pipeline_snapshot = _create_pipeline_snapshot_from_tool_invoker(
+                        tool_name=e.break_point.tool_name if isinstance(e.break_point, ToolBreakpoint) else None,
+                        agent_name=resolved_break_point.agent_name if resolved_break_point else None,
+                        execution_context=exe_context,
+                        break_point=resolved_break_point,
+                    )
+                    e._break_point = e.pipeline_snapshot.break_point
+                    # If Agent is not in a pipeline, we save the snapshot to a file.
+                    # Checked by __component_name__ not being set.
+                    if getattr(self, "__component_name__", None) is None:
+                        full_file_path = _save_pipeline_snapshot(pipeline_snapshot=e.pipeline_snapshot)
+                        e.pipeline_snapshot_file_path = full_file_path
+                    raise e
 
                 # Set execution context tool execution decisions to empty after applying them b/c they should only
                 # be used once for the current tool calls