LangChain para agentes de IA: Tutorial completo
Os agentes de IA são entidades de software autônomas que podem perceber seu ambiente, tomar decisões e agir para alcançar objetivos específicos. Eles representam um avanço significativo na forma como interagimos com e construímos sistemas inteligentes. Se você deseja entender os componentes essenciais e a implementação prática dos agentes de IA, comece por O guia completo dos agentes de IA em 2026. LangChain se destaca como uma estrutura poderosa para construir esses agentes, fornecendo as abstrações necessárias e as ferramentas para integrar grandes modelos de linguagem (LLMs) com fontes de dados externas e capacidades computacionais. Este tutorial irá guiá-lo na criação de agentes de IA usando LangChain, concentrando-se nos aspectos práticos e nos mecanismos subjacentes.
Compreendendo os fundamentos dos agentes LangChain
No cerne do LangChain, um agente orquestra a interação entre um LLM e um conjunto de ferramentas. O LLM atua como o “cérebro” do agente, decidindo qual ferramenta usar e com qual entrada, com base no objetivo atual e no estado observado. As ferramentas são funções que realizam tarefas específicas, como pesquisar na web, consultar um banco de dados ou executar código.
Os principais componentes de um agente LangChain são:
- LLM: O modelo de linguagem responsável pelo raciocínio e pela tomada de decisões.
- Ferramentas: Funções que o agente pode chamar para interagir com o mundo externo.
- Prompt: Instruções dadas ao LLM, orientando seu comportamento e uso das ferramentas.
- Executante de agente: O ambiente de execução que gerencia o ciclo do agente, passando as observações e as ações entre o LLM e as ferramentas.
Considere um agente projetado para responder perguntas sobre notícias. Ele poderia ter uma ferramenta para realizar pesquisas na web e outra para artigos. O LLM, ao receber uma consulta, decidiria se deve pesquisar na web, executar a pesquisa, observar os resultados e, eventualmente, resumi-los antes de formular uma resposta final.
Configurar seu ambiente LangChain
Antes de construir um agente, certifique-se de ter o LangChain instalado e de acessar um LLM. Usaremos os modelos da OpenAI para este tutorial, mas o LangChain suporta muitos outros.
pip install langchain langchain-openai
Você precisará definir sua chave API da OpenAI como uma variável de ambiente:
import os
os.environ["OPENAI_API_KEY"] = "SUA_CHAVE_API_OPENAI"
Para exemplos mais simples, você pode instanciar o LLM diretamente:
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(temperature=0)
O parâmetro `temperature` controla o nível de aleatoriedade da saída do LLM. Um valor de 0 torna a saída mais determinística e factual, o que é adequado para a tomada de decisões dos agentes.
Construir seu primeiro agente LangChain: Um agente de pesquisa simples
Vamos construir um agente capaz de responder a perguntas usando pesquisa na web. Para isso, precisamos de uma ferramenta de pesquisa na web. O LangChain fornece integrações para vários provedores de pesquisa. Usaremos a ferramenta `TavilySearchResults`, que frequentemente é uma boa escolha padrão.
Primeiro, instale o pacote necessário e configure sua chave API Tavily:
pip install langchain-community tavily-python
import os
os.environ["TAVILY_API_KEY"] = "SUA_CHAVE_API_TAVILY"
Agora, vamos definir as ferramentas e instanciar o agente.
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_react_agent
from langchain import hub
from langchain_community.tools.tavily_search import TavilySearchResults
# 1. Inicializar o LLM
llm = ChatOpenAI(temperature=0, model="gpt-4o")
# 2. Definir as ferramentas
search_tool = TavilySearchResults(max_results=3) # Limitar a 3 resultados de pesquisa
tools = [search_tool]
# 3. Recuperar o prompt do agente ReAct do LangChain Hub
# O modelo ReAct (Raciocínio e Ação) é uma abordagem comum para agentes.
# Ele incita o LLM a gerar um processo de reflexão antes de tomar uma ação.
prompt = hub.pull("hwchase17/react")
# 4. Criar o agente
# create_react_agent constrói um agente que utiliza o prompt ReAct.
agent = create_react_agent(llm, tools, prompt)
# 5. Criar o executante do agente
# O AgentExecutor é responsável pela execução do ciclo de decisão do agente.
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
# 6. Executar o agente
response = agent_executor.invoke({"input": "Qual é a capital da França e qual é sua população atual?"})
print(response["output"])
No exemplo acima:
- Inicializamos `ChatOpenAI` como nosso LLM.
- Criamos uma ferramenta `TavilySearchResults`.
- Recuperamos um prompt ReAct padrão do `langchain_hub`. Esse prompt orienta o LLM a pensar passo a passo (Pensamento) e depois a decidir sobre uma Ação e uma Entrada de Ação.
- `create_react_agent` combina o LLM, as ferramentas e o prompt em um agente.
- `AgentExecutor` executa o agente, gerenciando a sequência de observações e ações. A flag `verbose=True` é crucial para depuração, pois mostra o processo de reflexão interna do agente.
A saída com `verbose=True` mostrará o “Pensamento”, “Ação”, “Entrada de Ação” e “Observação” do agente em cada etapa, ilustrando seu raciocínio.
Adicionar ferramentas e capacidades mais complexas
Os agentes se tornam realmente poderosos quando podem interagir com diversos sistemas. Vamos expandir nosso agente com uma ferramenta para realizar cálculos.
from langchain.agents import AgentExecutor, create_react_agent
from langchain import hub
from langchain_openai import ChatOpenAI
from langchain_community.tools.tavily_search import TavilySearchResults
from langchain.tools import tool # Decorador para uma criação de ferramenta simples
# 1. Inicializar o LLM
llm = ChatOpenAI(temperature=0, model="gpt-4o")
# 2. Definir as ferramentas
search_tool = TavilySearchResults(max_results=3)
@tool
def calculator(expression: str) -> str:
"""Avalia uma expressão matemática e retorna o resultado."""
try:
return str(eval(expression))
except Exception as e:
return f"Erro ao avaliar a expressão: {e}"
tools = [search_tool, calculator]
# 3. Recuperar o prompt do agente ReAct
prompt = hub.pull("hwchase17/react")
# 4. Criar o agente
agent = create_react_agent(llm, tools, prompt)
# 5. Criar o executante do agente
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
# 6. Executar o agente com uma nova solicitação
response = agent_executor.invoke({"input": "Qual é 12345 multiplicado por 67890? Além disso, descubra quem ganhou a última Copa do Mundo."})
print(response["output"])
Aqui, usamos o decorador `@tool` para definir rapidamente uma ferramenta `calculator`. Esse decorador deduz automaticamente a descrição e o esquema de argumentos da ferramenta, que o LLM usa para entender como chamá-la. O agente agora decidirá se deve usar o `calculator` ou os `TavilySearchResults` com base na consulta de entrada. Essa modularidade é essencial para construir agentes de IA sofisticados. Para uma coordenação multi-agentes mais avançada, frameworks como CrewAI Multi-Agent Systems Guide oferecem abstrações poderosas.
Tipos de agentes e seus casos de uso
LangChain oferece vários tipos de agentes, cada um com forças e mecanismos de tomada de decisão diferentes:
- `create_react_agent` (Agente ReAct): Usa o modelo ReAct (Raciocínio e Ação). O LLM gera um “Pensamento” (monólogo interno) e, em seguida, uma “Ação” (chamada de ferramenta) e uma “Entrada de Ação”. É uma abordagem muito eficaz e amplamente utilizada para agentes de uso geral.
- `create_json_agent`: Projetado para agentes que interagem com APIs esperando entradas e saídas em JSON. O LLM é incitado a gerar chamadas de ferramenta no formato JSON.
- `create_openai_functions_agent`: usa as capacidades de chamada de função da OpenAI. O LLM produz diretamente um objeto estruturado indicando a ferramenta a ser chamada e seus argumentos, o que pode ser mais confiável do que a análise de texto. Frequentemente é a escolha preferida ao usar os modelos da OpenAI.
A escolha do tipo de agente depende do seu caso de uso específico e do LLM que você está utilizando. Para a maioria das tarefas gerais com os modelos da OpenAI, `create_openai_functions_agent` é um excelente ponto de partida devido à sua solidez. Vamos examinar um exemplo utilizando-o.
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_core.messages import SystemMessage, HumanMessage
from langchain.tools import tool
from langchain_community.tools.tavily_search import TavilySearchResults
# 1. Inicializar LLM
llm = ChatOpenAI(temperature=0, model="gpt-4o")
# 2. Definir as ferramentas
search_tool = TavilySearchResults(max_results=3)
@tool
def current_time(format_str: str = "%Y-%m-%d %H:%M:%S") -> str:
"""Retorna a data e hora atuais no formato especificado."""
import datetime
return datetime.datetime.now().strftime(format_str)
tools = [search_tool, current_time]
# 3. Definir o prompt do agente (usando mensagens específicas do agente OpenAI)
system_message = SystemMessage(
content="Você é um assistente IA útil. Use as ferramentas disponíveis para responder às perguntas."
)
prompt = [system_message, HumanMessage(content="{input}"), MessagesPlaceholder(variable_name="agent_scratchpad")]
# 4. Criar o agente usando create_openai_functions_agent
agent = create_openai_functions_agent(llm, tools, prompt)
# 5. Criar o executor do agente
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
# 6. Executar o agente
response = agent_executor.invoke({"input": "Que horas são atualmente e quais eram os principais títulos da imprensa de ontem?"})
print(response["output"])
Note o `MessagesPlaceholder(variable_name=”agent_scratchpad”)` no prompt. É aqui que os pensamentos, ações e observações intermediárias do agente são injetados no histórico da conversa, permitindo que o LLM mantenha o contexto.
Gerenciamento do estado e memória do agente
Para que os agentes possam realizar interações complexas e em vários turnos, eles precisam de memória. LangChain fornece diversos componentes de memória para armazenar e recuperar o histórico das conversas. O AgentExecutor pode ser configurado com memória.
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain_core.messages import SystemMessage, HumanMessage, MessagesPlaceholder
from langchain.tools import tool
from langchain_community.tools.tavily_search import TavilySearchResults
from langchain.memory import ConversationBufferWindowMemory # Importar a memória
# 1. Inicializar LLM
llm = ChatOpenAI(temperature=0, model="gpt-4o")
# 2. Definir as ferramentas
search_tool = TavilySearchResults(max_results=3)
tools = [search_tool]
# 3. Definir o prompt do agente
system_message = SystemMessage(
content="Você é um assistente IA útil. Use as ferramentas disponíveis para responder às perguntas. Seja conciso em suas respostas."
)
prompt = [
system_message,
MessagesPlaceholder(variable_name="chat_history"), # Espaço reservado para o histórico das conversas
HumanMessage(content="{input}"),
MessagesPlaceholder(variable_name="agent_scratchpad")
]
# 4. Criar a memória
# ConversationBufferWindowMemory mantém uma janela das 'k' últimas interações.
memory = ConversationBufferWindowMemory(memory_key="chat_history", return_messages=True, k=3)
# 5. Criar o agente
agent = create_openai_functions_agent(llm, tools, prompt)
# 6. Criar o executor do agente com memória
agent_executor = AgentExecutor(
agent=agent,
tools=tools,
verbose=True,
memory=memory # Adicionar a memória aqui
)
# 7. Executar uma conversa em vários turnos
print("--- Primeiro turno ---")
response1 = agent_executor.invoke({"input": "Qual é a capital do Japão?"})
print(response1["output"])
print("\n--- Segundo turno ---")
response2 = agent_executor.invoke({"input": "Qual é sua população?"}) # Referindo-se a "sua" (a capital do Japão)
print(response2["output"])
print("\n--- Terceiro turno ---")
response3 = agent_executor.invoke({"input": "E quanto à capital do Brasil?"})
print(response3["output"])
Ao introduzir ConversationBufferWindowMemory e incluir MessagesPlaceholder(variable_name=”chat_history”) no prompt, o agente agora pode manter o contexto através de vários turnos. O LLM vê as mensagens anteriores, permitindo que compreenda referências como “sua população” no segundo turno. Isso é essencial para construir agentes IA envolventes e funcionais, especialmente para casos de uso como a Criação de um agente IA para o serviço ao cliente.
Personalização avançada do agente e desenvolvimento de ferramentas
Embora o LangChain ofereça muitas ferramentas integradas, você frequentemente precisará criar ferramentas personalizadas para interagir com suas aplicações específicas, bancos de dados ou APIs internas.
As ferramentas personalizadas podem ser simples funções decoradas com @tool, como mostrado com calculator e current_time. Para cenários mais complexos, você pode definir uma classe que herda de BaseTool ou usar StructuredTool para uma definição precisa dos argumentos.
from langchain.tools import BaseTool
from pydantic import BaseModel, Field
from typing import Type
# Definir o esquema de entrada para a ferramenta personalizada
class GetDatabaseRecordInput(BaseModel):
table_name: str = Field(description="Nome da tabela do banco de dados")
record_id: int = Field(description="ID do registro a ser recuperado")
class GetDatabaseRecordTool(BaseTool):
name = "get_database_record"
description = "Útil para recuperar um registro específico de uma tabela de banco de dados pelo seu ID."
args_schema: Type[BaseModel] = GetDatabaseRecordInput
def _run(self, table_name: str, record_id: int) -> str:
"""Simula a recuperação de um registro de um banco de dados."""
print(f"DEBUG: Recuperando o registro {record_id} da tabela {table_name}")
if table_name == "users" and record_id == 1:
return "Registro de usuário: {'id': 1, 'name': 'Alice', 'email': '[email protected]'}"
elif table_name == "products" and record_id == 101:
return "Registro de produto: {'id': 101, 'name': 'Laptop', 'price': 1200}"
return f"Registro não encontrado para a tabela '{table_name}' com o ID '{record_id}'"
async def _arun(self, table_name: str, record_id: int) -> str:
"""Versão assíncrona da ferramenta (opcional)."""
# Implementar a lógica assíncrona aqui
raise NotImplementedError("Chamada assíncrona não implementada para esta ferramenta.")
# Adicionar esta ferramenta à lista de ferramentas do seu agente
# tools.append(GetDatabaseRecordTool())
Esta GetDatabaseRecordTool demonstra como definir uma ferramenta com um esquema de entrada específico usando Pydantic, fornecendo ao LLM instruções claras sobre como utilizá-la. Este nível de controle é essencial para integrar agentes em sistemas empresariais. Ao comparar frameworks, considere como cada um gerencia essas integrações de ferramentas personalizadas; veja Comparar os 5 melhores frameworks de agentes IA 2026 para mais contexto.
Pontos chave para lembrar
- Os agentes LangChain utilizam um LLM para orquestrar o uso das ferramentas, permitindo que interajam com o mundo exterior além de seus dados de treinamento.
- Os componentes principais são o LLM, as ferramentas, um prompt e o executor do agente.
- O modelo ReAct (Raciocinar e Agir) é uma abordagem sólida, muitas vezes facilitada pelos prompts do LangChain Hub.
create_openai_functions_agenté geralmente recomendado para modelos OpenAI devido à sua saída estruturada confiável.- Os componentes de memória (por exemplo,
ConversationBufferWindowMemory) são cruciais para conversas em vários turnos e a consciência contextual. - As ferramentas personalizadas são fáceis de criar usando o decorador
@toolou herdando deBaseToolpara interações mais complexas, permitindo que os agentes se integrem em sistemas proprietários. - Use sempre
verbose=Truedurante o desenvolvimento para inspecionar o processo de pensamento interno do agente e depurar de forma eficaz.
Conclusão
LangChain fornece uma estrutura abrangente e flexível para construir agentes IA. Ao entender seus componentes principais—LLMs, ferramentas, prompts e executores—você pode construir agentes capazes de raciocínio complexo e interação. Desde agentes de busca simples até sistemas sofisticados com memória e integrações personalizadas, o LangChain oferece os elementos necessários para tornar suas ideias de agentes IA realidade. À medida que o campo dos agentes IA continua a evoluir, dominar frameworks como o LangChain será cada vez mais valioso para desenvolver aplicações inteligentes e autônomas.
🕒 Published: