docs: 3.0 doc updates (ToolInvoker/Generator removal, required_variables default, logging/tracing) (#11956)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: julian-risch

docs-website/docs/concepts/concepts-overview.mdx

@@ -19,10 +19,7 @@ Working on this level with Haystack components is a hands-on approach. Component
 
 #### Generators
 
-[Generators](../pipeline-components/generators.mdx) are responsible for generating text responses after you give them a prompt. They are specific for each LLM technology (OpenAI, Cohere, local models, and others). There are two types of Generators: chat and non-chat:
-
-- The chat ones enable chat completion and are designed for conversational contexts. It expects a list of messages to interact with the user.
-- The non-chat Generators use LLMs for simpler text generation (for example, translating or summarizing text).
+[Generators](../pipeline-components/generators.mdx) are responsible for generating text responses after you give them a prompt. They are specific for each LLM technology (OpenAI, Cohere, local models, and others). Haystack core ships ChatGenerators: they enable chat completion and are designed for conversational contexts, expecting a list of Chat Messages to interact with the user. For simpler text generation (for example, translating or summarizing text), they also accept a plain string prompt.
 
 Read more about various Generators in our [guides](../pipeline-components/generators/guides-to-generators/choosing-the-right-generator.mdx).
 

docs-website/docs/concepts/pipelines.mdx

@@ -44,7 +44,7 @@ See [Pipeline Loops](pipelines/pipeline-loops.mdx) for a deeper explanation of h
 
 ### Async Execution and Streaming
 
-Pipelines execute components in parallel when their dependencies allow it. This improves performance in complex pipelines with independent operations. For example, a pipeline can run multiple Retrievers or LLM calls simultaneously, execute independent pipeline branches in parallel, and efficiently handle I/O-bound operations that would otherwise cause delays. You can cap the number of components running at the same time with the `concurrency_limit` init parameter.
+When run asynchronously, pipelines execute components in parallel when their dependencies allow it. This improves performance in complex pipelines with independent operations. For example, a pipeline can run multiple Retrievers or LLM calls simultaneously, execute independent pipeline branches in parallel, and efficiently handle I/O-bound operations that would otherwise cause delays. You can cap the number of components running at the same time with the `concurrency_limit` argument of the async run methods (`run_async`, `run_async_generator`, and `stream`). The synchronous `run` method executes components sequentially.
 
 Besides the blocking `run` method, every pipeline offers three ways to run asynchronously:
 

docs-website/docs/development/logging.mdx

@@ -74,7 +74,24 @@ Here’s what the resulting log would look like when a pipeline is run:
 
 Haystack leverages the [structlog library](https://www.structlog.org/en/stable/) to provide structured key-value logs. This provides additional metadata with each log message and is especially useful if you archive your logs with tools like [ELK](https://www.elastic.co/de/elastic-stack), [Grafana](https://grafana.com/oss/agent/?plcmt=footer), or [Datadog](https://www.datadoghq.com/).
 
-If Haystack detects a [structlog installation](https://www.structlog.org/en/stable/) on your system, it will automatically switch to structlog for logging.
+If Haystack detects a [structlog installation](https://www.structlog.org/en/stable/) on your system, it installs a structlog-based formatting handler on import - but only for Haystack's own logger namespaces (`haystack`, `haystack_integrations`, and `haystack_experimental`). The root logger and the process-global structlog configuration are left untouched, so importing Haystack does not change how your application or other libraries log.
+
+### Scoping and Duplicate Log Lines
+
+You can adjust this behavior with an explicit `configure_logging` call:
+
+- `configure_logging(logger_name="")` attaches the formatting handler to the root logger instead, restoring the legacy behavior of formatting every log record in the process.
+- `configure_logging(propagate=False)` stops Haystack's log records from propagating to ancestor loggers. Use this to avoid duplicate log lines when your application also configures a handler on the root logger.
+
+```python
+from haystack.logging import configure_logging
+
+# Format all log records in the process (legacy behavior)
+configure_logging(logger_name="")
+
+# Avoid duplicate log lines when the host app configures the root logger
+configure_logging(propagate=False)
+```
 
 ### Console Rendering
 
@@ -102,4 +119,4 @@ We recommend JSON logging when deploying Haystack to production. Haystack will a
 
 ### Disabling Structured Logging
 
-To disable structured logging despite an existing installation of structlog, set the environment variable `HAYSTACK_LOGGING_IGNORE_STRUCTLOG_ENV_VAR` to `true` when running Haystack.
+To disable structured logging despite an existing installation of structlog, set the environment variable `HAYSTACK_LOGGING_IGNORE_STRUCTLOG` to `true` when running Haystack.

docs-website/docs/development/tracing/opentelemetry.mdx

@@ -28,8 +28,8 @@ Learn how to trace your Haystack pipelines with OpenTelemetry.
 
 [OpenTelemetry](https://opentelemetry.io/) is an open-source observability framework for collecting traces, metrics, and logs. Haystack integrates with OpenTelemetry, so you can send traces of your pipeline runs to any OpenTelemetry-compatible backend.
 
-:::info[Moving to an integration]
-`OpenTelemetryTracer` is deprecated in Haystack core and is moving to the `opentelemetry-haystack` package. Starting with Haystack 3.0, OpenTelemetry tracing is no longer auto-enabled when `opentelemetry-sdk` is installed. Install the integration and either enable the `OpenTelemetryTracer` directly or add the `OpenTelemetryConnector` component to your pipeline.
+:::info[Provided by an integration]
+`OpenTelemetryTracer` lives in the `opentelemetry-haystack` package and is not part of Haystack core. Since Haystack 3.0, OpenTelemetry tracing is no longer auto-enabled when `opentelemetry-sdk` is installed. Install the integration and either enable the `OpenTelemetryTracer` directly or add the `OpenTelemetryConnector` component to your pipeline.
 :::
 
 ## Installation

docs-website/docs/overview/faq.mdx

@@ -41,4 +41,4 @@ The ZIP file contains documentation for all minor releases from version 1.0 to 1
 
 To download documentation for a specific release, replace the version number in the following URL: `https://core-engineering.s3.eu-central-1.amazonaws.com/public/docs/v1.26.zip`.
 
-Learn how to migrate to Haystack version 2.x with our [migration guide](migration.mdx).
+Learn how to migrate to Haystack 3.x with our [migration guide](migration.mdx).

docs-website/docs/overview/migrating-from-langgraphlangchain-to-haystack.mdx

@@ -147,20 +147,19 @@ def divide(a: int, b: int) -> float:
   </div>
 </div>
 
-**Step 2: Initialize the LLM with tools**
+**Step 2: Initialize the LLM**
 
-Both frameworks connect tools to the LLM, but with different APIs. In Haystack, tools are passed directly to the `ChatGenerator` component during initialization. In LangGraph, you first initialize the model, then bind tools using `.bind_tools()` to create a tool-enabled LLM instance.
+The frameworks connect tools to the LLM differently. In Haystack, you only initialize the `ChatGenerator` component here: the tools are passed to the `Agent` in Step 3, which forwards them to the LLM. In LangGraph, you first initialize the model, then bind tools using `.bind_tools()` to create a tool-enabled LLM instance.
 
 <div className="code-comparison">
   <div className="code-comparison__column">
     <CodeBlock language="python" title="Haystack">{`from haystack_integrations.components.generators.anthropic import AnthropicChatGenerator
 
-# Augment the LLM with tools
+# Initialize the LLM; the tools are passed to the Agent in Step 3
 tools = [add, multiply, divide]
 model = AnthropicChatGenerator(
     model="claude-sonnet-4-5-20250929",
     generation_kwargs={"temperature": 0},
-    tools=tools,
 )`}</CodeBlock>
   </div>
   <div className="code-comparison__column">
@@ -177,45 +176,32 @@ llm_with_tools = model.bind_tools(tools)`}</CodeBlock>
   </div>
 </div>
 
-**Step 3: Set up message handling and LLM invocation**
+**Step 3: Assemble the agent**
 
-This is where the frameworks diverge more significantly. In Haystack you'll use a custom component (`MessageCollector`) to accumulate conversation history across the agentic loop. LangGraph instead defines a node function (`llm_call`) that operates on `MessagesState` - a built-in state container that automatically manages message history.
+This is where the frameworks diverge most. In Haystack, you create the `Agent` component from the chat generator and tools - the agentic loop is built in. The Agent accumulates the conversation (LLM replies and tool results) internally, executes the tool calls prepared by the LLM, and iterates until an exit condition is met. The default `exit_conditions=["text"]` stops the loop as soon as the LLM replies without tool calls; tool names can also be used to exit after a specific tool runs.
+
+In LangGraph, you build the loop explicitly: a node function (`llm_call`) that invokes the LLM on the accumulated `MessagesState`, a node function (`tool_node`) that executes tool calls and wraps the results in `ToolMessage` objects, and a conditional edge function (`should_continue`) that decides whether to continue the loop or finish. You then wire nodes and edges together in a `StateGraph` and compile the graph into an executable agent.
 
 <div className="code-comparison">
   <div className="code-comparison__column">
-    <CodeBlock language="python" title="Haystack">{`from typing import Any, Dict, List
-
-from haystack import component
-from haystack.core.component.types import Variadic
-from haystack.dataclasses import ChatMessage
-
-# Components
-
-# Custom component to temporarily store the messages
-@component()
-class MessageCollector:
-    def __init__(self):
-        self._messages = []
+    <CodeBlock language="python" title="Haystack">{`from haystack.components.agents import Agent
 
-    @component.output_types(messages=List[ChatMessage])
-    def run(self, messages: Variadic[List[ChatMessage]]) -> Dict[str, Any]:
-        self._messages.extend([msg for inner in messages for msg in inner])
-        return {"messages": self._messages}
-
-    def clear(self):
-        self._messages = []
-
-message_collector = MessageCollector()`}</CodeBlock>
+# Create the agent - the agentic loop (LLM calls,
+# tool execution, iteration) is built in
+agent = Agent(
+    chat_generator=model,
+    tools=tools,
+    system_prompt="You are a helpful assistant tasked with performing arithmetic on a set of inputs.",
+    exit_conditions=["text"],  # default
+)`}</CodeBlock>
   </div>
   <div className="code-comparison__column">
-    <CodeBlock language="python" title="LangGraph + LangChain">{`from langgraph.graph import MessagesState
+    <CodeBlock language="python" title="LangGraph + LangChain">{`from typing import Literal
+from langgraph.graph import MessagesState, StateGraph, START, END
 from langchain.messages import SystemMessage, ToolMessage
-from typing import Literal
 
-# Nodes
+# Node: the LLM decides whether to call a tool or not
 def llm_call(state: MessagesState):
-    # LLM decides whether to call a tool or not
-
     return {
         "messages": [
             llm_with_tools.invoke(
@@ -227,103 +213,24 @@ def llm_call(state: MessagesState):
                 + state["messages"]
             )
         ]
-    }`}</CodeBlock>
-  </div>
-</div>
-
-**Step 4: Execute tool calls**
-
-When the LLM decides to use a tool, it must be invoked and its result returned. Haystack provides a built-in `ToolInvoker` component that handles this automatically. LangGraph requires you to define a custom node function that iterates over tool calls, invokes each tool, and wraps the results in `ToolMessage` objects.
-
-<div className="code-comparison">
-  <div className="code-comparison__column">
-    <CodeBlock language="python" title="Haystack">{`from haystack.components.tools import ToolInvoker
+    }
 
-# Tool invoker component to execute a tool call
-tool_invoker = ToolInvoker(tools=tools)`}</CodeBlock>
-  </div>
-  <div className="code-comparison__column">
-    <CodeBlock language="python" title="LangGraph + LangChain">{`def tool_node(state: dict):
-    # Performs the tool call
+# Node: performs the tool calls
+def tool_node(state: dict):
     result = []
     for tool_call in state["messages"][-1].tool_calls:
         tool = tools_by_name[tool_call["name"]]
         observation = tool.invoke(tool_call["args"])
         result.append(ToolMessage(content=observation, tool_call_id=tool_call["id"]))
-    return {"messages": result}`}</CodeBlock>
-  </div>
-</div>
-
-**Step 5: Implement conditional routing logic**
-
-After the LLM responds, we need to decide whether to continue the loop (if tools were called) or finish (if the LLM provided a final answer). Haystack uses a `ConditionalRouter` component with declarative route conditions written in Jinja2 templates. LangGraph uses a conditional edge function (`should_continue`) that inspects the state and returns the next node or `END`.
+    return {"messages": result}
 
-<div className="code-comparison">
-  <div className="code-comparison__column">
-    <CodeBlock language="python" title="Haystack">{`from haystack.components.routers import ConditionalRouter
-
-# ConditionalRouter component to route to the tool invoker or end user based upon whether the LLM made a tool call
-routes = [
-    {
-        "condition": "{{replies[0].tool_calls | length > 0}}",
-        "output": "{{replies}}",
-        "output_name": "there_are_tool_calls",
-        "output_type": List[ChatMessage],
-    },
-    {
-        "condition": "{{replies[0].tool_calls | length == 0}}",
-        "output": "{{replies}}",
-        "output_name": "final_replies",
-        "output_type": List[ChatMessage],
-    },
-]
-router = ConditionalRouter(routes, unsafe=True)`}</CodeBlock>
-  </div>
-  <div className="code-comparison__column">
-    <CodeBlock language="python" title="LangGraph + LangChain">{`from langgraph.graph import END
-
-# Conditional edge function to route to the tool node or end based upon whether the LLM made a tool call
+# Conditional edge: route to the tool node or end
+# based upon whether the LLM made a tool call
 def should_continue(state: MessagesState) -> Literal["tool_node", END]:
-    # Decide if we should continue the loop or stop based upon whether the LLM made a tool call
-
-    messages = state["messages"]
-    last_message = messages[-1]
-
-    # If the LLM makes a tool call, then perform an action
+    last_message = state["messages"][-1]
     if last_message.tool_calls:
         return "tool_node"
-
-    # Otherwise, we stop (reply to the user)
-    return END`}</CodeBlock>
-  </div>
-</div>
-
-**Step 6: Assemble the workflow**
-
-This is where you wire together all the components or nodes. Haystack uses a `Pipeline` where you explicitly add components and connect their inputs and outputs, creating a directed graph with loops. LangGraph uses a `StateGraph` where you add nodes and edges, then compile the graph into an executable agent. Both approaches achieve the same agentic loop, but with different levels of explicitness.
-
-<div className="code-comparison">
-  <div className="code-comparison__column">
-    <CodeBlock language="python" title="Haystack">{`from haystack import Pipeline
-
-# Build pipeline
-agent_pipe = Pipeline()
-
-# Add components
-agent_pipe.add_component("message_collector", message_collector)
-agent_pipe.add_component("llm", model)
-agent_pipe.add_component("router", router)
-agent_pipe.add_component("tool_invoker", tool_invoker)
-
-# Add connections
-agent_pipe.connect("message_collector", "llm.messages")
-agent_pipe.connect("llm.replies", "router")
-agent_pipe.connect("router.there_are_tool_calls", "tool_invoker") # If there are tool calls, send them to the ToolInvoker
-agent_pipe.connect("router.there_are_tool_calls", "message_collector")
-agent_pipe.connect("tool_invoker.tool_messages", "message_collector")`}</CodeBlock>
-  </div>
-  <div className="code-comparison__column">
-    <CodeBlock language="python" title="LangGraph + LangChain">{`from langgraph.graph import StateGraph, START
+    return END
 
 # Build workflow
 agent_builder = StateGraph(MessagesState)
@@ -346,19 +253,19 @@ agent = agent_builder.compile()`}</CodeBlock>
   </div>
 </div>
 
-**Step 7: Run the agent**
+**Step 4: Run the agent**
 
-Finally, we execute the agent with a user message. Haystack calls `.run()` on the pipeline with initial messages, while LangGraph calls `.invoke()` on the compiled agent. Both return the conversation history.
+Finally, we execute the agent with a user message. Haystack calls `.run()` on the Agent with initial messages, while LangGraph calls `.invoke()` on the compiled agent. Both return the conversation history.
 
 <div className="code-comparison">
   <div className="code-comparison__column">
-    <CodeBlock language="python" title="Haystack">{`# Run the pipeline
-messages = [
-    ChatMessage.from_system(text="You are a helpful assistant tasked with performing arithmetic on a set of inputs."),
+    <CodeBlock language="python" title="Haystack">{`from haystack.dataclasses import ChatMessage
+
+# Run the agent
+result = agent.run(messages=[
     ChatMessage.from_user(text="Add 3 and 4.")
-]
-result = agent_pipe.run({"messages": messages})
-result`}</CodeBlock>
+])
+print(result["last_message"].text)`}</CodeBlock>
   </div>
   <div className="code-comparison__column">
     <CodeBlock language="python" title="LangGraph + LangChain">{`from langchain.messages import HumanMessage
@@ -375,7 +282,7 @@ for m in messages["messages"]:
 
 ### Creating Agents
 
-The [Agentic Flows](#agentic-flows-with-haystack-vs-langgraph) walkthrough above showed how to assemble an agent loop manually from pipeline primitives. Haystack also provides a high-level `Agent` class that wraps the full loop  -  LLM calls, tool invocation, and iteration  -  into a single component. LangGraph offers an equivalent shortcut through `create_react_agent` in `langgraph.prebuilt`. Both produce a ReAct-style agent that handles tool calling and multi-step reasoning automatically.
+The [Agentic Flows](#agentic-flows-with-haystack-vs-langgraph) walkthrough above stepped through the agent loop piece by piece. In Haystack, the high-level `Agent` class wraps the full loop  -  LLM calls, tool invocation, and iteration  -  into a single component. LangGraph offers an equivalent shortcut through `create_react_agent` in `langgraph.prebuilt`. Both produce a ReAct-style agent that handles tool calling and multi-step reasoning automatically. Here are the complete examples side by side:
 
 <div className="code-comparison">
   <div className="code-comparison__column">