chore: import upstream snapshot with attribution

docs-website/docs/tools/pipelinetool.mdx

@@ -0,0 +1,243 @@
+---
+title: "PipelineTool"
+id: pipelinetool
+slug: "/pipelinetool"
+description: "Wraps a Haystack pipeline so an LLM can call it as a tool."
+---
+
+# PipelineTool
+
+Wraps a Haystack pipeline so an LLM can call it as a tool.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Mandatory init variables** | `pipeline`: The Haystack pipeline to wrap  <br /> <br />`name`: The name of the tool  <br /> <br />`description`: Description of the tool |
+| **API reference** | [PipelineTool](/reference/tools-api#pipeline_tool) |
+| **GitHub link**  | https://github.com/deepset-ai/haystack/blob/main/haystack/tools/pipeline_tool.py |
+| **Package name** | `haystack-ai` |
+
+</div>
+
+## Overview
+
+`PipelineTool` lets you wrap a whole Haystack pipeline and expose it as a tool that an LLM can call.
+It replaces the older workflow of first wrapping a pipeline in a `SuperComponent` and then passing that to
+`ComponentTool`.
+
+`PipelineTool` builds the tool parameter schema from the pipeline’s input sockets and uses the underlying components’ docstrings for input descriptions. You can choose which pipeline inputs and outputs to expose with
+`input_mapping` and `output_mapping`. It can be used in a pipeline with `ToolInvoker` or directly with the `Agent` component.
+
+`PipelineTool` also supports async invocation: since every `Pipeline` exposes a native `run_async`, the tool can be awaited (for example, from `Agent.run_async`) without extra configuration. See [Async Tools](tool.mdx#async-tools) for details.
+
+### Parameters
+
+- `pipeline` is mandatory and must be a `Pipeline` instance.
+- `name` is mandatory and specifies the tool name.
+- `description` is mandatory and explains what the tool does.
+- `input_mapping` is optional. It maps tool input names to pipeline input socket paths. If omitted, a default mapping is created from all pipeline inputs.
+- `output_mapping` is optional. It maps pipeline output socket paths to tool output names. If omitted, a default mapping is created from all pipeline outputs.
+- `parameters` is optional and lets you override the auto-generated JSON schema for the tool's inputs.
+- `outputs_to_string` is optional and controls how the pipeline's output is converted to a string for the LLM. By default, the full result dict is serialized. Use `{"source": "key"}` to extract a single output key, or add `"handler"` to apply a custom formatter.
+- `inputs_from_state` is optional and maps agent state keys to pipeline input parameters. Example: `{"repository": "repo"}` passes the state value at `"repository"` as the pipeline's `"repo"` input.
+- `outputs_to_state` is optional and maps pipeline output keys to agent state keys. Example: `{"documents": {"source": "docs"}}` writes the pipeline's `"docs"` output to `"documents"` in state.
+
+## Usage
+
+:::tip
+The recommended way to use `PipelineTool` in Haystack is with the [`Agent`](../pipeline-components/agents-1/agent.mdx) component, which manages the tool call loop for you. The pipeline example below shows the manual approach for cases where you need fine-grained control.
+:::
+
+### Basic Usage
+
+You can create a `PipelineTool` from any existing Haystack pipeline:
+
+The examples on this page use Sentence Transformers embedders that have moved to the `sentence-transformers-haystack` package. Install it to run the examples:
+
+```shell
+pip install sentence-transformers-haystack
+```
+
+```python
+from haystack import Document, Pipeline
+from haystack.tools import PipelineTool
+from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
+from haystack_integrations.components.rankers.sentence_transformers import (
+    SentenceTransformersSimilarityRanker,
+)
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+
+# Create your pipeline
+document_store = InMemoryDocumentStore()
+# Add some example documents
+document_store.write_documents(
+    [
+        Document(
+            content="Nikola Tesla was a Serbian-American inventor and electrical engineer.",
+        ),
+        Document(
+            content="Alternating current (AC) is an electric current which periodically reverses direction.",
+        ),
+        Document(
+            content="Thomas Edison promoted direct current (DC) and competed with AC in the War of Currents.",
+        ),
+    ],
+)
+retrieval_pipeline = Pipeline()
+retrieval_pipeline.add_component(
+    "bm25_retriever",
+    InMemoryBM25Retriever(document_store=document_store),
+)
+retrieval_pipeline.add_component(
+    "ranker",
+    SentenceTransformersSimilarityRanker(model="cross-encoder/ms-marco-MiniLM-L-6-v2"),
+)
+retrieval_pipeline.connect("bm25_retriever.documents", "ranker.documents")
+
+# Wrap the pipeline as a tool
+retrieval_tool = PipelineTool(
+    pipeline=retrieval_pipeline,
+    input_mapping={"query": ["bm25_retriever.query", "ranker.query"]},
+    output_mapping={"ranker.documents": "documents"},
+    name="retrieval_tool",
+    description="Search short articles about Nikola Tesla, AC electricity, and related inventors",
+)
+
+print(retrieval_tool)
+```
+
+### With the Agent Component
+
+```python
+from haystack import Document, Pipeline
+from haystack.tools import PipelineTool
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.sentence_transformers import (
+    SentenceTransformersTextEmbedder,
+    SentenceTransformersDocumentEmbedder,
+)
+from haystack.components.retrievers import InMemoryEmbeddingRetriever
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.agents import Agent
+from haystack.dataclasses import ChatMessage
+
+# Initialize a document store and add some documents
+document_store = InMemoryDocumentStore()
+document_embedder = SentenceTransformersDocumentEmbedder(
+    model="sentence-transformers/all-MiniLM-L6-v2",
+)
+documents = [
+    Document(
+        content="Nikola Tesla was a Serbian-American inventor and electrical engineer.",
+    ),
+    Document(
+        content="He is best known for his contributions to the design of the modern alternating current (AC) electricity supply system.",
+    ),
+]
+docs_with_embeddings = document_embedder.run(documents=documents)["documents"]
+document_store.write_documents(docs_with_embeddings)
+
+# Build a simple retrieval pipeline
+retrieval_pipeline = Pipeline()
+retrieval_pipeline.add_component(
+    "embedder",
+    SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2"),
+)
+retrieval_pipeline.add_component(
+    "retriever",
+    InMemoryEmbeddingRetriever(document_store=document_store),
+)
+retrieval_pipeline.connect("embedder.embedding", "retriever.query_embedding")
+
+# Wrap the pipeline as a tool
+retriever_tool = PipelineTool(
+    pipeline=retrieval_pipeline,
+    input_mapping={"query": ["embedder.text"]},
+    output_mapping={"retriever.documents": "documents"},
+    name="document_retriever",
+    description="For any questions about Nikola Tesla, always use this tool",
+)
+
+agent = Agent(
+    system_prompt="You are an assistant that can use a retrieval tool to find information about Nikola Tesla.",
+    chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
+    tools=[retriever_tool],
+)
+
+result = agent.run([ChatMessage.from_user("Who was Nikola Tesla?")])
+
+print("Answer:")
+print(result["messages"][-1].text)
+```
+
+### In a Pipeline
+
+You can also wire `PipelineTool` into a pipeline manually with `ChatGenerator` and `ToolInvoker` for full control over the tool call loop.
+
+```python
+from haystack import Document, Pipeline
+from haystack.tools import PipelineTool
+from haystack.document_stores.in_memory import InMemoryDocumentStore
+from haystack_integrations.components.embedders.sentence_transformers import (
+    SentenceTransformersTextEmbedder,
+    SentenceTransformersDocumentEmbedder,
+)
+from haystack.components.retrievers import InMemoryEmbeddingRetriever
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.tools.tool_invoker import ToolInvoker
+from haystack.dataclasses import ChatMessage
+
+# Initialize a document store and add some documents
+document_store = InMemoryDocumentStore()
+document_embedder = SentenceTransformersDocumentEmbedder(
+    model="sentence-transformers/all-MiniLM-L6-v2",
+)
+documents = [
+    Document(
+        content="Nikola Tesla was a Serbian-American inventor and electrical engineer.",
+    ),
+    Document(
+        content="He is best known for his contributions to the design of the modern alternating current (AC) electricity supply system.",
+    ),
+]
+docs_with_embeddings = document_embedder.run(documents=documents)["documents"]
+document_store.write_documents(docs_with_embeddings)
+
+# Build a simple retrieval pipeline
+retrieval_pipeline = Pipeline()
+retrieval_pipeline.add_component(
+    "embedder",
+    SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2"),
+)
+retrieval_pipeline.add_component(
+    "retriever",
+    InMemoryEmbeddingRetriever(document_store=document_store),
+)
+retrieval_pipeline.connect("embedder.embedding", "retriever.query_embedding")
+
+# Wrap the pipeline as a tool
+retriever_tool = PipelineTool(
+    pipeline=retrieval_pipeline,
+    input_mapping={"query": ["embedder.text"]},
+    output_mapping={"retriever.documents": "documents"},
+    name="document_retriever",
+    description="For any questions about Nikola Tesla, always use this tool",
+)
+
+pipeline = Pipeline()
+pipeline.add_component(
+    "llm",
+    OpenAIChatGenerator(model="gpt-5.4-nano", tools=[retriever_tool]),
+)
+pipeline.add_component("tool_invoker", ToolInvoker(tools=[retriever_tool]))
+pipeline.connect("llm.replies", "tool_invoker.messages")
+
+message = ChatMessage.from_user(
+    "Use the document retriever tool to find information about Nikola Tesla",
+)
+
+result = pipeline.run({"llm": {"messages": [message]}})
+
+print(result)
+```