Haystack is deepset’s framework for building AI applications as connected pieces: you plug a retriever into a generator and a router, and get a system you can test, swap and deploy to production. It is an open-source Python library that treats every block (search, LLM, decision) as a component with typed inputs and outputs. In this guide you will see what a pipeline is, how the Agent component works with tools, and how to combine RAG and agents in the same system. The same explanation is available in Spanish.

Key takeaways

  • Haystack is a Python framework by deepset, Apache 2.0 licensed, for building AI applications as pipelines of connected components.
  • You install it with pip install haystack-ai; version 2.31.0 shipped on 8 July 2026 and requires Python 3.10 or later.
  • Version 2.0, a full rewrite released on 11 March 2024, introduced typed connections and pipelines with cycles, which makes an agent’s loops possible.
  • The Agent component runs a loop: it calls the model, runs the tools it requests and repeats until an exit condition, with a default limit of 100 steps.
  • It is a mature project: the deepset-ai/haystack repository sits near 25,900 stars and dates back to 2019, and it serves both RAG and agents.

What is Haystack?

Haystack is an open-source AI orchestration framework, built by the German company deepset, for building production-ready LLM applications in Python. It has existed since 2019, when it started as a question-answering search library, and today the deepset-ai/haystack repository holds around 25,900 stars and 2,900 forks under an Apache 2.0 licence.

Its core idea is composition: instead of writing one monolithic script, you connect reusable components (a retriever, a generator, a router, an evaluator) into a graph called a pipeline. In the 2.0 announcement, deepset described the goal like this: "making it possible to implement composable AI systems that are easy to use, customize, extend, optimise, evaluate and ultimately deploy to production". That plug-together approach is what sets Haystack apart from hand-writing the glue every time.

The current line is 2.x: 2.31.0 shipped on 8 July 2026 and only asks for Python 3.10 or later. deepset has already announced a future 3.0, but 2.x is the stable line you will work with today.

How do component pipelines work?

A component is a Python class with a run method and declared input and output types. A pipeline connects one component’s output to another’s input, checking that the types match before running anything. That way you build anything from a simple semantic search to a multi-branch flow.

python -m venv .venv && source .venv/bin/activate
pip install haystack-ai
export OPENAI_API_KEY="your-key"

The minimal example of a generation pipeline takes a prompt template and a chat generator, and connects them with connect:

from haystack import Pipeline
from haystack.components.builders import ChatPromptBuilder
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage

pipe = Pipeline()
pipe.add_component("prompt", ChatPromptBuilder(
    template=[ChatMessage.from_user("Explain {{topic}} in one sentence.")]))
pipe.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini"))
pipe.connect("prompt.prompt", "llm.messages")

output = pipe.run({"prompt": {"topic": "a Haystack pipeline"}})
print(output["llm"]["replies"][0].text)

The big change in version 2.0 over 1.x was allowing cycles in the graph. Before, a pipeline had to be acyclic; now an output can flow back to an earlier component, which is exactly what an agent needs to retry after using a tool.

What is the Agent component and how does it use tools?

The Agent component (haystack.components.agents.Agent) is a ready-made agent built on that cycle engine. Instead of assembling the loop by hand, you pass it a chat generator and a list of tools, and it handles reason, act and observe until it finishes. It is the same reason-act-observe pattern you will see in any AI agent.

Its key parameters are few:

  • chat_generator: mandatory, a chat generator that supports tools.
  • tools: the list of tools (functions, components, whole pipelines or MCP servers).
  • exit_conditions: when to stop; the default is ["text"], meaning when the model replies without requesting more tools.
  • max_agent_steps: the iteration cap, 100 by default, so a confused agent does not fall into an infinite loop.
from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.tools import tool

@tool
def weather(city: str) -> str:
    """Return the weather for a city."""
    return f"It is 22 degrees and clear in {city}."

agent = Agent(
    chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
    tools=[weather],
    system_prompt="Use the weather tool when asked about the weather.",
)

response = agent.run(messages=[ChatMessage.from_user("What is the weather in Madrid?")])
print(response["last_message"].text)

Each tool is defined with the @tool decorator on an ordinary function; Haystack generates the argument schema from your type signature. Because the Agent is itself a component, you can drop it inside a larger pipeline, next to a retriever or other agents.

How do you combine RAG and agents?

Here is Haystack’s real strength: RAG and agents are not two separate products but components of the same pipeline. A typical RAG flow connects a retriever (which searches a vector database), a prompt builder that inserts the retrieved documents, and a generator that writes the answer from those sources.

To move from RAG to an agent, you wrap that retrieval pipeline in a tool and give it to the Agent component. The agent decides when to search, with which query and how many times, instead of always retrieving exactly once. So the same system answers direct questions with one search and, when the question is complex, chains several searches before replying. It is a pattern similar to the tool flows of LlamaIndex, but with Haystack’s explicit graph control.

Haystack or LlamaIndex?

Both are mature Python frameworks that do RAG and agents, so the choice follows your priority. LlamaIndex was born data-centric: it shines at connecting sources, indexing documents and building query engines, with agents layered on top. Haystack was born production-orchestration-centric: its typed graph, built-in evaluation and deployment as an API with Hayhooks make it strong when the system must be maintainable and auditable.

Aspect Haystack LlamaIndex
Origin focus Production orchestration Data and indexing for RAG
Mental model Graph of typed components Indices and query engines
Cycles and agents Pipelines with cycles, Agent component AgentWorkflow and ReActAgent
Strong point Maintainable, evaluable systems RAG over your documents

The practical rule: if your priority is ingesting and indexing lots of data, start with LlamaIndex; if it is orchestrating a robust system and deploying it, Haystack gives you more control.

Frequently asked questions

Which is the Haystack install package?

The modern package is haystack-ai, which you install with pip install haystack-ai and requires Python 3.10 or later. Watch out for the old name farm-haystack: it belongs to the 1.x line, which no longer gets new features. For anything you start today, use haystack-ai and version 2.31.0 or later, which is where the Agent component and the cycle engine live.

Do I need a paid API to use Haystack?

No. Although the examples usually use the OpenAI API, Haystack has integrations for many providers and for models you run on your own machine. You can replace OpenAIChatGenerator with a generator pointing at Ollama or a local server, and the rest of the pipeline does not change. That lets you prototype with a powerful model and then move the load to a cheaper or private one.

Is Haystack for production or only prototypes?

It is designed for production from the start. Beyond pipelines, it includes YAML serialisation, built-in tracing, logging and evaluation, and Hayhooks to expose a pipeline as a REST API. That is exactly the goal deepset set for version 2.0: composable systems that are easy to evaluate and deploy, not just to prototype.

Conclusion

Haystack gets it right by treating RAG and agents as the same problem: typed components you connect into a pipeline and, when a loop is needed, an Agent component that reasons with tools. With the 2.x line, its cycles and its production focus, it is a solid choice when you want a maintainable system rather than the fastest route to a prototype. The natural next step is to install haystack-ai, build the generation pipeline in this guide and then wrap a search in a tool for your first agent. If you come from the data world, compare it first with building agents with LlamaIndex.

Sources: [1] Haystack, Agent component documentation[1], [2] deepset-ai/haystack repository on GitHub[2], [3] Haystack 2.0 announcement on the deepset blog[3], [4] haystack-ai package on PyPI[4].

Visitas: 0

Sources

  1. Haystack, Agent component documentation
  2. deepset-ai/haystack repository on GitHub
  3. Haystack 2.0 announcement on the deepset blog
  4. haystack-ai package on PyPI

Route: Frameworks to Build AI Agents