Projeto de Agentes Inteligentes: desenvolvimento com LangChain, LangGraph e LangSmith

Estruturando um projeto com LLMs - Apresentação do curso

Apresentando o curso e objetivos do módulo

Olá. Meu nome é Alan Braz. Hoje, estamos aqui para discutir o terceiro módulo deste curso de formação de agentes, no qual realizaremos um projeto prático utilizando as três ferramentas do LangChain: o próprio LangChain, o LangGraph e o LangSmith.

Nos módulos anteriores, fizemos uma introdução ao LangChain e ao HAG. Agora, vamos adentrar o mundo dos agentes e dos multiagentes. Nosso foco será o ecossistema do LangChain, que está bastante completo, e exploraremos detalhadamente o código e a configuração dessas três ferramentas.

Desenvolvendo um projeto de ponta a ponta

Nosso objetivo é desenvolver um projeto de ponta a ponta, começando com o LangChain, evoluindo para o LangGraph, monitorando tudo com o LangSmith, conectando ferramentas externas, configurando a memória e testando o agente em funcionamento. Além disso, incluiremos outro subagente para criar uma pequena arquitetura de multiagentes e concluiremos este módulo executando tudo isso.

Para começar, vamos examinar o ecossistema do LangChain. Na tela, já acessamos o site oficial do LangChain. Observamos que a mensagem inicial mudou. O LangChain começou como um encadeador de uso para LLMs (Large Language Models, ou Modelos de Linguagem Grande), realizando tanto o pré-processamento dos prompts quanto o pós-processamento das saídas do modelo LLM. Essa cadeia simples já foi abordada em outros módulos, mas agora o foco está totalmente em agentes.

Explorando o LangSmith e sua importância

Vamos analisar o que eles indicam. Primeiramente, destacam o LangSmith, que é a parte mais importante. Não adianta termos um agente se não conseguimos observar suas ações, os prompts, as ferramentas que ele utiliza, quando as utiliza, quais entradas fornece a essas ferramentas e o consumo de tokens na solução. É essencial monitorar o uso de tokens, pois agentes invocam LLMs frequentemente, e o contexto entre ferramentas e memória pode aumentar significativamente o consumo de tokens. Uma chamada simples pode facilmente escalar de 200 tokens de entrada para 2.000, 15.000 ou até 20.000 tokens em uma única chamada.

Portanto, o LangSmith é a ferramenta mais crucial entre as três. O LangChain encadeia, o LangGraph configura o agente e seu fluxo, mas, como mencionado, sem observação, podemos nos perder facilmente. O LLM já é uma caixa preta, e, sem cuidado, esses sistemas também podem se tornar caixas pretas. O LangSmith é essencial para a observabilidade, rastreando todas as chamadas dentro do sistema, avaliação e deployment. Ele também possui o AgentBuilder, que permite construir agentes de forma no-code mais visual. No entanto, neste curso, focaremos em muito código.

Revisando os frameworks do ecossistema LangChain

Antes de explorar o LangSmith, vamos revisar as diferenças entre os frameworks deste ecossistema do LangChain.

O LangChain serve para orquestrarmos o modelo, chamá-lo, fazer o pedido e configurar os prompts. O LangGraph é responsável por criar agentes customizados em baixo nível. Vamos definir o grafo do agente, que é representado por um desenho com um nó de início. Um grafo possui três componentes principais: a memória, que armazena o estado de tudo o que está acontecendo naquele grafo, naquela chamada, naquele fluxo; os nós, que são os componentes, como o nó de início e fim, além de outros três nós que podem ser tanto chamadas a LLM quanto chamadas a ferramentas; e as arestas, que conectam e fazem a lógica do grafo.

Vamos criar um exemplo de grafo manualmente usando código Python, com o LangChain e o LangGraph, e visualizá-lo no LangSmith. Existe também um componente novo chamado DeepAgents, que não abordaremos aqui, mas a documentação do LangChain é muito completa. Recomendamos que todos consultem, pois é essencial que nós, como pessoas desenvolvedoras, saibamos ler a documentação dos frameworks que utilizamos. Além de escolher os frameworks, é importante saber ler a documentação, e o LangChain possui uma das melhores e mais completas documentações.

Focando na documentação e no caso de uso

Ao acessar a documentação, podemos escolher entre Python e TypeScript, mas focaremos em Python. A documentação aborda o LangChain, o LangGraph, observabilidade, avaliação, prompt e deployment do LangSmith. Vamos nos concentrar na parte de observabilidade. O AgentBuilder, que não abordaremos, possui muitos tutoriais e materiais para começar a desenvolver por conta própria. Embora a documentação não esteja disponível em português, é possível traduzir com o Google Tradutor do navegador.

Nosso caso de uso será simular um chatbot, um agente para um pet shop. Utilizamos a ferramenta A para gerar o prospecto do nosso pet shop, chamado Mundo Animalha. Vamos criar um RAG (Retrieval-Augmented Generation) que incluirá informações como nome, endereço, lojas, produtos vendidos, programa de fidelidade, políticas de troca e cancelamento. Este documento seria semelhante ao informativo de um site de pet shop, incluindo perguntas e respostas (FAQ).

Criando o agente do Mundo Animalha

Vamos criar o agente do Mundo Animalha, que consumirá essas informações via RAG, evoluindo o que aprendemos nas lições anteriores. Também adicionaremos algumas ferramentas ao agente, como uma de busca na internet para simular a ferramenta interna do pet shop que teria o catálogo de produtos. Além disso, conectaremos outra ferramenta, que será nosso catálogo de clientes, permitindo que clientes verifiquem seus pontos no programa de fidelidade para trocas por produtos.

Este será nosso caso de uso fictício de atendimento ao cliente, monitorado pelo LangSmith e orquestrado pelo LangChain e LangGraph. Vamos começar a configurar nosso ambiente.

Estruturando um projeto com LLMs - Configurando o ambiente de desenvolvimento

Configurando o ambiente de desenvolvimento

Vamos começar configurando nosso ambiente. Abrimos o VSCode, criamos uma nova pasta e faremos tudo do zero, passo a passo. O primeiro passo é instalar as dependências necessárias. Vamos abrir um novo terminal. Estamos na pasta "código". A primeira coisa é verificar a versão do Python que estamos utilizando. Estamos na versão 3.13, sendo que o mínimo necessário é 3.11 ou 3.12. A versão 3.12 é a indicada.

Para verificar a versão do Python, podemos usar o seguinte comando:

python -V

Instalando o gerenciador de pacotes uv

Vamos utilizar um gerenciador de pacotes, e ao invés do pip, usaremos o uv. Vamos verificar se está instalado. Caso não esteja, instalaremos. Não é conhecido, então vamos instalar o uv. Além disso, vamos criar um README para documentar todos os passos, transformando-o em um tutorial. O primeiro passo é ter o Python maior que 3.11 e instalar o gerenciador de pacotes. O uv é um instalador novo, substituindo o pip por ser mais rápido. Vamos colocar o comando e formatá-lo adequadamente.

Para instalar no PowerShell do Windows, basta executar o comando:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Houve um problema de segurança no PowerShell, pois o usuário não estava autorizado. Copiamos o comando sugerido, autorizamos e rodamos o comando para instalar o uv. Após a instalação, verificamos a versão com:

uv --version

Criando e configurando o ambiente virtual

Precisamos também configurar a variável de ambiente, que foi um passo pulado anteriormente. Com o uv instalado, podemos começar a configurar nosso ambiente.

A primeira coisa é criar um arquivo para guardar as variáveis de ambiente, o famoso .env. Vamos criar um arquivo .env vazio. Em Python, para carregar esse arquivo, utilizaremos a biblioteca loadenv. O primeiro pacote a ser instalado será:

uv add python-loadenv

Como não há projeto, precisamos criar um com o uv. Primeiramente, criaremos um ambiente virtual, pois não queremos instalar as coisas na própria máquina. É recomendado criar um ambiente virtual para cada projeto. Executaremos o comando:

uv venv .venv

Isso cria o ambiente virtual, e indicaremos que ele seja criado no .venv.

Ativando o ambiente virtual e instalando pacotes

É interessante iniciar esses arquivos locais com um ponto, pois eles são arquivos ocultos no sistema operacional e, ao subir no GitHub, podemos ignorá-los facilmente. Para ativar o ambiente, o comando é fornecido:

.venv\Scripts\activate

No PowerShell, pode ser necessário um comando adicional, mas funcionou. Agora, tentaremos adicionar o Python. Se o venv não estiver disponível, executamos:

uv init

Isso inicializa o ambiente. Se o pacote não for adicionado, pode ter mudado de nome. Vamos pesquisar. Outra coisa importante é apontar o ambiente que rodará o arquivo Python.

Para instalar o pacote, utilizamos o python-dotenv, que serve para ler o arquivo .env. O comando que executamos foi:

uv add python-dotenv

Criando o arquivo Python e importando bibliotecas

Inicialmente, criamos o ambiente virtual com uv. Vamos documentar os passos corretamente para que possamos replicá-los. Antes de tudo, foi necessário adicionar o uv ao path do Windows. Após isso, iniciamos e ativamos o ambiente virtual, permitindo que instalemos pacotes dentro dele. Em seguida, executamos uv init e instalamos o pacote uv add python-dotenv.

Após a instalação do pacote .env, podemos criar nosso primeiro arquivo Python, que chamaremos de agente.py. A primeira ação nesse arquivo é importar o módulo os:

import os

É importante, ao trabalhar com ambientes virtuais, apontar o VS Code para o ambiente virtual do projeto, pois as dependências e o autocomplete serão específicos para aquele projeto. O VS Code já está carregando o Python criado pelo uv no ambiente virtual.

Carregando variáveis de ambiente e testando

Vamos importar a funcionalidade de carregar variáveis de ambiente. Do pacote .env, que acabamos de instalar, importamos o load_dotenv:

from dotenv import load_dotenv

Para inicializar, basta executar:

load_dotenv()

Este arquivo Python, por enquanto, não realiza nenhuma ação. Podemos executá-lo, mas ele não fará nada efetivo. Para testar, criaremos uma variável TEST=langchain no arquivo .env. Em seguida, faremos um print com os.getenv para imprimir essa variável, apenas para verificar se está funcionando:

print(os.getenv("TEST", "vazio"))

Se quisermos definir um valor padrão caso a variável não esteja definida, podemos especificar um valor vazio. Ao executar, ele imprime langchain. Se tentarmos acessar uma variável inexistente, como TEST2, ele imprimirá vazio:

print(os.getenv("TEST2", "vazio"))

Isso confirma que o ambiente está configurado para começarmos a programar nosso agente.

Utilizando a biblioteca rich para impressão

Outra biblioteca do Python que apreciamos é a rich, que facilita a impressão de dados de forma mais legível. Quando lidamos com JSON ou dados mais complexos, ela imprime no terminal de forma organizada, o que ajuda na depuração. No terminal, executamos:

uv add rich

Do rich, importamos o print, que substitui o comando print padrão do Python, tornando a saída mais bonita:

from rich import print

Embora não haja diferença visível com o print atual, ao lidarmos com JSON, ele será impresso com quebras de linha, cores e tabulação, facilitando a visualização.

Concluindo a configuração do ambiente

Com o ambiente configurado, podemos começar a implementar nossos passos com langchain, langgraph, langsmith, configurar e evoluir até completarmos nosso agente.

Estruturando um projeto com LLMs - Selecionando o LLM para o projeto

Escolhendo o modelo de linguagem e provedor

Para criar qualquer agente, a primeira etapa é escolher qual modelo de linguagem será utilizado e de qual provedor. O padrão é chamarmos a API da OpenAI e utilizarmos o modelo do GPT no código para ser nosso motor, nosso LLM (Modelo de Linguagem Grande) dos agentes e do próprio LangChain. No entanto, a OpenAI não oferece mais uma camada gratuita, então, para usar a API da OpenAI, precisaríamos adicionar pelo menos 5 dólares de crédito. Contudo, isso não é mais necessário, pois atualmente existem vários provedores que permitem o uso sem a necessidade de cartão de crédito ou crédito pré-pago, oferecendo uma ampla cota de modelos para testes e desenvolvimentos.

Para um projeto real em produção, a empresa responsável terá a conta, os créditos e decidirá se utilizará o Gemini, o Copilot, a OpenAI, o Bedrock ou qualquer outro provedor. Neste tutorial, como queremos realizar tudo de forma gratuita, utilizaremos um provedor chamado Grok. Este provedor oferece uma camada gratuita com vários modelos disponíveis. Vamos criar uma conta no Grok, fazer login com uma conta do Google e mostrar o processo desde o início. O Grok cria a organização e o Playground sem a necessidade de cartão de crédito, e suas APIs são compatíveis com as da OpenAI, o que facilita a troca de provedores.

Explorando provedores alternativos e configurando variáveis de ambiente

O LangChain é vantajoso porque suporta uma infinidade de provedores de modelos, permitindo trocas fáceis. Além do Groq, existe outro provedor gratuito chamado OpenRouter. No OpenRouter AI, podemos obter uma chave de API para explorar vários modelos sem custos iniciais. É necessário criar uma chave de API, nomeá-la com o código do curso, que é 5596, e definir que ela não expirará. Essa chave será usada apenas para este propósito, e será copiada para o VS Code, onde criaremos uma variável de ambiente com o nome groq_API_key. Este nome é padrão, então, ao invocar o LangChain, ele já reconhecerá a variável sem necessidade de declaração adicional.

Para começar, vamos configurar nosso ambiente para utilizar essas variáveis. Primeiro, precisamos carregar as variáveis de ambiente. Para isso, utilizamos o seguinte código:

import os
from dotenv import load_dotenv
from rich import print

load_dotenv()

print(os.getenv("TEST", "vazio"))

Esse trecho de código carrega as variáveis de ambiente definidas em um arquivo .env e imprime o valor da variável TEST, que inicialmente está definida como "vazio".

Configurando o ambiente e verificando limites do provedor

Após configurar a conta no provedor de LLM, que será o Groq, e inserir a chave, o código do agente já estará lendo as chaves automaticamente. Não será necessário realizar ajustes adicionais. Para verificar qual modelo será utilizado e qual é a cota disponível, acessaremos as configurações do Groq e verificaremos os limites. O Groq lista todos os modelos disponíveis, indicando quantos pedidos por minuto e por dia podem ser feitos, além de quantos tokens por minuto e por dia são permitidos. A cota do Groq é bastante generosa, permitindo que realizemos o tutorial completo sem preocupações.

Agora, vamos definir as variáveis de ambiente necessárias no nosso arquivo .env:

GROQ_API_KEY=COLE SUA CHAVE AQUI
GROQ_MODEL=groq/compound

Instalando bibliotecas e instanciando o modelo de linguagem

Com essas variáveis configuradas, podemos prosseguir para a instalação das bibliotecas necessárias. Primeiro, instalamos o LangChain:

uv add langchain

Em seguida, instalamos a biblioteca específica para o Groq:

uv add langchain langchain-groq

Com as bibliotecas instaladas, podemos importar o módulo necessário para interagir com o Grok:

from langchain_groq import ChatGroq

Agora, precisamos instanciar o modelo de linguagem. Vamos criar uma instância do ChatGroq, passando o modelo que ele usará, que será obtido do ambiente:

llm = ChatGroq(model=os.getenv("GROQ_MODEL"))

Podemos agora invocar o modelo com uma entrada simples para verificar se tudo está funcionando corretamente:

print(llm.invoke("olá ia"))

Executando o script e configurando observabilidade

Para executar o script e verificar se tudo está configurado corretamente, utilizamos o seguinte comando:

uv run -- python .\agente.py

Agora que já chamamos nosso modelo e escolhemos o provedor, a primeira etapa importante está concluída. A próxima etapa é configurar o LangSmith para rastrear e observar o que acontece nas chamadas de LLMs, antes de encadear e complexificar o código. Vamos adicionar essa parte de observabilidade agora, para acompanhar o que está acontecendo desde o início.

Sobre o curso Projeto de Agentes Inteligentes: desenvolvimento com LangChain, LangGraph e LangSmith

O curso Projeto de Agentes Inteligentes: desenvolvimento com LangChain, LangGraph e LangSmith possui 156 minutos de vídeos, em um total de 32 atividades. Gostou? Conheça nossos outros cursos de IA para Dados em Inteligência Artificial, ou leia nossos artigos de Inteligência Artificial.

Matricule-se e comece a estudar com a gente hoje! Conheça outros tópicos abordados durante o curso:

• capitulo