Autor: Priya Sharma – Arquiteta de API e Consultora em Integração de IA
A capacidade de criar sistemas inteligentes capazes de entender instruções, raciocinar e agir de maneira autônoma transforma nossa interação com a tecnologia. No centro dessa transformação estão os agentes de IA – entidades de software projetadas para realizar tarefas utilizando o poder dos Large Language Models (LLMs) e ferramentas externas. Embora o conceito possa parecer complexo, frameworks como o LangChain simplificaram consideravelmente o processo de desenvolvimento, tornando a criação de agentes acessível a um público mais amplo.
Como arquiteta API e consultora em integração de IA, vi com meus próprios olhos o incrível potencial de agentes de IA bem projetados. Eles podem automatizar fluxos de trabalho complexos, fornecer assistência personalizada e desbloquear novas capacidades para empresas e indivíduos. Este guia prático irá guiá-lo pelo processo de construção de agentes de IA robustos usando a API LangChain, desde a compreensão dos componentes principais até a implementação de exemplos práticos e concretos. Ao final, você terá uma base sólida para projetar e implantar seus próprios agentes inteligentes, prontos para enfrentar uma infinidade de desafios.
Compreendendo os Agentes de IA e o Papel do LangChain
Antes de explorar o código, vamos esclarecer o que é um agente de IA e por que o LangChain é uma ferramenta indispensável para sua construção. Um agente de IA é um sistema que utiliza um LLM como seu “cérebro” para decidir quais ações tomar. Ao contrário de uma simples chamada LLM que gera uma única resposta, um agente pode se engajar em um processo de raciocínio em várias etapas:
- Perceber: Compreender a entrada do usuário ou o estado atual.
- Raciocinar: Determinar o melhor curso de ação com base em sua compreensão e nas ferramentas disponíveis.
- Agir: Executar uma ou mais ações utilizando ferramentas externas.
- Aprender (opcional, mas poderoso): Incorporar feedbacks para melhorar o desempenho futuro.
O LangChain fornece a estrutura necessária para construir esses agentes sofisticados. Ele oferece um método estruturado para conectar os LLMs a várias fontes de dados e ferramentas computacionais, permitindo que eles vão além da simples geração de texto. Pense no LangChain como o sistema operacional do seu agente de IA, fornecendo a estrutura para sua inteligência, memória e capacidade de interagir com o mundo.
Componentes Chave de um Agente LangChain
Para construir um agente com LangChain, você trabalhará principalmente com estes componentes essenciais:
- Large Language Model (LLM): O núcleo da inteligência. Isso pode ser os modelos GPT da OpenAI, Claude da Anthropic, ou alternativas de código aberto. O LLM processa as entradas, raciocina e produz decisões.
- Ferramentas: Funções que o agente pode chamar para interagir com sistemas externos ou realizar cálculos específicos. Exemplos incluem a pesquisa na Internet, consulta a um banco de dados, chamada de uma calculadora ou interação com uma API personalizada.
- Coleção de Ferramentas: Coleções de ferramentas relacionadas projetadas para casos de uso específicos (ex: um “kit de ferramentas Wikipedia” ou um “kit de ferramentas agente CSV”).
- Executor do Agente: O ambiente de execução que orquestra as ações do agente. Ele toma as decisões do LLM, executa as ferramentas escolhidas e devolve os resultados ao LLM para um raciocínio posterior.
- Memória: Permite que o agente mantenha informações de interações anteriores, permitindo conversas coerentes em várias rodadas e uma tomada de decisão contextual.
- Modelos de Prompt: Definem como a entrada do usuário e outras informações são formatadas para o LLM, guiando seu processo de raciocínio.
Configurar Seu Ambiente e Primeiros Passos
Antes de escrever o código do agente, certifique-se de que seu ambiente Python está pronto. Você precisará do Python 3.8+ e da biblioteca LangChain, assim como de qualquer fornecedor de LLM que você pretenda utilizar.
Instalação
Instale o LangChain e um fornecedor de LLM (ex: OpenAI):
pip install langchain langchain-openai
pip install python-dotenv # Para gerenciar as chaves API de forma seguraGerencie suas chaves API de forma segura. Crie um arquivo .env na raiz do seu projeto:
OPENAI_API_KEY="sua_chave_api_openai_aqui"Em seguida, carregue-o em seu script Python:
import os
from dotenv import load_dotenv
load_dotenv()
os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY")Interação Básica com o LLM
Para confirmar sua configuração, vamos fazer uma simples chamada ao LLM:
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
llm = ChatOpenAI(model="gpt-4o", temperature=0) # Usando um modelo poderoso com uma saída determinística
messages = [
HumanMessage(content="Qual é a capital da França?")
]
response = llm.invoke(messages)
print(response.content)Esta interação básica confirma que sua conexão LLM está funcionando. Agora, vamos equipar nosso LLM com ferramentas.
Criar Ferramentas para Seu Agente de IA
As ferramentas são as mãos e os pés do agente, permitindo que ele interaja com o mundo externo. O LangChain torna a definição de ferramentas simples. Cada ferramenta deve ter um nome claro, uma descrição e uma função que realiza a ação.
Exemplo: Uma Ferramenta Calculadora Simples
Vamos criar uma ferramenta que pode realizar aritmética básica. Embora os LLMs possam fazer matemática simples, ferramentas externas são mais confiáveis para cálculos complexos.
from langchain.tools import tool
@tool
def calculator(expression: str) -> str:
"""Avalia uma expressão matemática e retorna o resultado.
A entrada deve ser uma string contendo uma expressão matemática válida, por ex., '2 + 2' ou '(5 * 3) / 2'.
"""
try:
return str(eval(expression))
except Exception as e:
return f"Erro ao avaliar a expressão: {e}"
# Você pode testar a ferramenta diretamente
print(calculator.invoke("10 * 5 + 3"))Note o decorador @tool. Isso converte automaticamente sua função em uma ferramenta LangChain. A docstring é crucial, pois serve como descrição da ferramenta, que o LLM usa para entender quando e como utilizá-la.
Exemplo: Uma Ferramenta de Pesquisa Web (Usando Tavily)
A maioria dos agentes poderosos precisa de acesso a informações atualizadas. Uma ferramenta de pesquisa na web é fundamental. Usaremos o Tavily, uma API de pesquisa projetada especificamente para RAG (Retrieval Augmented Generation) e casos de uso de agentes.
Primeiro, instale o Tavily e configure sua chave API no seu arquivo .env:
pip install tavily-pythonTAVILY_API_KEY="sua_chave_api_tavily_aqui"Em seguida, carregue-a:
import os
from dotenv import load_dotenv
from langchain_community.tools.tavily_search import TavilySearchResults
load_dotenv()
os.environ["TAVILY_API_KEY"] = os.getenv("TAVILY_API_KEY")
# Crie a ferramenta de pesquisa Tavily
search = TavilySearchResults(max_results=3) # Obter os 3 melhores resultados
# Você também pode personalizar o nome e a descrição se necessário
# search.name = "web_search"
# search.description = "Pesquisa na web por informações."
# Teste a ferramenta de pesquisa
print(search.invoke("tutorial sobre o agente LangChain"))Ao definir essas ferramentas, estamos dando ao nosso agente as capacidades necessárias para expandir seu conhecimento além dos dados de treinamento e realizar cálculos com precisão.
Construir Seu Primeiro Agente LangChain
Com nosso LLM e ferramentas prontos, podemos agora montar nosso primeiro agente LangChain. Usaremos o método “create_openai_functions_agent”, que é uma maneira prática de construir agentes utilizando as capacidades de chamada de funções da OpenAI.
Passos para Construção do Agente
- Defina seu LLM: O cérebro do seu agente.
- Defina suas Ferramentas: As capacidades que seu agente possui.
- Crie um Modelo de Prompt: Guiar o LLM sobre seu comportamento.
- Crie o Agente: Combine LLM, ferramentas e prompt.
- Crie o Executor do Agente: O ambiente de execução que executa as decisões do agente.
import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain.tools import tool
from langchain_community.tools.tavily_search import TavilySearchResults
# Carregar as variáveis de ambiente
load_dotenv()
os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY")
os.environ["TAVILY_API_KEY"] = os.getenv("TAVILY_API_KEY")
# 1. Definir LLM
llm = ChatOpenAI(model="gpt-4o", temperature=0)
# 2. Definir as ferramentas
@tool
def calculator(expression: str) -> str:
"""Avalia uma expressão matemática e retorna o resultado.
A entrada deve ser uma string contendo uma expressão matemática válida, por exemplo, '2 + 2' ou '(5 * 3) / 2'.
"""
try:
return str(eval(expression))
except Exception as e:
return f"Erro ao avaliar a expressão: {e}"
search = TavilySearchResults(max_results=3)
search.name = "web_search"
search.description = "Busca na web informações atuais sobre uma consulta dada."
tools = [calculator, search]
# 3. Criar um modelo de prompts
prompt = ChatPromptTemplate.from_messages(
[
("system", "Você é um assistente AI útil. Responda às perguntas da forma mais precisa possível."),
MessagesPlaceholder(variable_name="chat_history"),
("human", "{input}"),
MessagesPlaceholder(variable_name="agent_scratchpad"),
]
)
# 4. Criar o agente
agent = create_openai_functions_agent(llm, tools, prompt)
# 5. Criar o executor do agente
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
# Executar o agente
# print("--- Execução do agente 1 (Cálculo simples) ---")
# result1 = agent_executor.invoke({"input": "Qual é 12345 * 6789 ?", "chat_history": []})
# print(result1["output"])
# print("\n--- Execução do agente 2 (Busca web) ---")
# result2 = agent_executor.invoke({"input": "Qual é a capital de Portugal e qual é sua população atual?", "chat_history": []})
# print(result2["output"])
# print("\n--- Execução do agente 3 (Combinado) ---")
# result3 = agent_executor.invoke({"input": "Qual é a raiz quadrada de 81 e quem inventou a World Wide Web?", "chat_history": []})
# print(result3["output"])Quando você define verbose=True no AgentExecutor, você verá o processo de raciocínio do agente: quais ferramentas ele considera, qual ele seleciona, a entrada que ele fornece para a ferramenta, e a saída da ferramenta. Isso é extremamente útil para depuração e para entender como seu agente raciocina.
Compreendendo o modelo de prompt
system: Define a personalidade geral e as instruções para o agente.MessagesPlaceholder(variable_name="chat_history"): É aqui que os turnos de conversa anteriores serão inseridos, permitindo a memória.human: A entrada atual do usuário.MessagesPlaceholder(variable_name="agent_scratchpad"): É aqui que o processo de raciocínio interno do agente e as saídas das ferramentas são armazenados durante uma única invocação, permitindo que o LLM raciocine passo a passo.
Adicionar memória e estado ao seu agente AI
Um agente realmente inteligente precisa de memória para manter o contexto ao longo de vários turnos de conversa. O LangChain oferece diversos tipos de memória, permitindo que seu agente se lembre das interações passadas.
Por que a memória é importante
- Coerência: Os agentes podem se referir a declarações e perguntas anteriores.
- Personalização: Os agentes podem se lembrar das preferências do usuário ou de interações passadas.
- Eficiência: Evita a repetição de informações ou a solicitação de esclarecimentos sobre detalhes já fornecidos.
Implementação de ConversationBufferMemory
ConversationBufferMemory é um tipo de memória simples, mas eficaz, que armazena todas as mensagens anteriores diretamente.
import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain.tools import tool
from langchain_community.tools.tavily_search import TavilySearchResults
from langchain.memory import ConversationBufferMemory # Importar a memória
# Carregar as variáveis de ambiente
load_dotenv()
os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY")
os.environ["TAVILY_API_KEY"] = os.getenv("TAVILY_API_KEY")
# LLM e ferramentas (idênticos aos anteriores)
llm = ChatOpenAI(model="gpt-4o", temperature=0)
@tool
def calculator(expression: str) -> str:
"""Avalia uma expressão matemática e retorna o resultado.
A entrada deve ser uma string contendo uma expressão matemática válida, por exemplo, '2 + 2' ou '(5 * 3) / 2'.
"""
try:
return str(eval(expression))
except Exception as e:
return f"Erro ao avaliar a expressão: {e}"
search = TavilySearchResults(max_results=3)
search.name = "web_search"
search.description = "Busca na web informações atuais sobre uma consulta dada."
tools = [calculator, search]
# Criar um modelo de prompt (note o espaço reservado `chat_history`)
prompt = ChatPromptTemplate.from_messages(
[
("system", "Você é um assistente AI útil. Lembre-se das interações anteriores e responda às perguntas da forma mais precisa possível."),
MessagesPlaceholder(variable_name="chat_history"), # É aqui que a memória será injetada
("human", "{input}"),
MessagesPlaceholder(variable_name="agent_scratchpad"),
]
)
# Inicializar a memória
memory = ConversationBufferMemory(memory_key="chat_history", return_messages=True)
# Criar o agente
agent = create_openai_functions_agent(llm, tools, prompt)
# Criar o executor do agente, passando a memória
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True, memory=memory)
# Executar o agente com memória
print("--- Execução do agente com memória ---")
print("\nUsuário: Qual é a capital da Espanha?")
result1 = agent_executor.invoke({"input": "Qual é a capital da Espanha?"})
print("Agente:", result1["output"])
print("\nUsuário: Qual é sua população?")
result2 = agent_executor.invoke({"input": "Qual é sua população?"})
print("Agente:", result2["output"])
print("\nUsuário: E qual é a população da capital da França?")
result3 = agent_executor.invoke({"input": "E qual é a população da capital da França?"})
print("Agente:", result3["output"])Neste exemplo, o agente se lembra de “Espanha” desde o primeiro turno, e de “capital da França” desde o terceiro, permitindo-lhe fornecer respostas relevantes sem precisar reformular explicitamente o país. O memory_key="chat_history" garante que o conteúdo da memória seja corretamente mapeado para o MessagesPlaceholder(variable_name="chat_history") em nosso modelo de prompt.
Outros tipos de memória
Artigos relacionados
- No coração dos padrões de design de API eficazes
- APIs de streaming para agentes AI
- Qdrant vs FAISS: Qual para as startups
🕒 Published: