chore: import upstream snapshot with attribution

docs-website/versioned_docs/version-2.26/pipeline-components/agents-1/agent.mdx

@@ -0,0 +1,253 @@
+---
+title: "Agent"
+id: agent
+slug: "/agent"
+description: "The `Agent` component is a tool-using agent that interacts with chat-based LLMs and tools to solve complex queries iteratively. It can execute external tools, manage state across multiple LLM calls, and stop execution based on configurable `exit_conditions`."
+---
+
+# Agent
+
+The `Agent` component is a tool-using agent that interacts with chat-based LLMs and tools to solve complex queries iteratively. It can execute external tools, manage state across multiple LLM calls, and stop execution based on configurable `exit_conditions`.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`ChatPromptBuilder`](../builders/chatpromptbuilder.mdx) or user input                     |
+| **Mandatory init variables**           | `chat_generator`: An instance of a Chat Generator that supports tools                  |
+| **Mandatory run variables**            | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx)s                              |
+| **Output variables**                   | `messages`: Chat history with tool and model responses                                 |
+| **API reference**                      | [Agents](/reference/agents-api)                                                               |
+| **GitHub link**                        | https://github.com/deepset-ai/haystack/blob/main/haystack/components/agents/agent.py |
+
+</div>
+
+## Overview
+
+The `Agent` component is a loop-based system that uses a chat-based large language model (LLM) and external tools to solve complex user queries. It works iteratively—calling tools, updating state, and generating prompts—until one of the configurable `exit_conditions` is met.
+
+It can:
+
+- Dynamically select tools based on user input,
+- Maintain and validate runtime state using a schema,
+- Stream token-level outputs from the LLM.
+
+The `Agent` returns a dictionary containing:
+
+- `messages`: the full conversation history,
+- Additional dynamic keys based on `state_schema`.
+
+### Parameters
+
+To initialize the `Agent` component, you need to provide it with an instance of a Chat Generator that supports tools. You can pass a list of [tools](../../tools/tool.mdx) or [`ComponentTool`](../../tools/componenttool.mdx) instances, or wrap them in a [`Toolset`](../../tools/toolset.mdx) to manage them as a group.
+
+You can additionally configure:
+
+- A `system_prompt` for your Agent,
+- A list of `exit_conditions` strings that will cause the agent to return. Can be either:
+  - “text”, which means  that the Agent will exit as soon as the LLM replies only with a text response,
+  - or specific tool names.
+- A `state_schema` for one agent invocation run. It defines extra information – such as documents or context – that tools can read from or write to during execution. You can use this schema to pass parameters that tools can both produce and consume.
+- `streaming_callback` to stream the tokens from the LLM directly in output.
+
+:::info
+For a complete list of available parameters, refer to the [Agents API Documentation](/reference/agents-api).
+:::
+
+### Agents as Tools
+
+You can wrap an `Agent` using [`ComponentTool`](../../tools/componenttool.mdx) to create multi-agent systems where specialized agents act as tools for a coordinator agent.
+
+When wrapping an `Agent` as a `ComponentTool`, use the `outputs_to_string` parameter with `{"source": "last_message"}` to extract only the agent's final response text, rather than the execution trace with tool calls to keep the coordinator agent's context clean and focused.
+
+```python
+## Wrap the agent as a ComponentTool with outputs_to_string
+research_tool = ComponentTool(
+    component=research_agent,  # another agent component
+    name="research_specialist",
+    description="A specialist that can research topics from the knowledge base",
+    outputs_to_string={"source": "last_message"},  ## Extract only the final response
+)
+
+## Create a coordinator agent that uses the specialist
+coordinator_agent = Agent(
+    chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
+    tools=[research_tool],
+    system_prompt="You are a coordinator that delegates research tasks to a specialist.",
+    exit_conditions=["text"],
+)
+
+## Run
+result = coordinator_agent.run(
+    messages=[ChatMessage.from_user("Tell me about Haystack")],
+)
+
+print(result["last_message"].text)
+```
+
+### Streaming
+
+You can stream output as it’s generated. Pass a callback to `streaming_callback`.
+Use the built-in `print_streaming_chunk` to print text tokens and tool events (tool calls and tool results).
+
+```python
+from haystack.components.generators.utils import print_streaming_chunk
+
+## Configure the Agent with a streaming callback
+coordinator_agent = Agent(
+    chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
+    tools=[research_tool],
+    system_prompt="You are a coordinator that delegates research tasks to a specialist.",
+    streaming_callback=print_streaming_chunk,
+)
+```
+
+See our [Streaming Support](../generators/guides-to-generators/choosing-the-right-generator.mdx#streaming-support) docs to learn more how `StreamingChunk` works and how to write a custom callback.
+
+Give preference to `print_streaming_chunk` by default. Write a custom callback only if you need a specific transport (for example, SSE/WebSocket) or custom UI formatting.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.tools.tool import Tool
+from haystack.components.agents import Agent
+
+
+## Tool Function
+def calculate(expression: str) -> dict:
+    try:
+        result = eval(expression, {"__builtins__": {}})
+        return {"result": result}
+    except Exception as e:
+        return {"error": str(e)}
+
+
+## Tool Definition
+calculator_tool = Tool(
+    name="calculator",
+    description="Evaluate basic math expressions.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "expression": {
+                "type": "string",
+                "description": "Math expression to evaluate",
+            },
+        },
+        "required": ["expression"],
+    },
+    function=calculate,
+    outputs_to_state={"calc_result": {"source": "result"}},
+)
+
+## Agent Setup
+agent = Agent(
+    chat_generator=OpenAIChatGenerator(),
+    tools=[calculator_tool],
+    exit_conditions=["calculator"],
+    state_schema={"calc_result": {"type": int}},
+)
+
+## Run the Agent
+response = agent.run(messages=[ChatMessage.from_user("What is 7 * (4 + 2)?")])
+
+## Output
+print(response["messages"])
+print("Calc Result:", response.get("calc_result"))
+```
+
+### In a pipeline
+
+The example pipeline below creates a database assistant using `OpenAIChatGenerator`, `LinkContentFetcher`, and custom database tool. It reads the given URL and processes the page content, then builds a prompt for the AI. The assistant uses this information to write people's names and titles from the given page to the database.
+
+```python
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
+from haystack.components.converters.html import HTMLToDocument
+from haystack.components.fetchers.link_content import LinkContentFetcher
+from haystack.core.pipeline import Pipeline
+from haystack.tools import tool
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from typing import Optional
+from haystack.dataclasses import ChatMessage, Document
+
+document_store = InMemoryDocumentStore()  # create a document store or an SQL database
+
+
+@tool
+def add_database_tool(
+    name: str,
+    surname: str,
+    job_title: Optional[str],
+    other: Optional[str],
+):
+    """Use this tool to add names to the database with information about them"""
+    document_store.write_documents(
+        [
+            Document(
+                content=name + " " + surname + " " + (job_title or ""),
+                meta={"other": other},
+            ),
+        ],
+    )
+    return
+
+
+database_assistant = Agent(
+    chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
+    tools=[add_database_tool],
+    system_prompt="""
+    You are a database assistant.
+    Your task is to extract the names of people mentioned in the given context and add them to a knowledge base,
+    along with additional relevant information about them that can be extracted from the context.
+    Do not use you own knowledge, stay grounded to the given context.
+    Do not ask the user for confirmation.
+    Instead, automatically update the knowledge base and return a brief summary of the people added,
+    including the information stored for each.
+    """,
+    exit_conditions=["text"],
+    max_agent_steps=100,
+    raise_on_tool_invocation_failure=False,
+)
+
+extraction_agent = Pipeline()
+extraction_agent.add_component("fetcher", LinkContentFetcher())
+extraction_agent.add_component("converter", HTMLToDocument())
+extraction_agent.add_component(
+    "builder",
+    ChatPromptBuilder(
+        template=[
+            ChatMessage.from_user("""
+    {% for doc in docs %}
+    {{ doc.content|default|truncate(25000) }}
+    {% endfor %}
+    """),
+        ],
+        required_variables=["docs"],
+    ),
+)
+
+extraction_agent.add_component("database_agent", database_assistant)
+extraction_agent.connect("fetcher.streams", "converter.sources")
+extraction_agent.connect("converter.documents", "builder.docs")
+extraction_agent.connect("builder", "database_agent")
+
+agent_output = extraction_agent.run(
+    {"fetcher": {"urls": ["https://haystack.deepset.ai/release-notes/v2.20.0"]}},
+)
+
+print(agent_output["database_agent"]["messages"][-1].text)
+```
+
+## Additional References
+
+🧑‍🍳 Cookbook: [Build a GitHub Issue Resolver Agent](https://haystack.deepset.ai/cookbook/github_issue_resolver_agent)
+
+📓 Tutorials:
+- [Build a Tool-Calling Agent](https://haystack.deepset.ai/tutorials/43_building_a_tool_calling_agent)
+- [Creating a Multi-Agent System](https://haystack.deepset.ai/tutorials/45_creating_a_multi_agent_system)

docs-website/versioned_docs/version-2.26/pipeline-components/agents-1/human-in-the-loop.mdx

@@ -0,0 +1,251 @@
+---
+title: "Human in the Loop"
+id: human-in-the-loop
+slug: "/human-in-the-loop"
+description: "Human-in-the-loop allows you to intercept agent tool calls before execution, letting a human confirm, reject, or modify the tool parameters."
+---
+
+# Human in the Loop
+
+Human-in-the-loop (HITL) lets you intercept an agent's tool calls before they are executed.
+A human can **confirm**, **reject**, or **modify** the parameters of each tool call in real time.
+This is useful for high-stakes operations - such as sending emails, modifying databases, or making API calls - where you want a human to review the action first.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Configured on**       | The [`Agent`](./agent.mdx) component via `confirmation_strategies`                               |
+| **Key classes**         | `BlockingConfirmationStrategy`, `AlwaysAskPolicy`, `AskOncePolicy`, `NeverAskPolicy`, `RichConsoleUI`, `SimpleConsoleUI` |
+| **Import path**         | `haystack.human_in_the_loop`                                                                     |
+| **GitHub link**         | https://github.com/deepset-ai/haystack/blob/main/haystack/human_in_the_loop/                    |
+
+</div>
+
+## Overview
+
+The HITL system is composed of three layers:
+
+- **Strategy** - decides what to do when a tool is about to be called. The built-in `BlockingConfirmationStrategy` pauses execution and asks a human.
+- **Policy** - decides *when* to ask. Built-in policies: `AlwaysAskPolicy`, `NeverAskPolicy`, `AskOncePolicy`.
+- **UI** - the interface used to ask the human. Built-in UIs: `RichConsoleUI` (requires `rich`) and `SimpleConsoleUI` (stdlib only).
+
+When the agent is about to invoke a tool, the strategy checks the policy.
+If the policy says to ask, the UI prompts the human with the tool name, description, and parameters. The human can:
+
+- **Confirm** (`y`) - execute as-is
+- **Reject** (`n`) - skip execution and feed rejection feedback back to the LLM
+- **Modify** (`m`) - edit the parameters before execution
+
+The agent then continues with the human's decision.
+
+## Usage
+
+### Basic setup
+
+```python
+from typing import Annotated
+from haystack.components.agents import Agent
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+from haystack.human_in_the_loop import (
+    AlwaysAskPolicy,
+    BlockingConfirmationStrategy,
+    SimpleConsoleUI,
+)
+from haystack.tools import tool
+
+
+@tool
+def send_email(
+    to: Annotated[str, "The recipient email address"],
+    subject: Annotated[str, "The email subject line"],
+    body: Annotated[str, "The email body"],
+) -> str:
+    """Send an email to a recipient."""
+    return f"Email sent to {to}."
+
+
+strategy = BlockingConfirmationStrategy(
+    confirmation_policy=AlwaysAskPolicy(),
+    confirmation_ui=SimpleConsoleUI(),
+)
+
+agent = Agent(
+    chat_generator=OpenAIChatGenerator(model="gpt-5.4-mini"),
+    tools=[send_email],
+    confirmation_strategies={"send_email": strategy},
+)
+
+result = agent.run(
+    messages=[ChatMessage.from_user("Send a welcome email to alice@example.com")],
+)
+```
+
+When the agent calls `send_email`, the terminal will pause and show:
+
+```
+--- Tool Execution Request ---
+Tool: send_email
+Description: Send an email to a recipient.
+Arguments:
+  to: alice@example.com
+  subject: Welcome!
+  body: Hi Alice, welcome aboard!
+------------------------------
+Confirm execution? (y=confirm / n=reject / m=modify):
+```
+
+### Using RichConsoleUI
+
+`RichConsoleUI` provides a styled terminal prompt using the [`rich`](https://github.com/Textualize/rich) library:
+
+```shell
+pip install rich
+```
+
+```python
+from haystack.human_in_the_loop import RichConsoleUI
+
+strategy = BlockingConfirmationStrategy(
+    confirmation_policy=AlwaysAskPolicy(),
+    confirmation_ui=RichConsoleUI(),
+)
+```
+
+### Applying strategies to multiple tools
+
+You can configure different strategies per tool, or share one strategy across a group of tools using a tuple key:
+
+```python
+@tool
+def delete_record(record_id: Annotated[str, "The ID of the record to delete"]) -> str:
+    """Delete a record from the database."""
+    return f"Record {record_id} deleted."
+
+
+@tool
+def update_record(
+    record_id: Annotated[str, "The ID of the record to update"],
+    data: Annotated[str, "The new data as a JSON string"],
+) -> str:
+    """Update a record in the database."""
+    return f"Record {record_id} updated."
+
+
+@tool
+def search(query: Annotated[str, "The search query"]) -> str:
+    """Search the knowledge base."""
+    return f"Results for: {query}"
+
+
+ask_strategy = BlockingConfirmationStrategy(
+    confirmation_policy=AlwaysAskPolicy(),
+    confirmation_ui=SimpleConsoleUI(),
+)
+
+agent = Agent(
+    chat_generator=OpenAIChatGenerator(model="gpt-5.4-mini"),
+    tools=[send_email, delete_record, update_record, search],
+    confirmation_strategies={
+        # Share one strategy across multiple sensitive tools using a tuple key
+        ("send_email", "delete_record", "update_record"): ask_strategy,
+        # search has no strategy - always executes without asking
+    },
+)
+```
+
+## Policies
+
+Policies control *when* the human is asked.
+
+| Policy | Behavior |
+| --- | --- |
+| `AlwaysAskPolicy` | Ask every time the tool is called |
+| `NeverAskPolicy` | Never ask - always proceed (useful for toggling HITL off without removing the strategy) |
+| `AskOncePolicy` | Ask once per unique `(tool_name, parameters)` combination. Remembers confirmed calls and skips asking on repeats. |
+
+### Custom policy
+
+You can implement your own policy by subclassing `ConfirmationPolicy` from `haystack.human_in_the_loop.types`:
+
+```python
+from haystack.human_in_the_loop.types import ConfirmationPolicy, ConfirmationUIResult
+from typing import Any
+
+
+class AskForSensitiveParamsPolicy(ConfirmationPolicy):
+    """Only ask when the 'to' parameter looks like an external email domain."""
+
+    def should_ask(
+        self,
+        tool_name: str,
+        tool_description: str,
+        tool_params: dict[str, Any],
+    ) -> bool:
+        to = tool_params.get("to", "")
+        return not to.endswith("@mycompany.com")
+```
+
+## Dataclasses
+
+### `ConfirmationUIResult`
+
+Returned by the UI after the human responds.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `action` | `str` | `"confirm"`, `"reject"`, or `"modify"` |
+| `feedback` | `str \| None` | Optional free-text feedback from the human |
+| `new_tool_params` | `dict \| None` | Replacement parameters when action is `"modify"` |
+
+### `ToolExecutionDecision`
+
+Returned by the strategy to the agent.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `tool_name` | `str` | Name of the tool |
+| `execute` | `bool` | Whether to execute the tool |
+| `tool_call_id` | `str \| None` | ID of the tool call |
+| `feedback` | `str \| None` | Feedback message passed back to the LLM on rejection or modification |
+| `final_tool_params` | `dict \| None` | Final parameters to use for execution |
+
+## Example: HITL with Hayhooks and Open WebUI
+
+The [hitl-hayhooks-redis-openwebui](https://github.com/deepset-ai/hitl-hayhooks-redis-openwebui) repository shows a full production-style HITL setup using a Haystack Agent served via [Hayhooks](https://github.com/deepset-ai/hayhooks) with approval dialogs rendered in [Open WebUI](https://github.com/open-webui/open-webui).
+
+The key pattern it demonstrates is a custom `RedisConfirmationStrategy` that uses `confirmation_strategy_context` to pass per-request resources - a Redis client and an async event queue - into the strategy at runtime:
+
+- When a tool call is about to execute, the strategy emits a `tool_call_start` SSE event and blocks on `Redis BLPOP` waiting for an approval decision.
+- The Open WebUI Pipe function receives the SSE event, shows the user a confirmation dialog, then writes `approved` or `rejected` to Redis via `LPUSH`.
+- Once Redis unblocks, the strategy returns a `ToolExecutionDecision` and the agent continues.
+
+This is a good reference if you need non-blocking HITL in a web or server environment where `SimpleConsoleUI` and `RichConsoleUI` are not suitable.
+
+## Custom UI
+
+Implement `ConfirmationUI` from `haystack.human_in_the_loop.types` to build your own interface - for example, a web-based approval queue:
+
+```python
+from haystack.human_in_the_loop.types import ConfirmationUI
+from haystack.human_in_the_loop import ConfirmationUIResult
+from typing import Any
+
+
+class WebhookApprovalUI(ConfirmationUI):
+    """Sends a webhook and waits for an async approval response."""
+
+    def get_user_confirmation(
+        self,
+        tool_name: str,
+        tool_description: str,
+        tool_params: dict[str, Any],
+    ) -> ConfirmationUIResult:
+        # Send approval request to your system and wait for response
+        response = send_approval_request_and_wait(tool_name, tool_params)
+        return ConfirmationUIResult(
+            action=response["action"],
+            feedback=response.get("feedback"),
+        )
+```