agent-pack-haystack 0.0.1__py3-none-any.whl

agent_pack_haystack-0.0.1.dist-info/METADATA

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: agent-pack-haystack
+Version: 0.0.1
+Summary: Pre-configured Haystack Agents
+Project-URL: Documentation, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/agent_pack#readme
+Project-URL: Issues, https://github.com/deepset-ai/haystack-core-integrations/issues
+Project-URL: Source, https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/agent_pack
+Author-email: deepset GmbH <info@deepset.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE.txt
+Keywords: agents,haystack
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python
+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: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: haystack-ai>=3.0.0
+Description-Content-Type: text/markdown
+
+# agent-pack-haystack
+
+[![PyPI - Version](https://img.shields.io/pypi/v/agent-pack-haystack.svg)](https://pypi.org/project/agent-pack-haystack)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/agent-pack-haystack.svg)](https://pypi.org/project/agent-pack-haystack)
+
+- [Changelog](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/agent_pack/CHANGELOG.md)
+
+---
+
+## Contributing
+
+Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
+
+To run integration tests locally, you need to export the `OPENAI_API_KEY` and `TAVILY_API_KEY` environment variables.

agent_pack_haystack-0.0.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+haystack_integrations/agent_pack/__init__.py,sha256=KHB2rXe8bnIbyL7hs25noL3N_wHgwjtba-N_hyV05-Y,288
+haystack_integrations/agent_pack/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+haystack_integrations/agent_pack/advanced_rag/__init__.py,sha256=XX-ddnPoMOFTmWbOtROCvtDxJUZKWx8sg8b_eba1TPM,535
+haystack_integrations/agent_pack/advanced_rag/agent.py,sha256=-PvM7S0e2i2n-LtCNztR5pGoydPMQxYZqENKp6li4Hw,9411
+haystack_integrations/agent_pack/advanced_rag/hooks.py,sha256=1_yjVrmI5lx3B5hnPr2nb2J7cMD0jZJXKlN1ivzk7KA,3438
+haystack_integrations/agent_pack/advanced_rag/prompts.py,sha256=FiIrPFsR915m0536tLBep9N7p--Rlc2QTqY7avUNy2I,4716
+haystack_integrations/agent_pack/advanced_rag/tools.py,sha256=A-jPLJr66Qe82oiG8xpIj-k5CtQ_rX0Y8xx3GIZwiIk,35130
+haystack_integrations/agent_pack/deep_research/__init__.py,sha256=vE1wxfJ1Z9rhz_uINRHLQvZL0mAeRZxBhtChv4h3K8s,199
+haystack_integrations/agent_pack/deep_research/agent.py,sha256=b1lQSgNZlLKz6EivF50wI1EBSLxyYz5d4YkWcm0t-n4,8694
+haystack_integrations/agent_pack/deep_research/hooks.py,sha256=9t_MnlII9ELiWQqldmW8eSlgb4PAOMnmz02WLs4AXs4,3562
+haystack_integrations/agent_pack/deep_research/prompts.py,sha256=hcWu68LeS1sC-fX0vYBLzNLdMS_aky3OK6ceR9uC2Gs,4469
+haystack_integrations/agent_pack/deep_research/tools.py,sha256=aDV2skNIk01uJ80skLqVqEc5WjpfriwnpAyWwPbWsvY,4939
+agent_pack_haystack-0.0.1.dist-info/METADATA,sha256=IP6rGjw-WZFOPYICeVtsh7uHW6P6ejly1uSLYl4HAJk,1873
+agent_pack_haystack-0.0.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+agent_pack_haystack-0.0.1.dist-info/licenses/LICENSE.txt,sha256=OrAtTu4aPmrTjKDSTzkSPgo_ji6NOMWO2N9JOTFyAzM,11350
+agent_pack_haystack-0.0.1.dist-info/RECORD,,

agent_pack_haystack-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_pack_haystack-0.0.1.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2023-present deepset GmbH
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

haystack_integrations/agent_pack/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .advanced_rag import create_advanced_rag_agent
+from .deep_research import create_deep_research_agent
+
+__all__ = ["create_advanced_rag_agent", "create_deep_research_agent"]

haystack_integrations/agent_pack/advanced_rag/__init__.py

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .agent import create_advanced_rag_agent
+from .tools import (
+    DocumentStoreToolset,
+    FetchDocumentsByFilterTool,
+    GetMetadataFieldRangeTool,
+    GetMetadataFieldValuesTool,
+    ListMetadataFieldsTool,
+)
+
+__all__ = [
+    "DocumentStoreToolset",
+    "FetchDocumentsByFilterTool",
+    "GetMetadataFieldRangeTool",
+    "GetMetadataFieldValuesTool",
+    "ListMetadataFieldsTool",
+    "create_advanced_rag_agent",
+]

haystack_integrations/agent_pack/advanced_rag/agent.py

@@ -0,0 +1,170 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any
+
+from haystack import Document, Pipeline
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIResponsesChatGenerator
+from haystack.components.generators.chat.types import ChatGenerator
+from haystack.components.retrievers.types import TextRetriever
+from haystack.document_stores.types import DocumentStore
+from haystack.hooks import Hook, HookPoint
+from haystack.lazy_imports import LazyImport
+from haystack.tools import Tool, Toolset, ToolsType
+
+from haystack_integrations.agent_pack.advanced_rag import prompts
+from haystack_integrations.agent_pack.advanced_rag.hooks import BackupAnswerHook
+from haystack_integrations.agent_pack.advanced_rag.tools import (
+    DocumentStoreToolset,
+    _make_retrieval_pipeline_tool,
+    _make_retriever_tool,
+)
+
+# The default system prompt renders today's date via the Jinja `{% now %}` tag, which needs `arrow`. Without this
+# check, a missing `arrow` surfaces as a cryptic `TemplateSyntaxError: Encountered unknown tag 'now'` because
+# `ChatPromptBuilder` silently skips the extension when `arrow` is not installed.
+with LazyImport(message='Run "pip install arrow>=1.3.0"') as arrow_import:
+    import arrow  # noqa: F401
+
+_DEFAULT_TIMEOUT = 180.0
+_DEFAULT_MAX_RETRIES = 5
+
+
+def _default_llm(model: str) -> OpenAIResponsesChatGenerator:
+    """
+    A default OpenAI Responses-API generator with the pack's timeout/retry settings.
+
+    Reasoning effort is set to "low": enough deliberate thinking for tool sequencing and filter construction, without
+    compounding latency across the agent's steps (leaving it unset would default to the heavier "medium").
+
+    :param model: The OpenAI model name.
+    :returns: The generator.
+    """
+    return OpenAIResponsesChatGenerator(
+        model=model,
+        timeout=_DEFAULT_TIMEOUT,
+        max_retries=_DEFAULT_MAX_RETRIES,
+        generation_kwargs={"reasoning": {"effort": "low"}},
+    )
+
+
+def create_advanced_rag_agent(
+    *,
+    document_store: DocumentStore,
+    retriever: TextRetriever | Pipeline | None = None,
+    retrieval_pipeline_input_mapping: dict[str, list[str]] | None = None,
+    retrieval_pipeline_output_mapping: dict[str, str] | None = None,
+    llm: ChatGenerator | None = None,
+    backup_answer_llm: ChatGenerator | None = None,
+    system_prompt: str | None = None,
+    max_agent_steps: int = 20,
+    max_fetched_docs: int = 10,
+    extra_tools: ToolsType | None = None,
+    state_schema: dict[str, Any] | None = None,
+    hooks: dict[HookPoint, list[Hook]] | None = None,
+    raise_on_tool_invocation_failure: bool = False,
+    tool_concurrency_limit: int = 4,
+) -> Agent:
+    """
+    Create the advanced RAG agent.
+
+    The agent answers questions from documents it retrieves out of the document store. Instead of guessing which
+    metadata fields exist, it can inspect the store (fields, values, ranges) and construct a Haystack filter to
+    narrow its retrieval when metadata helps — plain, unfiltered retrieval remains available when it doesn't. The
+    answer cites the retrieved documents.
+
+    The required `retriever` becomes the `search_documents` tool; `document_store` additionally feeds the three
+    metadata inspection tools and must implement the metadata introspection methods (`get_metadata_fields_info`,
+    `get_metadata_field_unique_values`, `get_metadata_field_min_max`).
+
+    :param document_store: The document store the metadata inspection tools and the `fetch_documents_by_filter` tool
+        run against.
+    :param retriever: What retrieves for the `search_documents` tool (required). Either a standalone retriever
+        component following the `TextRetriever` protocol, i.e. its `run` method accepts `query` and `filters`
+        (e.g. `InMemoryBM25Retriever`, or an embedding retriever wrapped in `TextEmbeddingRetriever`), or a custom
+        retrieval `Pipeline` (e.g. embedder -> retriever, or hybrid retrieval) — a pipeline additionally requires
+        `retrieval_pipeline_input_mapping`. It should retrieve by relevance scoring (keyword or embedding-based) —
+        direct, unscored fetching is already covered by the built-in `fetch_documents_by_filter` tool.
+    :param retrieval_pipeline_input_mapping: Required when `retriever` is a `Pipeline`: maps the tool inputs to
+        pipeline input sockets; must have exactly the keys "query" and "filters",
+        e.g. `{"query": ["embedder.text"], "filters": ["retriever.filters"]}`.
+    :param retrieval_pipeline_output_mapping: Optional when `retriever` is a `Pipeline`: maps pipeline output sockets
+        to tool outputs, e.g. `{"retriever.documents": "documents"}`.
+    :param llm: LLM that drives the agent loop. Defaults to `OpenAIResponsesChatGenerator("gpt-5.4")` with low
+        reasoning effort.
+    :param backup_answer_llm: LLM the built-in `BackupAnswerHook` uses to write a best-effort answer when the run
+        is cut off by `max_agent_steps`. Defaults to a separate `OpenAIResponsesChatGenerator("gpt-5.4")` with low
+        reasoning effort.
+    :param system_prompt: Overrides the pre-made system prompt.
+    :param max_agent_steps: Maximum steps for the agent loop. If the loop is cut off by this limit before writing an
+        answer, an `after_run` hook (`BackupAnswerHook`) makes one extra LLM call to produce a best-effort answer from
+        the evidence gathered so far, so `last_message` always carries a text answer.
+    :param max_fetched_docs: Maximum number of documents `fetch_documents_by_filter` shows per fetch. A filter fetch is
+        not bounded by a retriever's `top_k`, so this caps the tool result instead; the scored `search_documents` tool
+        is bounded by the `top_k` configured on your retrieval components.
+    :param extra_tools: Additional tools (or toolsets) for the agent, appended after the built-in document-store
+        toolset and the retrieval tool.
+    :param state_schema: Additional entries merged into the agent's state schema. The built-in `documents` entry
+        (the accumulated retrieved documents) always takes precedence.
+    :param hooks: Additional hooks per hook point, merged with the built-in hooks. For `after_run`, the built-in
+        backup-answer hook runs first, so custom hooks see the final answer.
+    :param raise_on_tool_invocation_failure: If True, a failing tool call raises instead of being returned to the LLM
+        as an error message it can recover from (the default).
+    :param tool_concurrency_limit: Maximum number of tool calls executed in parallel within one agent step.
+    :returns: The advanced RAG `Agent`. Call it with the question as a user message,
+        `agent.run(messages=[ChatMessage.from_user(question)])`; the answer is in `last_message` (a `ChatMessage`) and
+        `documents` carries every document the agent retrieved during the run (deduplicated by id, in first-retrieved
+        order) — the answer cites them by the first 8 characters of their id, e.g. `[doc a1b2c3d4]`. The standard Agent
+        outputs `messages`, `step_count`, `token_usage` and `tool_call_counts` are also returned.
+    """
+    if system_prompt is None:
+        # Only the default system prompt requires the `{% now %}` Jinja tag (and thus `arrow`).
+        arrow_import.check()
+
+    if retriever is None:
+        msg = "`retriever` is required: pass a retriever component or a retrieval `Pipeline`."
+        raise ValueError(msg)
+
+    retrieval_tool: Tool
+    if isinstance(retriever, Pipeline):
+        if retrieval_pipeline_input_mapping is None:
+            msg = "`retrieval_pipeline_input_mapping` is required when `retriever` is a `Pipeline`."
+            raise ValueError(msg)
+        retrieval_tool = _make_retrieval_pipeline_tool(
+            pipeline=retriever,
+            input_mapping=retrieval_pipeline_input_mapping,
+            output_mapping=retrieval_pipeline_output_mapping,
+        )
+    else:
+        if retrieval_pipeline_input_mapping is not None or retrieval_pipeline_output_mapping is not None:
+            msg = "The `retrieval_pipeline_*` arguments are only valid when `retriever` is a `Pipeline`."
+            raise ValueError(msg)
+        retrieval_tool = _make_retriever_tool(retriever=retriever)
+
+    llm = llm or _default_llm("gpt-5.4")
+    backup_answer_llm = backup_answer_llm or _default_llm("gpt-5.4")
+
+    tools: list[Tool | Toolset] = [
+        DocumentStoreToolset(document_store, max_fetched_docs=max_fetched_docs),
+        retrieval_tool,
+    ]
+    if extra_tools is not None:
+        tools.extend([extra_tools] if isinstance(extra_tools, Toolset) else list(extra_tools))
+
+    merged_hooks: dict[HookPoint, list[Hook]] = {"after_run": [BackupAnswerHook(chat_generator=backup_answer_llm)]}
+    for hook_point, point_hooks in (hooks or {}).items():
+        merged_hooks.setdefault(hook_point, []).extend(point_hooks)
+
+    return Agent(
+        chat_generator=llm,
+        system_prompt=system_prompt or prompts.SYSTEM_TEMPLATE,
+        tools=tools,
+        exit_conditions=["text"],
+        max_agent_steps=max_agent_steps,
+        state_schema={**(state_schema or {}), "documents": {"type": list[Document]}},
+        hooks=merged_hooks,
+        raise_on_tool_invocation_failure=raise_on_tool_invocation_failure,
+        tool_concurrency_limit=tool_concurrency_limit,
+    )

haystack_integrations/agent_pack/advanced_rag/hooks.py

@@ -0,0 +1,89 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from haystack import logging
+from haystack.components.agents.state import State
+from haystack.components.generators.chat.types import ChatGenerator
+from haystack.core.serialization import default_from_dict, default_to_dict
+from haystack.dataclasses import ChatMessage, ChatRole
+
+from haystack_integrations.agent_pack.advanced_rag import prompts
+
+logger = logging.getLogger(__name__)
+
+
+class BackupAnswerHook:
+    """
+    Produce a final answer when the agent run ends without one. Runs as an `after_run` hook.
+
+    When the agent exhausts `max_agent_steps` mid-investigation, the run ends on a tool call or tool result instead of
+    an assistant text answer (and only `after_run` hooks run in this situation). This hook detects that case and makes
+    one LLM call over the conversation so far to produce a best-effort answer from the already-gathered evidence.
+    """
+
+    allowed_hook_points = ("after_run",)
+
+    def __init__(self, chat_generator: ChatGenerator) -> None:
+        """
+        Create the hook.
+
+        :param chat_generator: LLM that writes the backup answer from the gathered evidence.
+        """
+        self.chat_generator = chat_generator
+
+    def warm_up(self) -> None:
+        """Prepare the hook's generator for use; called from the Agent's `warm_up`."""
+        if hasattr(self.chat_generator, "warm_up"):
+            self.chat_generator.warm_up()
+
+    def close(self) -> None:
+        """Release the hook's generator resources; called from the Agent's `close`."""
+        if hasattr(self.chat_generator, "close"):
+            self.chat_generator.close()
+
+    def to_dict(self) -> dict:
+        """
+        Serialize the hook to a dictionary.
+
+        :returns: Dictionary with serialized data.
+        """
+        return default_to_dict(self, chat_generator=self.chat_generator)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "BackupAnswerHook":
+        """
+        Deserialize the hook from a dictionary.
+
+        :param data: Dictionary to deserialize from.
+        :returns: Deserialized hook.
+        """
+        return default_from_dict(cls, data)
+
+    @staticmethod
+    def _needs_backup(messages: list[ChatMessage]) -> bool:
+        """
+        Whether the run ended without a final assistant text answer.
+
+        :param messages: The run's messages.
+        :returns: True when the last message is not a plain assistant text reply.
+        """
+        if not messages:
+            return False
+        last = messages[-1]
+        return not (last.is_from(ChatRole.ASSISTANT) and bool(last.text) and not last.tool_calls)
+
+    def run(self, state: State) -> None:
+        """
+        Append a best-effort final answer when the run ended without one (e.g. step exhaustion).
+
+        :param state: The agent run's state.
+        """
+        messages = state.data.get("messages") or []
+        if not self._needs_backup(messages):
+            return
+        logger.info("run ended without a final answer (likely max_agent_steps); writing a backup answer")
+        transcript = [m for m in messages if not m.is_from(ChatRole.SYSTEM)]
+        prompt = [ChatMessage.from_system(prompts.BACKUP_ANSWER_PROMPT), *transcript]
+        reply = self.chat_generator.run(messages=prompt)["replies"][0]
+        state.set("messages", [reply])  # merge_lists handler: appended as the final message

haystack_integrations/agent_pack/advanced_rag/prompts.py

@@ -0,0 +1,91 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <info@deepset.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+_FILTER_SYNTAX = """A filter is either a single condition:
+{"field": "meta.category", "operator": "==", "value": "science"}
+
+or a logical group of conditions:
+{"operator": "AND", "conditions": [
+    {"field": "meta.category", "operator": "==", "value": "science"},
+    {"field": "meta.year", "operator": ">=", "value": 2020}
+]}
+
+Comparison operators: ==, !=, >, >=, <, <=, in, not in ("in" and "not in" take a list as value).
+Logical operators: AND, OR, NOT (NOT takes a conditions list with exactly ONE entry).
+Groups can be nested inside "conditions".
+
+Rules:
+- Always prefix field names with "meta." (field "year" becomes "meta.year").
+- Use ONLY field names returned by list_metadata_fields and exact values as returned by
+  get_metadata_field_values; for numeric or date ranges stay within the bounds from
+  get_metadata_field_range."""
+
+
+FILTER_GRAMMAR = f"""Optional metadata filter to narrow the search, using Haystack filter syntax.
+
+{_FILTER_SYNTAX}
+- Omit this parameter entirely when no metadata filter is needed."""
+
+
+FETCH_FILTER_GRAMMAR = f"""The metadata filter selecting the documents to fetch, using Haystack filter syntax.
+
+{_FILTER_SYNTAX}"""
+
+
+RETRIEVAL_TOOL_DESCRIPTION = (
+    "Search the document store for documents relevant to a query, ranked by relevance. "
+    "Optionally narrow the search with a metadata filter (see the filters parameter). "
+    "Returns the matching documents with their id, metadata and content."
+)
+
+
+FILTER_RETRIEVER_TOOL_DESCRIPTION = (
+    "Fetch documents directly by metadata filter, WITHOUT relevance ranking. Returns the matching "
+    "documents in reading order (up to max_docs per call) plus the total match count; page through "
+    "larger match sets with offset. Use this when you can identify the exact documents you need "
+    "by their metadata (e.g. a specific title, source or file name); use search_documents when "
+    "you need a relevance search."
+)
+
+
+BACKUP_ANSWER_PROMPT = (
+    "You are finalizing an interrupted document-search session. The conversation below ended "
+    "before a final answer was written because the step budget ran out. Using ONLY the "
+    "information already gathered in the conversation (metadata listings and retrieved "
+    "documents), write the best possible answer to the user's original question, referencing "
+    "the documents used. If the gathered information is insufficient to answer, begin with "
+    '"No matching information was found" and briefly state what is missing. Do not call tools.'
+)
+
+
+SYSTEM_TEMPLATE = """{% message role="system" %}
+You answer questions using ONLY documents retrieved from a document store.
+Today's date is {% now 'local', '%d %B %Y' %}.
+
+Process:
+1. Call `list_metadata_fields` FIRST to learn which metadata fields exist and their types.
+2. Before filtering on a field, verify what it contains: use `get_metadata_field_values` for
+   keyword/boolean fields (filter values must match exactly) and `get_metadata_field_range` for
+   numeric or date-like fields.
+3. Call `search_documents` with a focused query and, when metadata can narrow the question, a
+   filter (the filter syntax is described in its `filters` parameter; always prefix field names
+   with "meta."). Not every question needs a filter — omit it when metadata cannot help.
+   When you can identify the exact documents you need by their metadata alone (e.g. a specific
+   title, source or file name), fetch them directly with `fetch_documents_by_filter` instead of
+   searching. The same applies when you need the COMPLETE set of documents matching a filter:
+   fetch with that filter and, if the result reports more matches than shown, continue with the
+   `offset` parameter — do not repeat searches with reworded queries or loosened filters.
+4. If a search returns no documents, relax or drop the filter and retry — at most a couple of
+   attempts. Do not re-inspect metadata you have already seen.
+
+Answering:
+- Answer using only the content of the retrieved documents. Cite the documents you used with the
+  exact bracketed reference shown in the tool results (e.g. [doc a1b2c3d4]), adding
+  distinguishing metadata such as a title or source when it helps the reader.
+- If you cannot find the requested information — the question asks about metadata fields or
+  values that don't exist in the store, or retrieval returns nothing relevant even after
+  relaxing the filter — do NOT guess or answer from general knowledge. Begin your answer with
+  "No matching information was found" and briefly state what you checked (e.g. which field or
+  value does not exist).
+{% endmessage %}"""