PipelineTool

Wraps a Haystack pipeline so an LLM can call it as a tool.

Mandatory init variables	pipeline: The Haystack pipeline to wrap name: The name of the tool description: Description of the tool
API reference	PipelineTool
GitHub link	https://github.com/deepset-ai/haystack/blob/main/haystack/tools/pipeline_tool.py
Package name	haystack-ai

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 works with both Pipeline and AsyncPipeline and can be used in a pipeline with ToolInvoker or directly with the Agent component.

Parameters

• pipeline is mandatory and must be a Pipeline or AsyncPipeline 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 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:

python

from haystack import Document, Pipeline
from haystack.tools import PipelineTool
from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
from haystack.components.rankers.sentence_transformers_similarity 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.components.embedders.sentence_transformers_text_embedder import (
    SentenceTransformersTextEmbedder,
)
from haystack.components.embedders.sentence_transformers_document_embedder import (
    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.components.embedders.sentence_transformers_text_embedder import (
    SentenceTransformersTextEmbedder,
)
from haystack.components.embedders.sentence_transformers_document_embedder import (
    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.",
    ),
]
document_embedder.warm_up()
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)