deepset-ai--haystack/docs-website/docs/tools/pipelinetool.mdx

---
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)
```