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

[julian-risch]

Related Issues

• Part of https://github.com/deepset-ai/haystack-private/issues/381

Proposed Changes:

A. Replace removed ToolInvoker with Agent (or manual Tool.invoke):

• docs-website/docs/tools/tool.mdx, toolset.mdx, mcptoolset.mdx, mcptool.mdx, componenttool.mdx, pipelinetool.mdx: ToolInvoker-based examples replaced with Agent-based examples. After review: tool.mdx drops the manual tool-calling sections entirely (the Passing Tools to Agent section is enough; the usage tip links to the Function Calling guide for the manual loop), and componenttool.mdx drops the In a Pipeline section that only duplicated the Agent example.
• docs-website/docs/pipeline-components/generators/guides-to-generators/function-calling.mdx: reframed as an explanation of what happens under the hood when an Agent runs tools; the "Actually Invoke the Tool" step uses Tool.invoke + ChatMessage.from_tool, and the page closes with the Agent doing the same loop automatically.
• docs-website/docs/pipeline-components/generators/googlegenaichatgenerator.mdx (also removes the broken https://www.notion.so/docs/toolinvoker link), vertexaigeminichatgenerator.mdx, googleaigeminichatgenerator.mdx: broken function-calling examples (undefined variables, removed ChatMessage.from_function) rewritten against the current API, each followed by a new With an Agent usage section. Also fixes an undefined-variable typo in the Vertex AI pipeline example.
• docs-website/docs/pipeline-components/generators/aimllapichatgenerator.mdx, cometapichatgenerator.mdx: tool-calling examples now run the Agent standalone under a With an Agent section (no unnecessary Pipeline wrapper).
• docs-website/docs/pipeline-components/agents-1/agent.mdx, state.mdx, guides-to-generators/choosing-the-right-generator.mdx: prose mentions of ToolInvoker recast as the Agent's built-in tool execution (streaming forwarding via tool_streaming_callback_passthrough).
• docs-website/docs/overview/migrating-from-langgraphlangchain-to-haystack.mdx: the Agentic Flows walkthrough is restructured into 4 steps so every step shows real Haystack code — the old Steps 3–6 (comment-only Haystack columns) are merged into one "Assemble the agent" step comparing Agent(...) with LangGraph's node/edge/StateGraph assembly. Step 2 retitled to "Initialize the LLM" since tools are no longer passed to the ChatGenerator. Removed AgentBreakpoint/ToolBreakpoint/Snapshot class names from the comparison table (only Breakpoint/PipelineSnapshot exist).
• docs-website/docs/overview/migration.mdx: completely revamped to cover the 2.x → 3.0 migration (based on MIGRATION.md): removed/renamed components (legacy Generators, ToolInvoker, TransformersSimilarityRanker, DALLEImageGenerator), the moved-to-integration-packages import table, pipeline changes (AsyncPipeline merge, deserialization allowlist), the required_variables default, Agent breaking changes, and behavior changes (Document IDs, logging, tracing, warm-up, Answer serialization) — each with before/after snippets and links to the detail pages. The 1.x → 2.x content is replaced by a pointer to its preserved copy on the v2.31.x branch; the FAQ link text is updated accordingly.

B. required_variables new default — PromptBuilder/ChatPromptBuilder now default to "*" and None warns.

• docs-website/docs/pipeline-components/builders/promptbuilder.mdx, chatpromptbuilder.mdx: corrected the "all optional by default" prose, updated examples, and fixed the serialized YAML default (required_variables: '*').

C. Generator split framing — legacy non-chat Generators were removed in 3.0, core ships ChatGenerators, and ChatGenerators accept a plain string.

• docs-website/docs/pipeline-components/generators/guides-to-generators/choosing-the-right-generator.mdx: the historical "Generators vs ChatGenerators" section is removed after review; the ChatGenerator description (string or Chat Messages input, function calling, multimodal) is folded into the intro.
• docs-website/docs/concepts/concepts-overview.mdx: stale "two types of Generators" framing reframed around ChatGenerators; the note about the 3.0 removal of legacy Generators is dropped after review (not relevant for new users; upgraders have the migration page).

D. Logging — describe the v3 scoped structlog behavior.

• docs-website/docs/development/logging.mdx: the formatting handler is installed only for the haystack/haystack_integrations/haystack_experimental namespaces; added configure_logging(logger_name="") (process-wide legacy behavior) and configure_logging(propagate=False) (avoid duplicate lines); fixed the env var name to HAYSTACK_LOGGING_IGNORE_STRUCTLOG.

E. OpenTelemetry tracing — OpenTelemetryTracer already lives in opentelemetry-haystack.

• docs-website/docs/development/tracing/opentelemetry.mdx: admonition no longer says "deprecated in core / moving"; it states the tracer is provided by the integration and not auto-enabled.

F. Pipeline concurrency — concurrency_limit is not an __init__ parameter.

• docs-website/docs/concepts/pipelines.mdx: corrected to a per-call argument of run_async/run_async_generator/stream; noted that sync run executes sequentially.

How did you test it?

• npm run build in docs-website passes (onBrokenLinks/onBrokenAnchors/onBrokenMarkdownLinks are all set to throw, so all links and anchors are validated).
• Pre-commit hooks pass, including ruff-format-docs over the code blocks.

Notes for the reviewer

• All review comments from the first round are addressed in the latest commit, including the two larger asks: the LangGraph Agentic Flows restructure and the full v2 → v3 revamp of migration.mdx.
• Deleting docs-website/docs/pipeline-components/tools/toolinvoker.mdx and the sidebars.js entry is intentionally left to a separate PR, so the remaining links to that page were removed here but the page itself is untouched.
• Remaining ToolInvoker mentions in tools/ready-made-tools/*, overview/platform-components.mdx, and concepts/pipelines/pipeline-breakpoints.mdx are out of scope for this PR and tracked separately.

Checklist

• I have read the contributors guidelines and the code of conduct.
• I have updated the related issue with new insights and changes.
• I have added unit tests and updated the docstrings. (N/A — docs-only)
• I've used one of the conventional commit types for my PR title: docs:.
• I have documented my code. (N/A — docs-only)
• I have added a release note file, following the contributors guidelines. (N/A — docs-only PRs don't need release notes)
• I have run pre-commit hooks and fixed any issue.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
haystack-docs	Ready	Preview, Comment	Jul 13, 2026 7:48am

[bogdankostic]

Looks mostly good, added some comments on stuff that I'm unsure about.

[bogdankostic]

Looks good