Autor: Priya Sharma – Arquiteta de API e Consultora de Integração de IA
A capacidade de criar sistemas inteligentes que podem entender instruções, raciocinar e agir autonomamente está transformando a forma como interagimos com a tecnologia. No centro dessa transformação estão os agentes de IA – entidades de software projetadas para realizar tarefas usando o poder dos Modelos de Linguagem de Grande Escala (LLMs) e ferramentas externas. Embora o conceito possa parecer complexo, estruturas como o 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 de integração de IA, vi em primeira mão 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 o levará pelo processo de construção de agentes de IA sólidos usando a API do LangChain, desde a compreensão dos componentes principais até a implementação de exemplos práticos do mundo real. Ao final, você terá uma base sólida para projetar e implantar seus próprios agentes inteligentes, prontos para enfrentar uma multiplicidade de desafios.
Entendendo os Agentes de IA e o Papel do LangChain
Antes de explorarmos 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 usa um LLM como seu “cérebro” para decidir quais ações tomar. Diferente de uma simples chamada de 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.
O LangChain fornece a estrutura necessária para construir esses agentes sofisticados. Ele oferece uma maneira estruturada de conectar LLMs com várias fontes de dados e ferramentas computacionais, permitindo que vão além da simples geração de texto. Pense no LangChain como o sistema operacional para 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 o LangChain, você trabalhará principalmente com estes componentes principais:
- Modelo de Linguagem de Grande Escala (LLM): O núcleo da inteligência. Este pode ser os modelos GPT da OpenAI, Claude da Anthropic ou alternativas de código aberto. O LLM processa 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 buscar na web, consultar um banco de dados, chamar uma calculadora ou interagir com uma API personalizada.
- Conjuntos de Ferramentas: Coleções de ferramentas relacionadas projetadas para casos de uso específicos (por exemplo, um “conjunto de ferramentas da Wikipedia” ou um “conjunto de ferramentas para agente CSV”).
- Executor de Agente: O tempo de execução que orquestra as ações do agente. Ele recebe as decisões do LLM, executa as ferramentas escolhidas e alimenta os resultados de volta ao LLM para raciocínio adicional.
- Memória: Permite que o agente retenha informações de interações anteriores, permitindo conversas coerentes com múltiplas trocas e tomada de decisões contextualizada.
- Modelos de Prompt: Define como a entrada do usuário e outras informações são formatadas para o LLM, guiando seu processo de raciocínio.
Configurando Seu Ambiente e Primeiros Passos
Antes de escrever qualquer código do agente, certifique-se de que seu ambiente Python esteja pronto. Você precisará do Python 3.8+ e da biblioteca LangChain, além de qualquer provedor de LLM que pretenda usar.
Instalação
Instale o LangChain e um provedor de LLM (por exemplo, OpenAI):
pip install langchain langchain-openai
pip install python-dotenv # Para gerenciar chaves de API com segurançaGerencie suas chaves de API de forma segura. Crie um arquivo .env na raiz do seu projeto:
OPENAI_API_KEY="sua_chave_api_openai_aqui"Então, carregue isso 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 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 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 com o LLM está funcionando. Agora, vamos habilitar nosso LLM com ferramentas.
Construindo Ferramentas para Seu Agente de IA
Ferramentas são as mãos e os pés do agente, permitindo que ele interaja com o mundo exterior. O LangChain torna a definição de ferramentas simples. Cada ferramenta deve ter um nome claro, uma descrição e uma função que realize a ação.
Exemplo: Uma Ferramenta de Calculadora Simples
Vamos criar uma ferramenta que possa 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 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 a descrição da ferramenta, que o LLM usa para entender quando e como utilizá-la.
Exemplo: Uma Ferramenta de Busca na Web (Usando Tavily)
Agentes mais poderosos precisam de acesso a informações atualizadas. Uma ferramenta de busca na web é fundamental. Usaremos o Tavily, uma API de busca especificamente projetada para RAG (Geração Aumentada por Recuperação) e casos de uso de agentes.
Primeiro, instale o Tavily e defina sua chave de API no seu arquivo .env:
pip install tavily-pythonTAVILY_API_KEY="sua_chave_api_tavily_aqui"Então, carregue isso:
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) # Obter os 3 principais resultados
# Você também pode personalizar o nome e a descrição se necessário
# search.name = "web_search"
# search.description = "Busca informações na web."
# Teste a ferramenta de busca
print(search.invoke("tutorial de agente LangChain"))Ao definir essas ferramentas, estamos dando ao nosso agente as capacidades necessárias para expandir seu conhecimento além de seus dados de treinamento e realizar cálculos com precisão.
Construindo 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 conveniente de construir agentes que usam as capacidades de chamada de funções da OpenAI.
Etapas de 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: Oriente o LLM sobre como se comportar.
- Crie o Agente: Combine LLM, ferramentas e prompt.
- Crie o Executor de Agente: O tempo 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 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 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 por informações atuais sobre uma consulta específica."
tools = [calculator, search]
# 3. Criar um Modelo de Prompt
prompt = ChatPromptTemplate.from_messages(
[
("system", "Você é um assistente de IA útil. Responda perguntas com a maior precisão 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 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 (Combinada) ---")
# 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 pensamento do agente: quais ferramentas ele considera, quais seleciona, a entrada que fornece à ferramenta e a saída da ferramenta. Isso é extremamente útil para depuração e para entender como seu agente raciocina.
Entendendo o Modelo de Prompt
system: Define a persona geral e as instruções para o agente.MessagesPlaceholder(variable_name="chat_history"): É aqui que as interações anteriores da conversa serão inseridas, permitindo memória.human: A entrada atual do usuário.MessagesPlaceholder(variable_name="agent_scratchpad"): É aqui que o processo de pensamento interno do agente e as saídas das ferramentas são armazenadas durante uma única invocação, permitindo que o LLM raciocine passo a passo.
Adicionando Memória e Estado ao Seu Agente de IA
Um agente verdadeiramente inteligente precisa de memória para manter o contexto ao longo de várias interações em uma conversa. O LangChain oferece vários tipos de memória, permitindo que seu agente lembre-se de interações passadas.
Por que a Memória é Importante
- Coerência: Agentes podem se referir a declarações e perguntas anteriores.
- Personalização: Agentes podem lembrar preferências do usuário ou interações passadas.
- Eficiência: Evita repetir informações ou pedir esclarecimentos sobre detalhes já fornecidos.
Implementando ConversationBufferMemory
ConversationBufferMemory é um tipo de memória simples, porém 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 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 (igual ao anterior)
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 por informações atuais sobre uma consulta específica."
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 de interações anteriores e responda perguntas com a maior precisão possível."),
MessagesPlaceholder(variable_name="chat_history"), # É aqui que a memória será injetada
("human", "{input}"),
MessagesPlaceholder(variable_name="agent_scratchpad"),
]
)
# Inicializar 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 quanto à população da capital da França?")
result3 = agent_executor.invoke({"input": "E quanto à 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 que ele forneça respostas relevantes sem precisar reiterações explícitas do país. A memory_key="chat_history" garante que o conteúdo da memória seja mapeado corretamente para o MessagesPlaceholder(variable_name="chat_history") em nosso prompt.
Outros Tipos de Memória
Artigos Relacionados
- Chegando ao Coração de Padrões de Design de API Eficazes
- APIs de streaming para agentes de IA
- Qdrant vs FAISS: Qual Escolher para Startups
🕒 Published: