Tutorial de IA do Haystack: Criando fluxos de trabalho agênticos

Durante a era da RAG (Retrieval-Augmented Generation), estruturas como a LangChain tornaram-se populares para o desenvolvimento de aplicativos de IA. No entanto, à medida que o mundo muda para os fluxos de trabalho de IA agêntica, estruturas como a Haystack AI estão se tornando proeminentes devido à sua flexibilidade, modularidade e eficácia no tratamento de uma ampla gama de casos de uso.

Neste tutorial, conheceremos o Haystack AI, exploraremos seus principais componentes e casos de uso e aprenderemos a criar um fluxo de trabalho de IA agêntica que integre várias ferramentas. Um fluxo de trabalho agêntico refere-se a sistemas em que os modelos de linguagem invocam autonomamente ferramentas e componentes com base em consultas do usuário para atingir uma meta.

Se você ainda não conhece o assunto, não deixe de conferir nossos tutoriais sobre IA agêntica e Agentic RAG.

Mantemos nossos leitores atualizados sobre as últimas novidades em IA enviando o The Median, nosso boletim informativo gratuito de sexta-feira que detalha as principais histórias da semana. Inscreva-se e fique atento em apenas alguns minutos por semana:

O que é a IA do Haystack?

Haystack é uma estrutura de código aberto projetada para a criação de aplicativos altamente personalizáveis e prontos para a produção, alimentados por LLMs (Large Language Models). Ele permite que os desenvolvedores criem uma ampla variedade de sistemas orientados por IA, incluindo pipelines RAG, fluxos de trabalho baseados em agentes, sistemas de pesquisa de última geração e até mesmo aplicativos de IA totalmente autônomos.

A arquitetura modular do Haystack permite que os desenvolvedores integrem as principais tecnologias e ferramentas de IA, incluindo OpenAI, Hugging Face Transformers, Chroma, ferramentas MCP, Elasticsearch e muito mais. 

É mais simples do que Langchain e oferece uma ampla gama de ferramentas para você criar seus componentes e agentes com apenas algumas linhas de código.

Em sua essência, o Haystack é estruturado em torno de componentes e pipelines, que trabalham em conjunto com provedores de LLM, armazenamentos de documentos, ferramentas, agentes e um rico ecossistema de integrações. Esses blocos de construção oferecem aos desenvolvedores a capacidade de projetar, personalizar e implementar sistemas de IA de ponta a ponta.

Fonte: Visão geral dos conceitos do Haystack

Componentes principais do Haystack

Usando os seguintes componentes do Haystack, você pode criar fluxos de trabalho fluxos de trabalho RAGrobustos, pipelines agênticos ou até mesmo combinar ambos para aplicativos avançados de IA.

1. Componentes

O Haystack oferece vários componentes para tarefas específicas, como recuperação, geração ou armazenamento de documentos. Esses componentes são classes Python com métodos chamáveis que são inicializados com parâmetros e executados usando o método run(). 

A API de componentes simplifica o processo de criação de componentes personalizados, incluindo aqueles para APIs e bancos de dados de terceiros. 

2. Geradores

Os geradores são responsáveis por produzir respostas de texto com base nos prompts que recebem. No back-end, esses geradores aproveitam as APIs fornecidas pelos provedores de LLM e são adaptados para atender a requisitos específicos.

Há dois tipos de geradores:

1. Geradores de bate-papo: Eles são projetados para contextos de conversação e permitem que você conclua o bate-papo interagindo com uma série de mensagens.

2. Geradores que não são de bate-papo: Eles são usados para tarefas mais simples de geração de texto, como tradução ou resumo.

3. Recuperadores

Recupere documentos relevantes de um armazenamento de documentos com base em consultas do usuário. Esse sistema é personalizado para armazenamentos de documentos específicos, permitindo que eles lidem com requisitos exclusivos de banco de dados com parâmetros personalizados. Por exemplo, o armazenamento de documentos do Elasticsearch tem pacotes de retriever e de armazenamento de documentos disponíveis.

4. Armazenamento de documentos

A interface de armazenamento de documentos do Haystack gerencia documentos com eficiência. Ele inclui funções como write_documents () e delete_documents () para lidar com o gerenciamento de dados. Os componentes podem interagir facilmente com o Document Store para ler ou gravar documentos. Um componente DocumentWriter pode ser usado para gravar dados em Document Stores para fluxos de trabalho mais complexos.

5. Classes de dados

As classes de dados simplificam a comunicação entre os componentes de forma direta e modular. As informações são trocadas dentro do sistema como entradas ou saídas em pipelines.

Há dois tipos de classes de dados:

• Classe de documento: Essa classe inclui texto, metadados, tabelas ou dados binários. Os documentos podem ser armazenados em armazenamentos de documentos ou transferidos entre componentes.
• Classe de respostas: Essa classe contém a resposta gerada, a consulta original e os metadados relacionados.

6. Pipelines

Os pipelines combinam componentes, armazenamentos de documentos e integrações em fluxos de trabalho personalizáveis. Eles oferecem suporte a recursos como fluxos simultâneos, componentes autônomos, loops, bem como etapas de pré-processamento, indexação e consulta. Os pipelines podem ser salvos em formatos como YAML ou TOML para reutilização ou compartilhamento.

7. Agentes

Agentes de IA são sistemas autônomos que usam grandes modelos de linguagem para tomar decisões e realizar tarefas complexas. Você pode criar ferramentas para se conectar a uma API, fornecê-las ao agente e, em seguida, fazer uma pergunta. O agente analisará a consulta e usará as ferramentas apropriadas com base em sua pergunta.

Comece a usar o Haystack AI

Nesta seção, aplicaremos os principais componentes do Haystack para criar um fluxo de trabalho AI Agentic que será usado com o RAG e a ferramenta de acesso à Web, dependendo da consulta do usuário. 

1. Configuração do ambiente

Para este guia, usaremos o DataLab como nosso ambiente de codificação. Para começar, instalaremos os seguintes pacotes Python: Haystack, OpenAI, Tavil e itertools. Veja a seguir para que cada pacote é usado:

1. Palheiro: Para criar pipelines e agentes para desenvolver aplicativos baseados em LLM.
2. Tavil: Para acessar a funcionalidade de pesquisa na Web por meio de APIs.
3. OpenAI: Para usar LLMs e modelos de incorporação.
4. itertools: Para obter ferramentas avançadas de iteração e looping eficiente em Python.

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

Para usar o OpenAI e o Tavily, defina suas chaves de API como variáveis de ambiente. Se estiver usando o DataLab, você poderá adicionar variáveis de ambiente navegando até a guia Environment e selecionando a opção Environment Variables.

Como alternativa, você pode defini-los programaticamente em Python:

import os

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

2. Preparando a base de conhecimento

Criaremos uma base de conhecimento usando a classe de dados Document do Haystack. Essa base de conhecimento conterá informações sobre a cidade de 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. Criação do pipeline do armazenamento de documentos

O armazenamento de documentos funciona como um armazenamento de vetores, armazenando incorporação de texto e permitindo a recuperação eficiente com base nas consultas do usuário. 

Aqui, nós o faremos:

1. Crie um armazenamento de documentos na memória.
2. Crie um pipeline Haystack com componentes como um incorporador OpenAI e um gravador de documentos.
3. Converta os documentos em embeddings e armazene-os em um repositório de documentos.

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

Depois de executar o pipeline, os documentos são armazenados com sucesso como embeddings:

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. Criando a ferramenta RAG

Quando o armazenamento de documentos estiver preenchido, criaremos uma ferramenta de pesquisa RAG personalizada. 

Essa ferramenta irá:

1. Converta as consultas do usuário em incorporações.
2. Realizar pesquisas de similaridade no armazenamento de documentos.
3. Recuperar documentos relevantes.

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. Criando uma ferramenta de pesquisa na Web

Como o Tavily não tem componentes nativos do Haystack, criaremos uma ferramenta de pesquisa na Web personalizada usando a API do Tavily. Essa ferramenta buscará resultados de pesquisa na Web em tempo real e os retornará como objetos 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. Criação de um agente

Criaremos um gerador usando as funções da OpenAI e o modelo mais recente do gpt-4.1-mini. Primeiro, desenvolveremos o prompt do sistema que ajudará o agente a determinar quais ferramentas usar para solicitações específicas do usuário. Por fim, criaremos o agente com o gerador, o prompt do sistema e uma lista de ferramentas.

Com base no prompt do sistema, o agente verificará primeiro as informações usando a pesquisa RAG. Se a pergunta do usuário estiver relacionada às últimas notícias, ao clima ou às últimas notícias, o Agente usará diretamente a ferramenta de pesquisa na Web.

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. Teste da ferramenta RAG

Faremos uma pergunta sobre Islamabad para que você invoque a ferramenta RAG para responder.

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)

Temos respostas de conscientização altamente contextuais, mas como sabemos que ele usou as ferramentas RAG para responder?

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

8. Análise das ferramentas utilizadas

Para verificar quais ferramentas são invocadas, criaremos uma função que extrairá informações sobre as ferramentas.

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

No primeiro teste, o agente usou apenas a ferramentarag_search para responder à pergunta.

Tools invoked → ['rag_search']

9. Testando a ferramenta da Web

Agora vamos perguntar sobre o clima de Islamabad. Em vez de invocar a ferramenta RAG, ele usará a ferramenta de pesquisa na Web para responder à pergunta.

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

A resposta é muito precisa e você usou a ferramenta de pesquisa na Web para responder à pergunta.

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

Se você estiver tendo problemas para executar o código acima, consulte o Datalab Notebook: Tutorial de IA do Haystack - DataLab.

Casos de uso do Haystack

Abordamos os conceitos básicos da estrutura de IA do Haystack. A próxima etapa da sua jornada de aprendizado é criar um aplicativo de IA totalmente funcional. Aqui estão alguns dos casos de uso que os desenvolvedores estão explorando:

1. IA multimodal: Desenvolver sistemas que processem e integrem vários tipos de entrada, inclusive texto e imagens, para aplicativos como legendas de imagens, transcrição de áudio e geração de imagens.
2. IA de conversação: Forneça interfaces de bate-papo para chatbots dinâmicos e de várias voltas que possam se envolver em conversas significativas.
3. Pipelines autênticos: Use chamadas funcionais para permitir que os modelos de linguagem interajam com ferramentas e acessem recursos externos.
4. RAG avançado: Combine a recuperação de documentos com a geração baseada em LLM para implementar uma variedade de estratégias de recuperação e geração.
5. Integração de ferramentas MCP: Conecte perfeitamente os LLMs com ferramentas externas, APIs e fontes de dados usando o Protocolo de contexto de modelo.
6. Avaliação do modelo: Avalie a precisão, a relevância e a confiabilidade dos pipelines.
7. Aplicativos multiagentes: Crie sistemas em que vários agentes colaborem efetivamente para resolver tarefas complexas e de várias etapas.

Considerações finais

Tendo trabalhado com muitas estruturas de LLM, considero o Haystack uma das opções mais intuitivas e flexíveis disponíveis. Ele é mais natural de usar, menos complexo e oferece maior controle sobre seus fluxos de trabalho. 

Um de seus recursos de destaque é a facilidade com que você pode criar componentes personalizados para seus pipelines, tornando-o altamente adaptável a uma ampla gama de casos de uso.

Gostei especialmente de experimentar agentes e ferramentas e entender como invocar cada um deles de forma eficaz. Trabalhar com o prompt do sistema me ajudou a entender como usar as ferramentas individualmente e em sequência. 

Além disso, o prompt do sistema pode ser facilmente personalizado para incluir detalhes adicionais, como a exibição de fontes e IDs de documentos, que podem ser importantes para o seu aplicativo.

Se você ainda não conhece o mundo dos agentes de IA, confira os recursos abaixo para saber mais: 

• Compreensão dos agentes de IA 
• Tipos de agentes de IA 
• Estruturas de agentes de IA 
• Tutorial do Agentic RAG com projeto de demonstração
• Guia do N8n com exemplos práticos