feat: Add Human in the Loop confirmation strategies for tool execution in Agent

README.md

@@ -41,16 +41,17 @@ that includes it. Once it reaches the end of its lifespan, the experiment will b
 
 ### Active experiments
 
-| Name                                  | Type                           | Expected End Date | Dependencies | Cookbook                                                                                                                                                                                                                                                  | Discussion    |
-|---------------------------------------|--------------------------------|-------------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
-| [`InMemoryChatMessageStore`][1]       | Memory Store                   | December 2024     | None         | <a href="https://colab.research.google.com/github/deepset-ai/haystack-cookbook/blob/main/notebooks/conversational_rag_using_memory.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>      | [Discuss][4]  |
-| [`ChatMessageRetriever`][2]           | Memory Component               | December 2024     | None         | <a href="https://colab.research.google.com/github/deepset-ai/haystack-cookbook/blob/main/notebooks/conversational_rag_using_memory.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>      | [Discuss][4]  |
-| [`ChatMessageWriter`][3]              | Memory Component               | December 2024     | None         | <a href="https://colab.research.google.com/github/deepset-ai/haystack-cookbook/blob/main/notebooks/conversational_rag_using_memory.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>      | [Discuss][4]  |
-| [`QueryExpander`][5]                  | Query Expansion Component      | October 2025      | None         | None | [Discuss][6]  |
-| [`EmbeddingBasedDocumentSplitter`][8] | EmbeddingBasedDocumentSplitter | August 2025       | None         | None | [Discuss][7]  |
-| [`MultiQueryEmbeddingRetriever`][13]  | MultiQueryEmbeddingRetriever   | November 2025     | None         | None | [Discuss][11] |
-| [`MultiQueryTextRetriever`][14]       | MultiQueryTextRetriever        | November 2025     | None         | None | [Discuss][12] |
-| [`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] |
+| Name                                                                                                                                                                                    | Type                           | Expected End Date | Dependencies | Cookbook                                                                                                                                                                                                                                             | Discussion    |
+|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------|-------------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
+| [`InMemoryChatMessageStore`][1]                                                                                                                                                         | Memory Store                   | December 2024     | None         | <a href="https://colab.research.google.com/github/deepset-ai/haystack-cookbook/blob/main/notebooks/conversational_rag_using_memory.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/> | [Discuss][4]  |
+| [`ChatMessageRetriever`][2]                                                                                                                                                             | Memory Component               | December 2024     | None         | <a href="https://colab.research.google.com/github/deepset-ai/haystack-cookbook/blob/main/notebooks/conversational_rag_using_memory.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/> | [Discuss][4]  |
+| [`ChatMessageWriter`][3]                                                                                                                                                                | Memory Component               | December 2024     | None         | <a href="https://colab.research.google.com/github/deepset-ai/haystack-cookbook/blob/main/notebooks/conversational_rag_using_memory.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/> | [Discuss][4]  |
+| [`QueryExpander`][5]                                                                                                                                                                    | Query Expansion Component      | October 2025      | None         | None                                                                                                                                                                                                                                                 | [Discuss][6]  |
+| [`EmbeddingBasedDocumentSplitter`][8]                                                                                                                                                   | EmbeddingBasedDocumentSplitter | August 2025       | None         | None                                                                                                                                                                                                                                                 | [Discuss][7]  |
+| [`MultiQueryEmbeddingRetriever`][13]                                                                                                                                                    | MultiQueryEmbeddingRetriever   | November 2025     | None         | None                                                                                                                                                                                                                                                 | [Discuss][11] |
+| [`MultiQueryTextRetriever`][14]                                                                                                                                                         | MultiQueryTextRetriever        | November 2025     | None         | None                                                                                                                                                                                                                                                 | [Discuss][12] |
+| [`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] |
+| [`Agent`][15]; [Confirmation Policies][16]; [ConfirmationUIs][17]; [ConfirmationStrategies][18]; [`ConfirmationUIResult` and `ToolExecutionDecision`][19] [HITLBreakpointException][20] | Human in the Loop              | December 2025     | rich         | None                                                                                                                                                                                                                                                 | [Discuss][20] |
 
 [1]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/chat_message_stores/in_memory.py
 [2]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/retrievers/chat_message_retriever.py
@@ -66,6 +67,13 @@ that includes it. Once it reaches the end of its lifespan, the experiment will b
 [12]: https://github.com/deepset-ai/haystack-experimental/discussions/364
 [13]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/retrievers/multi_query_embedding_retriever.py
 [14]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/retrievers/multi_query_text_retriever.py
+[15]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/agents/agent.py
+[16]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/agents/human_in_the_loop/policies.py
+[17]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/agents/human_in_the_loop/user_interfaces.py
+[18]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/agents/human_in_the_loop/strategies.py
+[19]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/agents/human_in_the_loop/dataclasses.py
+[20]: https://github.com/deepset-ai/haystack-experimental/blob/main/haystack_experimental/components/agents/human_in_the_loop/errors.py
+[21]: https://github.com/deepset-ai/haystack-experimental/discussions/XXX
 
 ### Adopted experiments
 | Name                                                                                   | Type                                     | Final release |

docs/pydoc/config/agents_api.yml

@@ -0,0 +1,36 @@
+loaders:
+  - type: haystack_pydoc_tools.loaders.CustomPythonLoader
+    search_path: [../../../]
+    modules: [
+      "haystack_experimental.components.agents.agent",
+      "haystack_experimental.components.agents.human_in_the_loop.breakpoint",
+      "haystack_experimental.components.agents.human_in_the_loop.dataclasses",
+      "haystack_experimental.components.agents.human_in_the_loop.errors",
+      "haystack_experimental.components.agents.human_in_the_loop.policies",
+      "haystack_experimental.components.agents.human_in_the_loop.strategies",
+      "haystack_experimental.components.agents.human_in_the_loop.types",
+      "haystack_experimental.components.agents.human_in_the_loop.user_interfaces",
+    ]
+    ignore_when_discovered: ["__init__"]
+processors:
+  - type: filter
+    expression:
+    documented_only: true
+    do_not_filter_modules: false
+    skip_empty_modules: true
+  - type: smart
+  - type: crossref
+renderer:
+  type: haystack_pydoc_tools.renderers.ReadmeCoreRenderer
+  excerpt: Tool-using agents with provider-agnostic chat model support.
+  category_slug: haystack-api
+  title: Agents
+  slug: experimental-agents-api
+  order: 2
+  markdown:
+    descriptive_class_title: false
+    classdef_code_block: false
+    descriptive_module_title: true
+    add_method_class_prefix: true
+    add_member_class_prefix: false
+    filename: experimental_agents_api.md

haystack_experimental/components/agents/__init__.py

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <[email protected]>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import sys
+from typing import TYPE_CHECKING
+
+from lazy_imports import LazyImporter
+
+_import_structure = {"agent": ["Agent"]}
+
+if TYPE_CHECKING:
+    from .agent import Agent as Agent
+
+else:
+    sys.modules[__name__] = LazyImporter(name=__name__, module_file=__file__, import_structure=_import_structure)