Haystack: pipelines y agentes

Haystack es el framework de deepset para construir aplicaciones de IA como piezas conectadas: enchufas un recuperador a un generador y a un router, y obtienes un sistema que puedes probar, cambiar y desplegar en producción. Es una biblioteca de Python de código abierto que trata cada bloque (búsqueda, LLM, decisión) como un componente con entradas y salidas tipadas. En esta guía verás qué es un pipeline, cómo funciona el componente Agent con herramientas, y cómo combinar RAG y agentes en el mismo sistema. La misma explicación está disponible en inglés.

Puntos clave

• Haystack es un framework de Python de deepset, con licencia Apache 2.0, para construir aplicaciones de IA como pipelines de componentes conectados.
• Se instala con pip install haystack-ai; la versión 2.31.0 salió el 8 de julio de 2026 y requiere Python 3.10 o superior.
• La versión 2.0, una reescritura completa publicada el 11 de marzo de 2024, introdujo conexiones tipadas y pipelines con ciclos, lo que hace posibles los bucles de un agente.
• El componente Agent ejecuta un bucle: llama al modelo, ejecuta las herramientas que pida y repite hasta una condición de salida, con un límite de 100 pasos por defecto.
• Es un proyecto consolidado: el repositorio deepset-ai/haystack ronda las 25.900 estrellas y existe desde 2019, y sirve tanto para RAG como para agentes.

¿Qué es Haystack?

Haystack es un framework de orquestación de IA de código abierto, creado por la empresa alemana deepset, para construir aplicaciones de LLM listas para producción en Python. Existe desde 2019, cuando nació como una biblioteca de búsqueda por preguntas y respuestas, y hoy el repositorio deepset-ai/haystack acumula unas 25.900 estrellas y 2.900 forks bajo licencia Apache 2.0.

Su idea central es la composición: no escribes un script monolítico, sino que conectas componentes reutilizables (un recuperador, un generador, un router, un evaluador) en un grafo llamado pipeline. En el anuncio de la versión 2.0, deepset describió el objetivo así: "hacer posible implementar sistemas de IA componibles que sean fáciles de usar, personalizar, ampliar, optimizar, evaluar y, en última instancia, desplegar en producción". Ese enfoque de piezas encajables es lo que diferencia a Haystack de escribir el pegamento a mano cada vez.

La versión actual es la línea 2.x: la 2.31.0 se publicó el 8 de julio de 2026 y solo pide Python 3.10 o superior. deepset ya ha anunciado una futura versión 3.0, pero la 2.x es la estable con la que trabajarás hoy.

¿Cómo funcionan los pipelines de componentes?

Un componente es una clase de Python con un método run y unas entradas y salidas de tipos declarados. Un pipeline conecta la salida de un componente con la entrada de otro, comprobando que los tipos encajan antes de ejecutar nada. Así construyes desde una búsqueda semántica sencilla hasta un flujo con varias ramas.

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

El ejemplo mínimo de un pipeline de generación toma una plantilla de prompt y un generador de chat, y los conecta con 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("Explica {{tema}} en una frase.")]))
pipe.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini"))
pipe.connect("prompt.prompt", "llm.messages")

salida = pipe.run({"prompt": {"tema": "un pipeline de Haystack"}})
print(salida["llm"]["replies"][0].text)

La gran novedad de la versión 2.0 frente a la 1.x fue permitir ciclos en el grafo. Antes un pipeline tenía que ser acíclico; ahora una salida puede volver a un componente anterior, que es justo lo que necesita un agente para reintentar tras usar una herramienta.

¿Qué es el componente Agent y cómo usa herramientas?

El componente Agent (haystack.components.agents.Agent) es un agente listo para usar construido sobre ese motor de ciclos. En vez de montar el bucle a mano, le pasas un generador de chat y una lista de herramientas, y él se encarga de razonar, actuar y observar hasta terminar. Es el mismo patrón razonar-actuar-observar que verás en cualquier agente de IA.

Sus parámetros clave son pocos:

• chat_generator: obligatorio, un generador de chat que admita herramientas.
• tools: la lista de herramientas (funciones, componentes, pipelines completos o servidores MCP, el protocolo abierto para conectar herramientas externas a un LLM).
• exit_conditions: cuándo parar; por defecto ["text"], es decir, cuando el modelo responde sin pedir más herramientas.
• max_agent_steps: el tope de iteraciones, 100 por defecto, para que un agente confundido no entre en un bucle infinito.

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 clima(ciudad: str) -> str:
    """Devuelve el tiempo de una ciudad."""
    return f"En {ciudad} hace 22 grados y está despejado."

agente = Agent(
    chat_generator=OpenAIChatGenerator(model="gpt-4o-mini"),
    tools=[clima],
    system_prompt="Usa la herramienta de clima cuando pregunten por el tiempo.",
)

respuesta = agente.run(messages=[ChatMessage.from_user("¿Qué tiempo hace en Madrid?")])
print(respuesta["last_message"].text)

Cada herramienta se define con el decorador @tool sobre una función normal; Haystack genera el esquema de argumentos a partir de tu firma de tipos. Como el Agent es en sí un componente, puedes meterlo dentro de un pipeline mayor, junto a un recuperador o a otros agentes.

¿Cómo se combinan RAG y agentes?

Aquí está la fuerza real de Haystack: RAG y agentes no son dos productos distintos, sino componentes del mismo pipeline. Un flujo típico de RAG conecta un recuperador (que busca en una base de datos vectorial), un constructor de prompts que inserta los documentos recuperados, y un generador que redacta la respuesta con esas fuentes.

Para pasar de RAG a un agente, envuelves ese pipeline de recuperación en una herramienta y se la das al componente Agent. El agente decide cuándo buscar, con qué consulta y cuántas veces, en lugar de recuperar siempre una sola vez. Así el mismo sistema responde preguntas directas con una búsqueda y, cuando la pregunta es compleja, encadena varias búsquedas antes de contestar. Es un patrón parecido al de los flujos con herramientas de LlamaIndex (el otro framework Python maduro para RAG y agentes, centrado en indexar datos), pero con el control explícito del grafo de Haystack.

¿Haystack o LlamaIndex?

Ambos son frameworks de Python maduros que hacen RAG y agentes, así que la elección va con tu prioridad. LlamaIndex nació centrado en los datos: destaca en conectar fuentes, indexar documentos y construir motores de consulta, con los agentes montados encima. Haystack nació centrado en la orquestación en producción: su grafo tipado, su evaluación integrada y el despliegue como API con Hayhooks (la herramienta de deepset que convierte un pipeline de Haystack en un servicio REST) lo hacen fuerte cuando el sistema debe ser mantenible y auditable.

La regla práctica: si tu prioridad es ingerir e indexar muchos datos, empieza por LlamaIndex; si es orquestar un sistema robusto y desplegarlo, Haystack te da más control.

Preguntas frecuentes

¿Cuál es el paquete de instalación de Haystack?

El paquete moderno es haystack-ai, que instalas con pip install haystack-ai y requiere Python 3.10 o superior. Cuidado con el nombre antiguo farm-haystack: corresponde a la línea 1.x, que ya no recibe funcionalidades nuevas. Para cualquier proyecto que empieces hoy usa haystack-ai y la versión 2.31.0 o posterior, que es donde vive el componente Agent y el motor de ciclos.

¿Necesito una API de pago para usar Haystack?

No. Aunque los ejemplos suelen usar la API de OpenAI, Haystack tiene integraciones para muchos proveedores y para modelos que ejecutas en tu propia máquina. Puedes sustituir OpenAIChatGenerator por un generador que apunte a Ollama (herramienta que ejecuta modelos de lenguaje de código abierto en tu propio equipo) o a un servidor local, y el resto del pipeline no cambia. Eso te deja prototipar con un modelo potente y luego mover la carga a uno más barato o privado.

¿Haystack sirve para producción o solo para prototipos?

Está pensado desde el principio para producción. Además de los pipelines, incluye serialización a YAML, trazado, registro y evaluación integrados, y Hayhooks para exponer un pipeline como API REST. Ese es precisamente el objetivo que deepset fijó para la versión 2.0: sistemas componibles fáciles de evaluar y desplegar, no solo de prototipar.

Conclusión

Haystack acierta al tratar RAG y agentes como el mismo problema: componentes tipados que conectas en un pipeline y, cuando hace falta un bucle, un componente Agent que razona con herramientas. Con la versión 2.x, sus ciclos y su vocación de producción, es una opción sólida cuando quieres un sistema mantenible más que la ruta más rápida a un prototipo. El siguiente paso natural es instalar haystack-ai, montar el pipeline de generación de esta guía y luego envolver una búsqueda en una herramienta para tu primer agente. Si vienes del mundo de los datos, compáralo antes con construir agentes con LlamaIndex.

Fuentes: [1] Haystack, documentación del componente Agent^[1], [2] Repositorio deepset-ai/haystack en GitHub^[2], [3] Anuncio de Haystack 2.0 en el blog de deepset^[3], [4] Paquete haystack-ai en PyPI^[4].

Fuentes

1. Haystack, documentación del componente Agent
2. Repositorio deepset-ai/haystack en GitHub
3. Anuncio de Haystack 2.0 en el blog de deepset
4. Paquete haystack-ai en PyPI

Ruta: Frameworks para construir agentes de IA