Haystack AI Tutorial: Agentische Workflows aufbauen

Während der Ära der Retrieval-Augmented Generation (RAG) wurden Frameworks wie LangChain für die Entwicklung von KI-Anwendungen populär. In dem Maße, in dem sich die Welt auf agentenbasierte KI-Workflows verlagert, werden Frameworks wie Haystack AI aufgrund ihrer Flexibilität, Modularität und Effektivität bei der Bewältigung einer breiten Palette von Anwendungsfällen immer wichtiger.

In diesem Tutorium lernen wir Haystack AI kennen, erkunden seine wichtigsten Komponenten und Anwendungsfälle und erfahren, wie man einen KI-Agenten-Workflow aufbaut, der mehrere Tools integriert. Ein agentenbasierter Arbeitsablauf bezieht sich auf Systeme, bei denen Sprachmodelle auf der Grundlage von Benutzeranfragen selbstständig Werkzeuge und Komponenten aufrufen, um ein Ziel zu erreichen.

Wenn du dich noch nicht mit dem Thema beschäftigt hast, solltest du dir unsere Tutorials zu Agentische KI und Agentische RAG.

Wir halten unsere Leserinnen und Leser mit The Median auf dem Laufenden, unserem kostenlosen Freitags-Newsletter, der die wichtigsten Meldungen der Woche aufschlüsselt. Melde dich an und bleibe in nur ein paar Minuten pro Woche auf dem Laufenden:

Was ist Haystack AI?

Haystack ist ein Open-Source-Framework, das für die Entwicklung hochgradig anpassbarer, produktionsreifer Anwendungen auf der Grundlage von Large Language Models (LLMs) entwickelt wurde. Sie ermöglicht es Entwicklern, eine breite Palette von KI-gesteuerten Systemen zu erstellen, darunter RAG-Pipelines, agentenbasierte Workflows, hochmoderne Suchsysteme und sogar vollständig autonome KI-Anwendungen.

Die modulare Architektur von Haystack ermöglicht es Entwicklern, führende KI-Technologien und -Tools zu integrieren, darunter OpenAI, Hugging Face Transformers, Chroma, MCP-Tools, Elasticsearch und mehr. 

Es ist einfacher als Langchain und bietet eine breite Palette von Werkzeugen, mit denen du deine Komponenten und Agenten mit nur wenigen Zeilen Code erstellen kannst.

Im Kern ist Haystack um Komponenten und Pipelines herum aufgebaut, die mit LLM-Anbietern, Dokumentenspeichern, Tools, Agenten und einem umfangreichen Ökosystem von Integrationen zusammenarbeiten. Diese Bausteine geben Entwicklern die Möglichkeit, durchgängige KI-Systeme zu entwerfen, anzupassen und einzusetzen.

Quelle: Haystack-Konzepte Übersicht

Die wichtigsten Komponenten von Haystack

Mit den folgenden Haystack-Komponenten kannst du robuste RAG-WorkflowsAgenten-Pipelines aufbauen oder sogar beides für fortschrittliche KI-Anwendungen kombinieren.

1. Komponenten

Haystack bietet verschiedene Komponenten für bestimmte Aufgaben wie das Abrufen, Erstellen oder Speichern von Dokumenten. Diese Komponenten sind Python-Klassen mit aufrufbaren Methoden, die mit Parametern initialisiert und mit der Methode run() ausgeführt werden. 

Die Komponenten-API vereinfacht die Erstellung von benutzerdefinierten Komponenten, einschließlich solcher für APIs und Datenbanken von Drittanbietern. 

2. Stromerzeuger

Die Generatoren sind für die Erstellung von Textantworten auf der Grundlage der erhaltenen Aufforderungen verantwortlich. Im Backend nutzen diese Generatoren APIs, die von LLM-Anbietern zur Verfügung gestellt werden, und werden auf spezifische Anforderungen zugeschnitten.

Es gibt zwei Arten von Generatoren:

1. Chat-Generatoren: Diese sind für Konversationskontexte konzipiert und ermöglichen das Abschließen von Chats durch Interaktion mit einer Reihe von Nachrichten.

2. Nicht-Chat-Generatoren: Diese werden für einfachere Aufgaben der Texterstellung verwendet, z. B. für Übersetzungen oder Zusammenfassungen.

3. Retriever

Rufe relevante Dokumente aus einem Dokumentenspeicher auf der Grundlage von Benutzeranfragen ab. Dieses System wird für bestimmte Dokumentenspeicher angepasst, damit sie mit individuellen Parametern einzigartige Datenbankanforderungen erfüllen können. Für den Elasticsearch-Dokumentenspeicher sind zum Beispiel sowohl Retriever- als auch Dokumentenspeicher-Pakete verfügbar.

4. Dokumentenspeicher

Die Schnittstelle zur Dokumentenablage in Haystack verwaltet Dokumente effektiv. Es enthält Funktionen wie write_documents () und delete_documents () für die Datenverwaltung. Komponenten können einfach mit dem Dokumentenspeicher interagieren, um Dokumente zu lesen oder zu schreiben. Eine DocumentWriter Komponente kann verwendet werden, um Daten in Document Stores für komplexere Workflows zu schreiben.

5. Datenklassen

Datenklassen vereinfachen die Kommunikation zwischen Komponenten auf unkomplizierte und modulare Weise. Informationen werden innerhalb des Systems als Inputs oder Outputs in Pipelines ausgetauscht.

Es gibt zwei Arten von Datenklassen:

• Dokumentenklasse: Diese Klasse umfasst Text, Metadaten, Tabellen oder Binärdaten. Dokumente können in Dokumentenspeichern gespeichert oder zwischen Komponenten übertragen werden.
• Antworte Klasse: Diese Klasse enthält die generierte Antwort, die ursprüngliche Anfrage und zugehörige Metadaten.

6. Pipelines

Pipelines kombinieren Komponenten, Dokumentenspeicher und Integrationen zu anpassbaren Workflows. Sie unterstützen Funktionen wie gleichzeitige Abläufe, eigenständige Komponenten, Schleifen sowie Vorverarbeitungs-, Indizierungs- und Abfrageschritte. Pipelines können in Formaten gespeichert werden wie YAML oder TOML zur Wiederverwendung oder Weitergabe gespeichert werden.

7. Agenten

KI-Agenten sind autonome Systeme, die große Sprachmodelle verwenden, um Entscheidungen zu treffen und komplexe Aufgaben zu bewältigen. Du kannst Tools bauen, die sich mit einer API verbinden, sie dem Agenten geben und dann eine Frage stellen. Der Agent wird die Anfrage analysieren und je nach deiner Frage die passenden Werkzeuge einsetzen.

Erste Schritte mit Haystack AI

In diesem Abschnitt werden wir die wichtigsten Komponenten von Haystack anwenden, um einen KI-Agenten-Workflow zu erstellen, der je nach Benutzeranfrage mit dem RAG- oder Web-Access-Tool verwendet wird. 

1. Einrichten der Umgebung

In diesem Leitfaden werden wir DataLab als Programmierumgebung verwenden. Um loszulegen, werden wir die folgenden Python-Pakete installieren: Haystack, OpenAI, Tavil und itertools. Hier siehst du, wofür jedes Paket verwendet wird:

1. Heuhaufen: Für die Erstellung von Pipelines und Agenten zur Entwicklung LLM-basierter Anwendungen.
2. Tavil: Für den Zugriff auf Websuchfunktionen über APIs.
3. OpenAI: Für die Verwendung von LLMs und Einbettungsmodellen.
4. itertools: Für fortgeschrittene Iterationswerkzeuge und effiziente Schleifen in Python.

!pip install -qU \
    "haystack-ai[agentst]" \
    tavily-python \
    openai \
    more_itertools

Um OpenAI und Tavily zu nutzen, setze ihre API-Schlüssel als Umgebungsvariablen. Wenn du DataLab verwendest, kannst du Umgebungsvariablen hinzufügen, indem du auf die Registerkarte Umgebung navigierst und die Option Umgebungsvariablen auswählst .

Alternativ kannst du sie auch programmatisch in Python einstellen:

import os

os.environ["OPENAI_API_KEY"]  = "sk-..."   # ← paste your OpenAI key
os.environ["TAVILY_API_KEY"]  = "tvly-..." # ← paste your Tavily key

2. Vorbereiten der Wissensbasis

Wir erstellen eine Wissensdatenbank mit der Haystack-Datenklasse Document. Diese Wissensdatenbank enthält Informationen über die Stadt Islamabad.

from haystack.dataclasses import Document
from typing import List, Any, Dict


docs: List[Document] = [
    Document(content="Islamabad experiences a humid subtropical climate with hot summers and mild winters."),
    Document(content="Peak tourist season in Islamabad is during spring (March to May) and autumn (September to November) due to pleasant weather."),
    Document(content="Faisal Mosque, one of the largest mosques in the world, is an iconic landmark in Islamabad designed by Turkish architect Vedat Dalokay."),
    Document(content="Islamabad was purpose-built as the capital of Pakistan in the 1960s, designed by Greek architect Constantinos Apostolos Doxiadis."),
    Document(content="The city is known for its well-planned infrastructure, wide roads, and green spaces, making it one of the most organized cities in Pakistan."),
]

3. Aufbau der Dokumentenspeicher-Pipeline

Der Dokumentenspeicher fungiert als Vektorspeicher, der Texteinbettungen speichert und ein effizientes Abrufen auf der Grundlage von Benutzeranfragen ermöglicht. 

Hier werden wir:

1. Erstelle einen In-Memory-Dokumentenspeicher.
2. Baue eine Haystack-Pipeline mit Komponenten wie einem OpenAI Embedder und einem Document Writer.
3. Wandle die Dokumente in Einbettungen um und speichere sie in einem Dokumentenspeicher.

from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.components.embedders import OpenAIDocumentEmbedder
from haystack.components.writers import DocumentWriter
from haystack import Pipeline, component

document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")

indexing_pipeline = Pipeline()
indexing_pipeline.add_component("embedder", OpenAIDocumentEmbedder(model="text-embedding-3-small"))
indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_store))
indexing_pipeline.connect("embedder", "writer")

indexing_pipeline.run({"embedder": {"documents": docs}})

Nach dem Durchlaufen der Pipeline werden die Dokumente erfolgreich als Einbettungen gespeichert:

Calculating embeddings: 1it [00:00,  1.34it/s]


{'embedder': {'meta': {'model': 'text-embedding-3-small',
   'usage': {'prompt_tokens': 128, 'total_tokens': 128}}},
 'writer': {'documents_written': 5}}

4. Das RAG-Tool erstellen

Sobald der Dokumentenspeicher gefüllt ist, werden wir ein benutzerdefiniertes RAG-Suchwerkzeug erstellen. 

Dieses Tool wird:

1. Wandle Benutzeranfragen in Einbettungen um.
2. Führe Ähnlichkeitssuchen im Dokumentenspeicher durch.
3. Finde relevante Dokumente.

from haystack.tools import ComponentTool
from haystack.components.embedders import OpenAIDocumentEmbedder, OpenAITextEmbedder
from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever

@component()
class RagSearcher:
    """Query ‑> top‑k docs from the private store"""
    def __init__(self, document_store, top_k: int = 3):
        self.text_embedder = OpenAITextEmbedder(model="text-embedding-3-small")
        self.retriever = InMemoryEmbeddingRetriever(document_store=document_store, top_k=top_k)

    @component.output_types(documents=List[Document])
    def run(self, text: str) -> Dict[str, Any]:
        emb_out = self.text_embedder.run(text=text)
        docs_out = self.retriever.run(query_embedding=emb_out["embedding"])
        return {"documents": docs_out["documents"]}

rag_tool = ComponentTool(
    component=RagSearcher(document_store),
    name="rag_search",
    description="Semantic search over the Islamabad knowledge base."
)

5. Ein Web-Suchwerkzeug erstellen

Da Tavily keine nativen Haystack-Komponenten hat, werden wir ein benutzerdefiniertes Web-Suchwerkzeug mit der Tavily-API erstellen. Dieses Tool holt Live-Suchergebnisse aus dem Internet und gibt sie als Document Objekte zurück.

import os
import requests
from haystack import component
from haystack.dataclasses import Document
from typing import List

@component
class TavilyWebSearch:
    def __init__(self, api_key: str, top_k: int = 3):
        self.api_key = api_key
        self.top_k   = top_k

    def run(self, query: str):
        resp = requests.post(
            "https://api.tavily.com/search",
            json={
                "api_key": self.api_key,
                "query": query,
                "max_results": self.top_k,
                "include_answer": True,
            },
            timeout=15,
        )
        resp.raise_for_status()
        data = resp.json()

        docs: List[Document] = []
        if answer := data.get("answer"):
            docs.append(Document(content=answer, meta={"source": "tavily:direct_answer"}))

        for hit in data.get("results", []):
            docs.append(
                Document(
                    content=hit["content"],
                    meta={
                        "title": hit["title"],
                        "url": hit["url"],
                    },
                )
            )
        return {"documents": docs}


web_tool = ComponentTool(
    component=TavilyWebSearch(api_key=os.environ["TAVILY_API_KEY"], top_k=3),
    name="web_search",
    description="Live web search via Tavily ."
)

6. Einen Agenten aufbauen

Wir werden einen Generator mit den OpenAI-Funktionen und dem neuesten gpt-4.1-mini Modell erstellen. Zuerst werden wir die Systemabfrage entwickeln, die dem Agenten hilft, zu bestimmen, welche Tools er für bestimmte Benutzeranfragen verwenden soll. Zum Schluss erstellen wir den Agenten mit dem Generator, der System-Eingabeaufforderung und einer Liste von Tools.

Auf der Grundlage der Systemaufforderung prüft der Agent die Informationen zunächst mit der RAG-Suche. Wenn sich die Frage des Nutzers auf die neuesten Nachrichten, das Wetter oder aktuelle Meldungen bezieht, wird der Agent direkt die Websuche nutzen.

from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.components.agents import Agent

generator = OpenAIChatGenerator(model="gpt-4.1-mini")

system_prompt = """
You are a helpful assistant.
- Use rag_search first to retrieve information from the knowledge base.
- Use web_search only when the query requires fresh, real-time, or external information (e.g., weather, breaking news).
"""

agent = Agent(
    chat_generator=generator,
    system_prompt=system_prompt,
    tools=[rag_tool, web_tool],
)

7. Testen des RAG-Tools

Wir werden eine Frage über Islamabad stellen, um das RAG-Tool zur Beantwortung aufzurufen.

from haystack.dataclasses import ChatMessage

msg = ChatMessage.from_user("What is the peak tourist season in Islamabad?")
resp = agent.run(messages=[msg])
print(resp["messages"][-1].text)

Wir haben sehr kontextbezogene Antworten, aber woher wissen wir, dass er die RAG-Tools zur Beantwortung verwendet hat?

The peak tourist season in Islamabad is during spring (March to May) and autumn (September to November).

8. Verwendete Analysetools

Um zu überprüfen, welche Tools aufgerufen werden, erstellen wir eine Funktion, die Informationen über die Tools extrahiert.

def tools_used(run_output: dict) -> list[str]:
    seen, ordered = set(), []

    for msg in run_output["messages"]:
        for call in msg.tool_calls:
            if call.tool_name not in seen:
                ordered.append(call.tool_name)
                seen.add(call.tool_name)
    return ordered
print("Tools invoked →", tools_used(resp))

Beim ersten Test verwendete der Agent nur das Toolrag_search, um die Frage zu beantworten.

Tools invoked → ['rag_search']

9. Testen des Webtools

Wir werden jetzt nach dem Wetter in Islamabad fragen. Anstatt das RAG-Tool aufzurufen, wird es die Websuche nutzen, um die Frage zu beantworten.

msg = ChatMessage.from_user("What is the temperature in Islamabad now?")
resp = agent.run(messages=[msg])
print(resp["messages"][-1].text)
print("Tools invoked →", tools_used(resp))

Die Antwort ist sehr genau und sie hat die Websuche benutzt, um die Frage zu beantworten.

The current temperature in Islamabad is 31°C with a real-feel temperature of 32°C.
Tools invoked → ['web_search']

Wenn du Probleme beim Ausführen des obigen Codes hast, sieh dir bitte das Datalab Notebook an: Haystack AI Tutorial - DataLab.

Haystack Anwendungsfälle

Wir haben die Grundlagen des Haystack AI Frameworks behandelt. Der nächste Schritt auf deiner Lernreise ist die Erstellung einer voll funktionsfähigen KI-Anwendung. Hier sind einige der Anwendungsfälle, die Entwickler erforschen:

1. Multimodale KI: Entwickle Systeme, die verschiedene Eingabearten, einschließlich Text und Bilder, für Anwendungen wie Bildunterschriften, Audiotranskription und Bilderzeugung verarbeiten und integrieren.
2. Konversationelle KI: Biete Chat-Schnittstellen für dynamische Chatbots an, die sich auf sinnvolle Unterhaltungen einlassen können.
3. Agentische Pipelines: Verwende funktionale Aufrufe, damit Sprachmodelle mit Tools interagieren und auf externe Funktionen zugreifen können.
4. Erweiterte RAG: Kombiniere die Dokumentensuche mit LLM-basierter Generierung, um eine Vielzahl von Such- und Generierungsstrategien umzusetzen.
5. Integration von MCP-Tools: Verbinde LLMs nahtlos mit externen Tools, APIs und Datenquellen mit dem Modell-Kontext-Protokoll.
6. Modellbewertung: Prüfe die Pipelines auf Genauigkeit, Relevanz und Zuverlässigkeit.
7. Multi-Agenten-Anwendungen: Schaffe Systeme, in denen mehrere Agenten effektiv zusammenarbeiten, um komplexe, mehrstufige Aufgaben zu lösen.

Schlussgedanken

Nachdem ich mit vielen LLM-Frameworks gearbeitet habe, halte ich Haystack für eine der intuitivsten und flexibelsten Optionen, die es gibt. Es fühlt sich natürlicher an, ist weniger komplex und bietet mehr Kontrolle über deine Arbeitsabläufe. 

Eines der herausragenden Merkmale ist die Leichtigkeit, mit der du benutzerdefinierte Komponenten für deine Pipelines erstellen kannst, was sie für eine Vielzahl von Anwendungsfällen anpassbar macht.

Mir hat es besonders viel Spaß gemacht, mit Agenten und Werkzeugen zu experimentieren und zu verstehen, wie man sie effektiv einsetzt. Die Arbeit mit dem Systemprompt hat mir geholfen zu verstehen, wie ich die Werkzeuge einzeln und in der Reihenfolge verwenden kann. 

Außerdem kann die Systemabfrage leicht angepasst werden, um zusätzliche Details einzubinden, wie z.B. die Anzeige von Quellen und Dokument-IDs, die für deine Anwendung wichtig sein können.

Wenn du neu in der Welt der KI-Agenten bist, kannst du in den folgenden Ressourcen mehr erfahren: 

• KI-Agenten verstehen 
• Arten von KI-Agenten 
• AI Agent Frameworks 
• Agentic RAG Tutorial mit Demo-Projekt
• N8n Leitfaden mit praktischen Beispielen