Autor: Priya Sharma – Arquiteta de API e Consultora para Integração de IA
A capacidade de criar sistemas inteligentes capazes de entender instruções, raciocinar e agir de forma autônoma transforma nossa maneira de interagir com a tecnologia. No coração dessa transformação estão os agentes de IA – entidades de software projetadas para executar tarefas usando o poder dos Large Language Models (LLMs) e ferramentas externas. Embora o conceito possa parecer complexo, frameworks como LangChain simplificaram significativamente o processo de desenvolvimento, tornando a criação de agentes acessível a um público mais amplo.
Como arquiteta de API e consultora para 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á acompanhá-lo através do 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. No final, você terá uma base sólida para projetar e implantar seus agentes inteligentes, prontos para enfrentar uma multiplicidade 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 LangChain é uma ferramenta indispensável para sua construção. Um agente de IA é um sistema que utiliza um LLM como “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 envolver 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 usando ferramentas externas.
- Aprender (opcional, mas poderoso): Incorporar feedback para melhorar o desempenho futuro.
LangChain fornece a estrutura necessária para construir esses agentes sofisticados. Oferece um método estruturado para conectar os LLMs a diferentes 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, sua memória e sua capacidade de interagir com o mundo.
Componentes Chave de um Agente LangChain
Para construir um agente com LangChain, você trabalhará principalmente com esses componentes essenciais:
- Large Language Model (LLM): O núcleo da inteligência. Pode ser um dos 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 executar cálculos específicos. Exemplos incluem busca na Internet, consultas a um banco de dados, chamadas a uma calculadora ou interação com uma API personalizada.
- Conjunto de Ferramentas: Coleções de ferramentas relacionadas projetadas para casos de uso específicos (ex: um “conjunto de ferramentas Wikipedia” ou um “conjunto de ferramentas agente CSV”).
- Executor do Agente: O ambiente de execução que coordena as ações do agente. Toma decisões do LLM, executa as ferramentas escolhidas e retorna os resultados ao LLM para raciocínio posterior.
- Memória: Permite que o agente mantenha informações das interações anteriores, permitindo conversas coerentes em múltiplos turnos e uma tomada de decisão contextual.
- Modelos de Convite: 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 esteja pronto. Você vai precisar do Python 3.8+ e da biblioteca LangChain, além de qualquer provedor de LLM que pretende usar.
Instalação
Instale LangChain e um provedor de LLM (ex: OpenAI):
pip install langchain langchain-openai
pip install python-dotenv # Para gerenciar as chaves API de forma seguraGerencie suas chaves API com segurança. Crie um arquivo .env na raiz do seu projeto:
OPENAI_API_KEY="sua_chave_api_openai_aqui"Em seguida, carregue-o no 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 chamada simples 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)Essa interação básica confirma que sua conexão LLM está funcionando. Agora, vamos equipar nosso LLM com ferramentas.
Criar Ferramentas para o Seu Agente IA
As ferramentas são as mãos e os pés do agente, permitindo interagir com o mundo externo. A LangChain torna a definição das ferramentas simples. Cada ferramenta deve ter um nome claro, uma descrição e uma função que executa a ação.
Exemplo: Uma Ferramenta Calculadora Simples
Vamos criar uma ferramenta que pode executar aritméticas básicas. Embora os LLM possam fazer operações matemáticas simples, as 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 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}"
# 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 utiliza para entender quando e como usá-la.
Exemplo: Uma Ferramenta de Busca na Web (Utilizando Tavily)
A maioria dos agentes poderosos precisa de acesso a informações atualizadas. Uma ferramenta de busca na web é fundamental. Usaremos Tavily, uma API de busca projetada especificamente para RAG (Geração Aumentada por Recuperação) 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-o:
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 busca Tavily
search = TavilySearchResults(max_results=3) # Obtenha os 3 melhores resultados
# Você também pode personalizar o nome e a descrição se necessário
# search.name = "web_search"
# search.description = "Busca na web por informações."
# Teste a ferramenta de busca
print(search.invoke("tutorial sobre o agente LangChain"))Definindo essas ferramentas, damos ao nosso agente as capacidades necessárias para expandir seus conhecimentos além de seus dados de treinamento e executar cálculos com precisão.
Construir Seu Primeiro Agente LangChain
Com nosso LLM e nossas ferramentas prontos, agora podemos montar nosso primeiro agente LangChain. Usaremos o método “create_openai_functions_agent”, que é um modo prático de construir agentes usando as capacidades de chamada de função da OpenAI.
Passos para a Construção do Agente
- Defina seu LLM: O cérebro do seu agente.
- Defina suas Ferramentas: As capacidades que seu agente possui.
- Criar um Modelo de Convite: Guia o LLM sobre seu comportamento.
- Criar o Agente: Combina LLM, ferramentas e convite.
- Criar o Executor do Agente: O ambiente de execução que executa as decisões do agente.
“`html
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 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 = "Pesquisa na web por informações atuais sobre uma determinada consulta."
tools = [calculator, search]
# 3. Criar um modelo de prompt
prompt = ChatPromptTemplate.from_messages(
[
("system", "Você é um assistente AI útil. Responda às perguntas da maneira 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)
# Execute 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 (Pesquisa na 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ê pode ver o processo de reflexão do agente: quais ferramentas ele considera, qual ele seleciona, a entrada que fornece à ferramenta e a saída da ferramenta. É extremamente útil para depuração e para entender como seu agente raciocina.
Compreender o modelo de prompt
system: Define a personalidade geral e as instruções para o agente.MessagesPlaceholder(variable_name="chat_history"): Aqui são inseridos os turnos de conversa anteriores, permitindo a memória.human: A entrada atual do usuário.MessagesPlaceholder(variable_name="agent_scratchpad"): Aqui é armazenado o processo de reflexão interna do agente e as saídas das ferramentas 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 durante vários turnos de conversa. LangChain oferece diferentes tipos de memória, permitindo que seu agente lembre-se de 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 lembrar as preferências do usuário ou interações passadas.
- Eficiência: Evita repetir informações ou pedir 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.
“““html
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 memória
# Carregar 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ênticas a antes)
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, como '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 = "Pesquisa na web por informações atuais sobre uma determinada consulta."
tools = [calculator, search]
# Criar um modelo de prompt (note o espaço reservado `chat_history`)
prompt = ChatPromptTemplate.from_messages(
[
("system", "Você é um assistente de IA útil. Lembre-se das interações anteriores e responda às perguntas da forma mais precisa possível."),
MessagesPlaceholder(variable_name="chat_history"), # Aqui 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 é a sua população?")
result2 = agent_executor.invoke({"input": "Qual é a 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 lembra “Espanha” da primeira interação, e “capital da França” da terceira, permitindo-lhe fornecer respostas relevantes sem precisar reformular explicitamente o país. A memory_key="chat_history" garante que o conteúdo da memória esteja corretamente mapeado para o MessagesPlaceholder(variable_name="chat_history") no nosso modelo de prompt.
Outros tipos de memória
Artigos relacionados
- Ao coração dos modelos de design de API eficazes
- APIs de streaming para agentes de IA
- Qdrant vs FAISS: Qual escolher para startups
“`
🕒 Published: