LangChain para Agentes de IA: Tutorial Completo

LangChain para Agentes de IA: Tutorial Completo

Agentes de IA são entidades de software autônomas que podem perceber seu ambiente, tomar decisões e executar ações para alcançar objetivos específicos. Eles representam um avanço significativo na forma como interagimos e construímos sistemas inteligentes. Se você está buscando entender os componentes principais e a implementação prática de agentes de IA, comece com O Guia Completo para Agentes de IA em 2026. LangChain se destaca como uma estrutura poderosa para construir esses agentes, oferecendo as abstrações necessárias e ferramentas para integrar grandes modelos de linguagem (LLMs) com fontes de dados externas e capacidades computacionais. Este tutorial irá guiá-lo na construção de agentes de IA usando LangChain, com foco nos aspectos práticos e mecanismos subjacentes.

Compreendendo os Fundamentos do Agente LangChain

Em sua essência, um agente LangChain 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. 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.
• Executor do Agente: O runtime que gerencia o loop do agente, passando observações e ações entre o LLM e as ferramentas.

Considere um agente projetado para responder perguntas sobre eventos atuais. Ele pode ter uma ferramenta para realizar pesquisas na web e outra para artigos. O LLM, dado uma consulta, decidiria se deve pesquisar na web, executar a pesquisa, observar os resultados e, em seguida, potencialmente resumi-los antes de formular uma resposta final.

Configurando Seu Ambiente LangChain

Antes de construir um agente, certifique-se de ter o LangChain instalado e acesso a 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 de 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 a aleatoriedade da saída do LLM. Um valor de 0 torna a saída mais determinística e factual, adequada para a tomada de decisões do agente.

Construindo Seu Primeiro Agente LangChain: Um Simples Agente de Pesquisa

Vamos construir um agente que pode responder perguntas usando pesquisa na web. Isso requer uma ferramenta de pesquisa na web. O LangChain oferece integrações para vários provedores de pesquisa. Usaremos a ferramenta `TavilySearchResults`, que costuma ser uma boa opção padrão.

Primeiro, instale o pacote necessário e defina sua chave da 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 LLM
llm = ChatOpenAI(temperature=0, model="gpt-4o")

# 2. Definir Ferramentas
search_tool = TavilySearchResults(max_results=3) # Limitar a 3 resultados de pesquisa
tools = [search_tool]

# 3. Puxar o Prompt do Agente ReAct do LangChain Hub
# O padrão ReAct (Raciocínio e Ação) é uma abordagem comum para agentes.
# Ele orienta o LLM a gerar um processo de pensamento antes de tomar uma ação.
prompt = hub.pull("hwchase17/react")

# 4. Criar o Agente
# create_react_agent constrói um agente que usa o prompt ReAct.
agent = create_react_agent(llm, tools, prompt)

# 5. Criar o Executor do Agente
# O AgentExecutor é responsável por executar o loop 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"])

Neste exemplo:

• Inicializamos o `ChatOpenAI` como nosso LLM.
• Criamos uma ferramenta `TavilySearchResults`.
• Puxamos um prompt padrão ReAct do `langchain_hub`. Este prompt orienta o LLM a pensar passo a passo (Pensamento) e depois decidir sobre uma Ação e Input da Ação.
• `create_react_agent` combina o LLM, ferramentas e 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 pensamento interno do agente.

A saída com `verbose=True` mostrará o “Pensamento,” “Ação,” “Input da Ação,” e “Observação” do agente em cada etapa, demonstrando seu raciocínio.

Adicionando Ferramentas e Capacidades Mais Complexas

Agentes se tornam realmente poderosos quando podem interagir com vários sistemas. Vamos estender 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 criação simples de ferramentas

# 1. Inicializar LLM
llm = ChatOpenAI(temperature=0, model="gpt-4o")

# 2. Definir 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. Puxar o Prompt do Agente ReAct
prompt = hub.pull("hwchase17/react")

# 4. Criar o Agente
agent = create_react_agent(llm, tools, prompt)

# 5. Criar o Executor do Agente
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

# 6. Executar o Agente com uma nova consulta
response = agent_executor.invoke({"input": "Qual é 12345 vezes 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`. Este decorador infere 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 a `calculator` ou `TavilySearchResults` com base na consulta de entrada. Essa modularidade é a chave para construir agentes de IA sofisticados. Para coordenação avançada entre múltiplos agentes, estruturas como o Guia de Sistemas Multi-Agentes CrewAI oferecem abstrações poderosas.

Tipos de Agentes e Seus Casos de Uso

LangChain oferece vários tipos de agentes, cada um com diferentes forças e mecanismos de tomada de decisão subjacentes:

• `create_react_agent` (Agente ReAct): Usa o padrão ReAct (Raciocínio e Ação). O LLM gera um “Pensamento” (monólogo interno) e depois uma “Ação” (chamada de ferramenta) e “Input da Ação.” Esta é uma abordagem altamente eficaz e amplamente utilizada para agentes de propósito geral.
• `create_json_agent`: Projetado para agentes que interagem com APIs que esperam entradas e saídas em JSON. O LLM é orientado a gerar chamadas de ferramentas formatadas em JSON.
• `create_openai_functions_agent`: utiliza as capacidades de chamada de funções 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 analisar texto. Esta é geralmente a escolha preferida ao usar modelos da OpenAI.

Escolher o tipo certo de agente depende do seu caso de uso específico e do LLM que você está utilizando. Para a maioria das tarefas gerais com modelos da OpenAI, `create_openai_functions_agent` é um excelente ponto de partida devido à sua solidez. Vamos olhar um exemplo usando-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 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 de funções da OpenAI)
system_message = SystemMessage(
 content="Você é um assistente de IA útil. Use as ferramentas disponíveis para responder 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": "Qual é a hora atual e quais foram as principais manchetes de notícias ontem?"})
print(response["output"])

Observe o `MessagesPlaceholder(variable_name=”agent_scratchpad”)` no prompt. É aqui que os pensamentos, ações e observações intermediárias do agente são inseridos no histórico da conversa, permitindo que o LLM mantenha o contexto.

Gerenciando o Estado e a Memória do Agente

Para que os agentes realizem interações complexas e de múltiplas etapas, eles precisam de memória. O LangChain fornece vários componentes de memória para armazenar e recuperar o histórico de 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 memória

# 1. Inicializar LLM
llm = ChatOpenAI(temperature=0, model="gpt-4o")

# 2. Definir Ferramentas
search_tool = TavilySearchResults(max_results=3)
tools = [search_tool]

# 3. Definir o Prompt do Agente
system_message = SystemMessage(
 content="Você é um assistente de IA útil. Use as ferramentas disponíveis para responder perguntas. Mantenha suas respostas sucintas."
)
prompt = [
 system_message,
 MessagesPlaceholder(variable_name="chat_history"), # Placeholder para histórico de chat
 HumanMessage(content="{input}"),
 MessagesPlaceholder(variable_name="agent_scratchpad")
]

# 4. Criar Memória
# ConversationBufferWindowMemory mantém uma janela das últimas 'k' 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 memória aqui
)

# 7. Executar Conversa de Múltiplas Etapas
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" (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 em várias etapas. O LLM vê as mensagens anteriores, permitindo que ele compreenda referências como “sua população” no segundo turno. Isso é fundamental para construir agentes de IA envolventes e funcionais, especialmente para casos de uso como Construindo um Agente de IA para Atendimento 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.

Ferramentas personalizadas podem ser funções simples 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 definição precisa de argumentos.

from langchain.tools import BaseTool
from pydantic import BaseModel, Field
from typing import Type

# Defina 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 do 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 registro {record_id} da tabela {table_name}")
 if table_name == "users" and record_id == 1:
 return "Registro do usuário: {'id': 1, 'name': 'Alice', 'email': '[email protected]'}"
 elif table_name == "products" and record_id == 101:
 return "Registro do produto: {'id': 101, 'name': 'Laptop', 'price': 1200}"
 return f"Registro não encontrado para a tabela '{table_name}' com ID '{record_id}'"

 async def _arun(self, table_name: str, record_id: int) -> str:
 """Versão assíncrona da ferramenta (opcional)."""
 # Implemente a lógica assíncrona aqui
 raise NotImplementedError("Chamada assíncrona não implementada para esta ferramenta.")

# Adicione 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 usá-la. Esse nível de controle é essencial para integrar agentes em sistemas empresariais. Ao comparar frameworks, considere como cada um lida com essas integrações de ferramentas personalizadas; veja Comparando os 5 Melhores Frameworks de Agentes de IA 2026 para mais contexto.

Principais Conclusões

• Os agentes do LangChain usam um LLM para orquestrar o uso de ferramentas, permitindo que interajam com o mundo externo além de seus dados de treinamento.
• Os componentes principais são o LLM, as Ferramentas, um Prompt e o Executor do Agente.
• O padrão ReAct (Raciocinar e Agir) é uma boa abordagem, frequentemente facilitada por prompts do LangChain Hub.
• `create_openai_functions_agent` é geralmente recomendado para modelos da OpenAI devido à sua saída estruturada confiável.
• Componentes de memória (por exemplo, `ConversationBufferWindowMemory`) são cruciais para conversas de múltiplas etapas e consciência contextual.
• Ferramentas personalizadas são fáceis de criar usando o decorador `@tool` ou herdando de `BaseTool` para interações mais complexas, permitindo que os agentes se integrem a sistemas proprietários.
• Use sempre `verbose=True` durante o desenvolvimento para inspecionar o processo de pensamento interno do agente e depurar efetivamente.

Conclusão

O LangChain fornece um framework completo e flexível para construir agentes de IA. Ao entender seus componentes principais—LLMs, ferramentas, prompts e executores—você pode construir agentes capazes de raciocínio e interação complexos. De agentes de busca simples a sistemas sofisticados com memória e integrações personalizadas, o LangChain oferece os blocos básicos para dar vida às suas ideias de agentes de IA. À medida que o campo dos agentes de IA continua a evoluir, dominar frameworks como o LangChain será cada vez mais valioso para o desenvolvimento de aplicações inteligentes e autônomas.

🕒 Published: April 2, 2026