Tutoriel Haystack AI : Construire des flux de travail agentiques

À l'époque de la génération assistée par récupération (RAG), des cadres tels que LangChain sont devenus populaires pour le développement d'applications d'intelligence artificielle. Cependant, à mesure que le monde évolue vers des flux de travail d'IA agentique, des cadres comme Haystack AI deviennent importants en raison de leur flexibilité, de leur modularité et de leur efficacité dans la gestion d'un large éventail de cas d'utilisation.

Dans ce tutoriel, nous allons découvrir Haystack AI, explorer ses composants clés et ses cas d'utilisation, et apprendre à construire un flux de travail agentique d'IA qui intègre plusieurs outils. Un flux de travail agentique se réfère à des systèmes dans lesquels les modèles de langage invoquent de manière autonome des outils et des composants sur la base de requêtes de l'utilisateur afin d'atteindre un objectif.

Si vous êtes novice en la matière, n'hésitez pas à consulter nos tutoriels sur les thèmes suivants L'IA agentique et RAG agentique.

Nous tenons nos lecteurs informés des dernières nouveautés en matière d'IA en leur envoyant The Median, notre lettre d'information gratuite du vendredi qui analyse les principaux sujets de la semaine. Abonnez-vous et restez à la pointe de la technologie en quelques minutes par semaine :

Qu'est-ce que Haystack AI ?

Haystack est un cadre open-source conçu pour créer des applications hautement personnalisables et prêtes à la production, basées sur de grands modèles de langage (LLM). Il permet aux développeurs de créer une large gamme de systèmes pilotés par l'IA, y compris des pipelines RAG, des flux de travail basés sur des agents, des systèmes de recherche de pointe et même des applications d'IA entièrement autonomes.

L'architecture modulaire de Haystack permet aux développeurs d'intégrer des technologies et des outils d'IA de premier plan, notamment OpenAI, Hugging Face Transformers, Chroma, les outils MCP, Elasticsearch, etc. 

Il est plus simple que Langchain et offre un large éventail d'outils pour créer vos composants et agents avec seulement quelques lignes de code.

Haystack est structuré autour de composants et de pipelines, qui collaborent avec des fournisseurs LLM, des magasins de documents, des outils, des agents et un riche écosystème d'intégrations. Ces modules permettent aux développeurs de concevoir, de personnaliser et de déployer des systèmes d'IA de bout en bout.

Source : Aperçu des concepts de Haystack

Composants clés de Haystack

En utilisant les composants Haystack suivants, vous pouvez construire de robustes flux de travail RAGdes pipelines agentiques, ou même combiner les deux pour des applications d'IA avancées.

1. Composants

Haystack propose différents composants pour des tâches spécifiques telles que la recherche, la génération ou le stockage de documents. Ces composants sont des classes Python avec des méthodes appelables qui sont initialisées avec des paramètres et exécutées à l'aide de la méthode run(). 

L'API des composants rationalise le processus de création de composants personnalisés, y compris pour les API et les bases de données de tiers. 

2. Générateurs

Les générateurs sont chargés de produire des réponses textuelles sur la base des invites qu'ils reçoivent. En arrière-plan, ces générateurs exploitent les API fournies par les fournisseurs de LLM et sont adaptés pour répondre à des besoins spécifiques.

Il existe deux types de générateurs :

1. Générateurs de chat : Ils sont conçus pour des contextes conversationnels et permettent de terminer une conversation en interagissant avec une série de messages.

2. Générateurs de non-chats : Ils sont utilisés pour des tâches de génération de texte plus simples, telles que la traduction ou le résumé.

3. Retrievers

Récupérer des documents pertinents à partir d'un magasin de documents en fonction des requêtes de l'utilisateur. Ce système est personnalisé pour des magasins de documents spécifiques, ce qui leur permet de gérer des exigences de base de données uniques avec des paramètres personnalisés. Par exemple, le magasin de documents Elasticsearch dispose à la fois d'un récupérateur et d'un magasin de documents.

4. Magasins de documents

L'interface de stockage de documents de Haystack gère efficacement les documents. Il comprend des fonctions telles que write_documents () et delete_documents () pour gérer les données. Les composants peuvent facilement interagir avec le magasin de documents pour lire ou écrire des documents. Un composant DocumentWriter peut être utilisé pour écrire des données dans les magasins de documents pour des flux de travail plus complexes.

5. Classes de données

Les classes de données simplifient la communication entre les composants de manière simple et modulaire. Les informations sont échangées au sein du système sous forme d'entrées ou de sorties dans des pipelines.

Il existe deux types de classes de données :

• Classe de document : Cette classe comprend du texte, des métadonnées, des tableaux ou des données binaires. Les documents peuvent être stockés dans des magasins de documents ou transférés entre les composants.
• Classe de réponse : Cette classe contient la réponse générée, la requête originale et les métadonnées associées.

6. Pipelines

Les pipelines combinent des composants, des magasins de documents et des intégrations dans des flux de travail personnalisables. Ils prennent en charge des fonctions telles que les flux simultanés, les composants autonomes, les boucles, ainsi que les étapes de prétraitement, d'indexation et d'interrogation. Les pipelines peuvent être enregistrés dans des formats tels que YAML ou TOML en vue d'une réutilisation ou d'un partage.

7. Agents

Les agents d'IA sont des systèmes autonomes qui utilisent de grands modèles de langage pour prendre des décisions et accomplir des tâches complexes. Vous pouvez créer des outils pour vous connecter à une API, les donner à l'agent, puis poser une question. L'agent analysera la demande et utilisera les outils appropriés en fonction de votre question.

Commencez avec Haystack AI

Dans cette section, nous appliquerons les composants clés de Haystack pour construire un flux de travail d'agent d'IA qui sera utilisé avec le RAG et l'outil d'accès au web, en fonction de la requête de l'utilisateur. 

1. Mise en place de l'environnement

Pour ce guide, nous utiliserons DataLab comme environnement de codage. Pour commencer, nous allons installer les paquets Python suivants : Haystack, OpenAI, Tavil et itertools. Voici à quoi sert chaque paquet :

1. Botte de foin : Pour créer des pipelines et des agents afin de construire des applications basées sur le LLM.
2. Tavil : Pour accéder aux fonctionnalités de recherche sur le web via les API.
3. OpenAI : Pour l'utilisation des LLM et des modèles d'intégration.
4. itertools : Pour des outils d'itération avancés et des boucles efficaces en Python.

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

Pour utiliser OpenAI et Tavily, définissez leurs clés API en tant que variables d'environnement. Si vous utilisez DataLab, vous pouvez ajouter des variables d'environnement en accédant à l' onglet Environnement de et en sélectionnant l'option Variables d'environnement.

Vous pouvez également les définir par programme en Python :

import os

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

2. Préparation de la base de connaissances

Nous allons créer une base de connaissances en utilisant la classe de données Document de Haystack. Cette base de connaissances contiendra des informations sur la ville d'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. Construire le pipeline du magasin de documents

Le magasin de documents agit comme un magasin de vecteurs, stockant les incorporations de texte et permettant une recherche efficace sur la base des requêtes de l'utilisateur. 

Ici, nous le ferons :

1. Créez un magasin de documents en mémoire.
2. Construisez un pipeline Haystack avec des composants tels qu'un intégrateur OpenAI et un rédacteur de documents.
3. Convertissez les documents en encastrements et stockez-les dans un magasin de documents.

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

Après l'exécution du pipeline, les documents sont stockés avec succès en tant qu'encastrements :

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. Création de l'outil RAG

Une fois le magasin de documents alimenté, nous créerons un outil de recherche RAG personnalisé. 

Cet outil vous permettra

1. Convertir les requêtes de l'utilisateur en enregistrements.
2. Effectuer des recherches de similarité dans le magasin de documents.
3. Recherchez les documents pertinents.

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. Création d'un outil de recherche sur le web

Comme Tavily n'a pas de composants Haystack natifs, nous allons créer un outil de recherche web personnalisé en utilisant l'API de Tavily. Cet outil récupère les résultats d'une recherche en ligne et les renvoie sous forme d'objets Document.

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. Création d'un agent

Nous allons créer un générateur en utilisant les fonctions OpenAI et le dernier modèle gpt-4.1-mini. Tout d'abord, nous développerons l'invite du système qui aidera l'agent à déterminer les outils à utiliser pour les demandes spécifiques des utilisateurs. Enfin, nous créerons l'agent avec le générateur, l'invite système et une liste d'outils.

Sur la base de l'invite du système, l'agent vérifiera d'abord les informations à l'aide de la recherche RAG. Si la question de l'utilisateur porte sur les dernières nouvelles, la météo ou les dernières actualités, l'agent utilisera directement l'outil de recherche en ligne.

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. Test de l'outil RAG

Nous allons poser une question sur Islamabad et invoquer l'outil RAG pour y répondre.

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)

Nous disposons de réponses très contextuelles, mais comment savoir s'il a utilisé les outils RAG pour répondre ?

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

8. Analyse des outils utilisés

Pour vérifier quels outils sont invoqués, nous allons créer une fonction qui extraira des informations sur les outils.

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

Pour le premier test, l'agent n'a utilisé que l'outilrag_search pour répondre à la question.

Tools invoked → ['rag_search']

9. Test de l'outil web

Nous allons maintenant vous interroger sur la météo d'Islamabad. Au lieu d'invoquer l'outil RAG, il utilisera l'outil de recherche sur le web pour répondre à la question.

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

La réponse est très précise et elle a utilisé l'outil de recherche en ligne pour répondre à la question.

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

Si vous rencontrez des problèmes lors de l'exécution du code ci-dessus, veuillez consulter le carnet de notes Datalab : Tutoriel Haystack AI - DataLab.

Cas d'utilisation de Haystack

Nous avons couvert les bases du cadre Haystack AI. L'étape suivante de votre parcours d'apprentissage consiste à créer une application d'IA entièrement fonctionnelle. Voici quelques-uns des cas d'utilisation explorés par les développeurs :

1. L'IA multimodale : Développer des systèmes qui traitent et intègrent différents types d'entrées, y compris le texte et les images, pour des applications telles que le sous-titrage d'images, la transcription audio et la génération d'images.
2. L'IA conversationnelle : Fournir des interfaces de chat pour des chatbots dynamiques et multitours, capables d'engager des conversations pertinentes.
3. Pipelines agentiques : Utilisez l'appel fonctionnel pour permettre aux modèles de langage d'interagir avec des outils et d'accéder à des capacités externes.
4. RAG avancé : Combinez la recherche de documents avec la génération basée sur LLM pour mettre en œuvre une variété de stratégies de recherche et de génération.
5. Intégration des outils MCP : Connectez de manière transparente les LLM avec des outils externes, des API et des sources de données à l'aide du Protocole de contexte de modèle.
6. Évaluation du modèle : Évaluer les pipelines en termes d'exactitude, de pertinence et de fiabilité.
7. Applications multi-agents : Créer des systèmes dans lesquels plusieurs agents collaborent efficacement pour résoudre des tâches complexes à plusieurs étapes.

Réflexions finales

Ayant travaillé avec de nombreux cadres LLM, je trouve que Haystack est l'une des options les plus intuitives et les plus flexibles disponibles. Il est plus naturel à utiliser, moins complexe et offre un meilleur contrôle sur vos flux de travail. 

L'une de ses principales caractéristiques est la facilité avec laquelle vous pouvez créer des composants personnalisés pour vos pipelines, ce qui le rend très adaptable à un large éventail de cas d'utilisation.

J'ai particulièrement apprécié d'expérimenter les agents et les outils et de comprendre comment invoquer chacun d'entre eux de manière efficace. Le fait de travailler avec l'invite du système m'a aidé à comprendre comment utiliser les outils individuellement et dans l'ordre. 

En outre, l'invite du système peut être facilement personnalisée pour inclure des détails supplémentaires, tels que l'affichage des sources et des identifiants de documents, qui peuvent être importants pour votre application.

Si vous ne connaissez pas encore le monde des agents d'intelligence artificielle, consultez les ressources ci-dessous pour en savoir plus : 

• Comprendre les agents d'intelligence artificielle 
• Types d'agents d'intelligence artificielle 
• Cadres d'agents d'IA 
• Tutoriel RAG Agentic avec projet de démonstration
• Guide N8n avec exemples pratiques