Vamos analisar essas partes essenciais do LlamaIndex e como elas auxiliam na criação de agentes:
- Componentes: São os blocos básicos de construção que você utiliza no LlamaIndex. Incluem elementos como prompts, modelos e bancos de dados. Os componentes geralmente ajudam a conectar o LlamaIndex com outras ferramentas e bibliotecas.
- Ferramentas: As ferramentas são componentes que oferecem funcionalidades específicas, como busca, cálculos ou acesso a serviços externos. Elas são os blocos que permitem aos agentes executar tarefas.
- Agentes: Os agentes são componentes autônomos que podem utilizar ferramentas e tomar decisões. Eles coordenam o uso das ferramentas para alcançar objetivos complexos.
- Fluxos de Trabalho: São processos passo a passo que organizam a lógica de execução. Os fluxos de trabalho, ou fluxos agentivos, são uma forma de estruturar o comportamento agentivo sem a necessidade de usar agentes explicitamente.
O que torna o LlamaIndex especial?
Embora o LlamaIndex realize algumas tarefas semelhantes a outros frameworks, como o smolagents, ele oferece alguns benefícios importantes:
- Sistema de fluxo de trabalho claro: Os fluxos de trabalho ajudam a dividir o processo de tomada de decisão dos agentes em etapas, utilizando uma sintaxe orientada a eventos e focada em execução assíncrona. Isso facilita a composição e organização da lógica de forma clara.
- Análise avançada de documentos com o LlamaParse: O LlamaParse foi desenvolvido especificamente para o LlamaIndex, o que garante uma integração perfeita — embora seja um recurso pago.
- Diversos componentes prontos para uso: O LlamaIndex já está no mercado há algum tempo, o que o tornou compatível com muitos outros frameworks. Isso significa que ele conta com uma variedade de componentes testados e confiáveis, como LLMs, recuperadores, índices e mais.
- LlamaHub: é um repositório com centenas desses componentes, agentes e ferramentas que você pode utilizar dentro do LlamaIndex.
Todos esses conceitos são necessários em diferentes cenários para criar agentes realmente úteis. Nas próximas seções, vamos explorar cada um desses conceitos em detalhes.
Introdução ao LlamaHub
O LlamaHub é um repositório com centenas de integrações, agentes e ferramentas que você pode utilizar dentro do LlamaIndex. Usaremos diversas integrações, então vamos começar conhecendo o LlamaHub e como ele pode nos ajudar.
Vamos ver como encontrar e instalar as dependências dos componentes que precisamos.
Instalação
As instruções para instalar o LlamaIndex estão disponíveis no LlamaHub em um formato bem organizado. Isso pode parecer um pouco complexo no início, mas a maioria dos comandos de instalação segue um padrão fácil de lembrar:
pip install llama-index-{component-type}-{framework-name}Vamos tentar instalar as dependências para um componente de LLM e embeddings usando a integração da API do Google Gemini.
!pip install llama-index-embeddings-gemini --quiet
!pip install llama-index-llms-google-genai --quiet
!pip install llama-index 'google-generativeai>=0.3.0' --quiet
!pip install llama-index-vector-stores-chroma --quiet
!pip install python-bcb --quietUso
Uma vez instaladas as dependências, podemos observar os padrões de uso. Você vai notar que os caminhos de importação seguem o comando de instalação! Abaixo, temos um exemplo de uso da API do Gemini para um componente LLM.
O que são componentes no LlamaIndex?
Lembra da Dona Cida, nossa agente prestativo? Para nos ajudar de forma eficaz, a Dona Cida precisa entender nossos pedidos e preparar, encontrar e usar informações relevantes para ajudar a completar as tarefas. É aí que entram os componentes do LlamaIndex.
Embora o LlamaIndex possua muitos componentes, vamos focar especificamente no componente QueryEngine. Por quê? Porque ele pode ser usado como uma ferramenta de Retrieval-Augmented Generation (RAG) para um agente.
Mas, o que é RAG? Os LLMs são treinados com enormes volumes de dados para aprender conhecimentos gerais. No entanto, eles podem não estar treinados com dados relevantes e atualizados. O RAG resolve esse problema encontrando e recuperando informações relevantes dos seus dados e fornecendo isso ao LLM.
Agora, pense em como a Dona Cida funciona funciona:
- Você pede para a Dona Cida ajudar a planejar uma festa de jantar
- A Dona Cida precisa consultar sua agenda, preferências alimentares e menus anteriores que foram um sucesso
- O QueryEngine ajuda a Dona Cida a encontrar essas informações e usá-las para planejar a festa
Isso torna o QueryEngine um componente fundamental para construir fluxos de trabalho agentivos com RAG no LlamaIndex. Assim como a Dona Cida precisa buscar informações da sua casa para ser útil, qualquer agente precisa de uma forma de encontrar e entender dados relevantes. O QueryEngine oferece exatamente essa capacidade.
Agora, vamos nos aprofundar um pouco mais nos componentes e ver como você pode combiná-los para criar um pipeline RAG.
Criando um pipeline RAG usando componentes
Existem cinco etapas principais dentro do RAG, que fazem parte da maioria das aplicações maiores que você construir. São elas:
- Carregamento (Loading): refere-se a obter seus dados de onde eles estão — seja arquivos de texto, PDFs, outro site, um banco de dados ou uma API — para dentro do seu fluxo de trabalho. O LlamaHub oferece centenas de integrações para escolher.
- Indexação (Indexing): significa criar uma estrutura de dados que permita consultar os dados. Para LLMs, isso quase sempre envolve criar embeddings vetoriais, que são representações numéricas do significado dos dados. Indexação também pode se referir a outras estratégias de metadados para facilitar encontrar dados contextualmente relevantes com base em propriedades.
- Armazenamento (Storing): uma vez que seus dados estejam indexados, você vai querer armazenar seu índice, assim como outros metadados, para evitar precisar reindexar tudo.
- Consulta (Querying): para qualquer estratégia de indexação, há várias maneiras de utilizar LLMs e estruturas de dados do LlamaIndex para realizar consultas, incluindo subconsultas, consultas em múltiplas etapas e estratégias híbridas.
- Avaliação (Evaluation): uma etapa crítica em qualquer fluxo é verificar o quão eficaz ele é em comparação com outras estratégias, ou quando você faz alterações. A avaliação fornece medidas objetivas de quão precisas, fiéis e rápidas são suas respostas às consultas.
A seguir, vamos ver como podemos reproduzir essas etapas usando componentes.
Carregamento e incorporação de documentos
Como mencionado antes, o LlamaIndex pode trabalhar sobre seus próprios dados, porém, antes de acessar esses dados, precisamos carregá-los. Existem três formas principais de carregar dados no LlamaIndex:
- SimpleDirectoryReader: um carregador embutido para vários tipos de arquivo a partir de um diretório local.
- LlamaParse: ferramenta oficial do LlamaIndex para análise de PDFs, disponível como uma API gerenciada.
- LlamaHub: um repositório com centenas de bibliotecas para carregamento de dados, que permitem ingerir dados de qualquer fonte.
A forma mais simples de carregar dados é usando o SimpleDirectoryReader. Esse componente versátil pode carregar diversos tipos de arquivo de uma pasta e convertê-los em objetos Document que o LlamaIndex pode manipular. Vamos ver como usar o SimpleDirectoryReader para carregar dados de uma pasta.
reader = SimpleDirectoryReader(input_dir = "dados")
documents = reader.load_data()Após carregar nossos documentos, precisamos dividi-los em pedaços menores chamados objetos Node. Um Node é apenas um trecho de texto do documento original, mais fácil para a IA trabalhar, mas que ainda mantém referências ao objeto Document original.
O IngestionPipeline nos ajuda a criar esses nodes por meio de duas transformações principais:
- SentenceSplitter: divide os documentos em pedaços gerenciáveis, separando-os em limites naturais de sentenças.
- HuggingFaceEmbedding: converte cada pedaço em embeddings numéricos — representações vetoriais que capturam o significado semântico de forma que a IA possa processar eficientemente.
Esse processo nos ajuda a organizar os documentos de um jeito mais útil para buscas e análises.
Armazenamento e indexação de documentos
Depois de criarmos nossos objetos Node, precisamos indexá-los para que se tornem pesquisáveis. Mas, antes disso, é necessário ter um local onde armazenar esses dados.
Como estamos utilizando um ingestion pipeline, podemos anexar diretamente um vector store ao pipeline para preenchê-lo com os dados processados. Neste caso, usaremos o Chroma para armazenar nossos documentos.
Vamos ver como criar esse índice a partir do nosso vector store e dos embeddings:
index = VectorStoreIndex.from_vector_store(vector_store, embed_model = embed_model)Todas as informações são automaticamente persistidas dentro do objeto ChromaVectorStore e no diretório especificado.
Ótimo! Agora que podemos salvar e carregar nosso índice com facilidade, vamos explorar como consultá-lo de diferentes maneiras.
Consultando um VectorStoreIndex com prompts e LLMs
Antes de podermos consultar nosso índice, precisamos convertê-lo em uma interface de consulta. As opções mais comuns de conversão são:
as_retriever: para recuperação básica de documentos, retornando uma lista de objetosNodeWithScorecom pontuações de similaridade.as_query_engine: para interações de pergunta e resposta única, retornando uma resposta textual.as_chat_engine: para interações conversacionais que mantêm memória ao longo de múltiplas mensagens, retornando uma resposta textual com base no histórico de conversa e no contexto indexado.
Vamos focar no query engine, pois ele é o mais comum em interações do tipo agente. Também passamos um LLM para o query engine, que será usado para gerar a resposta.
Processamento de Respostas
Nos bastidores, o query engine não utiliza apenas o LLM para responder à pergunta — ele também usa um ResponseSynthesizer como estratégia para processar a resposta. Essa estratégia é totalmente personalizável, mas há três abordagens principais que funcionam bem por padrão:
- refine: cria e refina uma resposta passando sequencialmente por cada trecho de texto recuperado. Faz uma chamada separada ao LLM para cada Node/trecho recuperado.
- compact (padrão): semelhante ao refine, mas concatena os trechos antes, resultando em menos chamadas ao LLM.
- tree_summarize: gera uma resposta detalhada ao percorrer cada trecho de texto recuperado e construir uma estrutura em árvore da resposta.
O modelo de linguagem nem sempre terá um comportamento previsível, então não podemos ter certeza de que a resposta gerada será sempre correta. Podemos lidar com isso avaliando a qualidade da resposta.
Avaliação e observabilidade
O LlamaIndex oferece ferramentas integradas de avaliação para medir a qualidade das respostas. Esses avaliadores utilizam LLMs para analisar as respostas em diferentes dimensões. Vamos conhecer os três principais avaliadores disponíveis:
- FaithfulnessEvaluator: avalia a fidelidade da resposta, verificando se ela é sustentada pelo contexto fornecido.
- AnswerRelevancyEvaluator: avalia a relevância da resposta, verificando se ela realmente responde à pergunta feita.
- CorrectnessEvaluator: avalia a exatidão da resposta, verificando se a informação apresentada está correta.
Essas ferramentas ajudam a monitorar, ajustar e melhorar o desempenho dos seus agentes com base em métricas objetivas.
evaluator = FaithfulnessEvaluator(llm = llm)
eval_result = evaluator.evaluate_response(response = response)
eval_result.passingMesmo sem uma avaliação direta, podemos obter insights sobre o desempenho do nosso sistema por meio da observabilidade. Isso é especialmente útil quando estamos construindo fluxos de trabalho mais complexos e queremos entender como cada componente está se comportando.
Já vimos como usar componentes para criar um QueryEngine. Agora, vamos ver como podemos utilizar o QueryEngine como uma ferramenta para um agente!
Usando ferramentas no LlamaIndex
Definir um conjunto claro de ferramentas (Tools) é essencial para um bom desempenho. Como discutimos previamente, interfaces de ferramentas bem definidas são mais fáceis para os LLMs utilizarem. Assim como uma API de software facilita a vida de engenheiros humanos, um LLM consegue aproveitar melhor uma ferramenta quando é fácil entender como ela funciona.
Existem quatro tipos principais de ferramentas no LlamaIndex:
- FunctionTool: Converte qualquer função Python em uma ferramenta que o agente pode usar. O LLM entende automaticamente como a função funciona a partir da sua assinatura e docstring.
- QueryEngineTool: Permite que agentes utilizem query engines como ferramentas. Como os próprios agentes podem ser construídos sobre query engines, isso significa que um agente pode usar outros agentes como ferramentas.
- Toolspecs: Conjuntos de ferramentas criados pela comunidade, geralmente voltados para serviços específicos, como Gmail, Google Drive, entre outros. Facilitam a reutilização e integração de serviços externos.
- Utility Tools: Ferramentas especiais que ajudam a lidar com grandes volumes de dados vindos de outras ferramentas. Elas são úteis para dividir, agrupar ou processar informações de forma mais eficiente.
A seguir, vamos explorar a FunctionTool com mais detalhes.
Criando uma FunctionTool
Uma FunctionTool oferece uma maneira simples de encapsular qualquer função Python e disponibilizá-la para um agente. É possível passar uma função síncrona ou assíncrona para a ferramenta, junto com parâmetros opcionais como nome e descrição.
O nome e a descrição são especialmente importantes, pois ajudam o agente a entender quando e como usar a ferramenta de forma eficaz.
Vamos ver abaixo como criar uma FunctionTool e depois chamá-la.
Usando Agentes no LlamaIndex
Lembra da Dona Cina?, nosso agente prestativa? Pois bem, ela está prestes a receber uma atualização! Agora que entendemos as ferramentas disponíveis no LlamaIndex, podemos dar a Dona Cida novas capacidades para nos atender ainda melhor.
Mas antes de prosseguirmos, vamos relembrar o que faz um agente funcionar. Previamente, aprendemos que:
Um Agente é um sistema que utiliza um modelo de IA para interagir com seu ambiente com o objetivo de alcançar uma meta definida pelo usuário. Ele combina raciocínio, planejamento e execução de ações (geralmente por meio de ferramentas externas) para realizar tarefas.
O LlamaIndex oferece suporte a três tipos principais de agentes com raciocínio:
- Function Calling Agents – Trabalham com modelos de IA que conseguem chamar funções específicas diretamente. São úteis quando queremos que o agente execute ações bem definidas, como consultar um calendário ou calcular algo com precisão.
- ReAct Agents – Podem trabalhar com qualquer modelo de IA que aceite entrada via chat ou texto. Eles são capazes de realizar tarefas de raciocínio mais complexas, alternando entre pensar (Reasoning) e agir (Acting). Isso os torna ideais para cenários onde o agente precisa planejar e tomar decisões em várias etapas.
- Advanced Custom Agents – Utilizam abordagens mais sofisticadas para lidar com tarefas e fluxos de trabalho ainda mais complexos. Permitem maior controle sobre o comportamento do agente e costumam ser altamente configuráveis, ideais para casos de uso específicos ou empresariais.
Inicializando Agentes
Para criar um agente, começamos fornecendo a ele um conjunto de funções/ferramentas que definem suas capacidades. Vamos ver como criar um agente com algumas ferramentas básicas. No momento em que este material foi escrito, o agente usará automaticamente a API de chamada de funções (function calling), se estiver disponível, ou então um loop padrão de agente ReAct.
Os LLMs que suportam APIs de ferramentas/funções são relativamente novos, mas oferecem uma forma poderosa de chamar ferramentas sem depender de promptings específicos. Eles permitem que o LLM gere chamadas de ferramentas com base em esquemas definidos.
Por outro lado, os agentes ReAct também são muito eficazes em tarefas que exigem raciocínio complexo e funcionam com qualquer LLM que ofereça recursos de chat ou conclusão de texto. Eles tendem a ser mais verbosos, mostrando passo a passo o raciocínio por trás das ações que executam.
agent = AgentWorkflow.from_tools_or_functions(
tools_or_functions = [tool],
llm = llm
)Agentes são, por padrão, sem estado (stateless), mas é possível habilitar a lembrança de interações passadas de forma opcional, utilizando um objeto chamado Context.
Isso pode ser útil, por exemplo, se você quiser usar um agente que precise lembrar de interações anteriores — como um chatbot que mantém o contexto ao longo de várias mensagens ou um gerenciador de tarefas que precisa acompanhar o progresso ao longo do tempo.
Você vai notar que os agentes no LlamaIndex são async (assíncronos), pois utilizam o operador await do Python.
Se você é novo em programação assíncrona em Python — ou precisa de uma revisão — eles oferecem um excelente guia sobre o assunto.
Quer aprender mais?
Conheça nossa Formação do Zero à Análise de Dados Econômicos e Financeiros usando Python e Inteligência Artificial. Aprenda do ZERO a coletar, tratar, construir modelos e apresentar dados econômicos e financeiros com o uso de Python e IA.
