LangChain: O Framework Definitivo para IA Generativa
O desenvolvimento de aplicações com LLMs (Large Language Models) evoluiu drasticamente nos últimos anos. O LangChain surgiu como o framework mais popular para criar aplicações robustas que vão muito além de simples chamadas de API. Neste guia completo, vamos explorar desde conceitos fundamentais até implementações avançadas de RAG e agentes autônomos.
O que é LangChain?
LangChain é um framework open-source que simplifica o desenvolvimento de aplicações complexas com modelos de linguagem. Ele fornece abstrações poderosas para:
- Chains: Sequências de operações com LLMs
- Agents: Sistemas autônomos que tomam decisões
- Memory: Gerenciamento de contexto e histórico
- RAG: Retrieval Augmented Generation
- Tools: Integração com APIs e serviços externos
Por que usar LangChain?
| Recurso | Sem LangChain | Com LangChain |
|---|---|---|
| Prompt Management | Manual, código espalhado | Templates estruturados |
| Memory | Implementação custom | Built-in, múltiplos tipos |
| RAG | Muita integração manual | Abstrações prontas |
| Agents | Lógica complexa | Framework de decisão |
| Debugging | Console.log básico | LangSmith integrado |
"LangChain não é apenas uma biblioteca, é uma mudança de paradigma em como construímos aplicações de IA." - Harrison Chase, criador do LangChain
Instalação e Configuração
Setup do Ambiente
# Criar ambiente virtual
python -m venv langchain-env
source langchain-env/bin/activate # Linux/Mac
# ou
langchain-env\Scripts\activate # Windows
# Instalar dependências
pip install langchain langchain-openai langchain-community
pip install chromadb tiktoken python-dotenv
Configuração das API Keys
# config.py
import os
from dotenv import load_dotenv
load_dotenv()
# OpenAI
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
# Anthropic (Claude)
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")
# LangSmith (opcional, para debugging)
LANGCHAIN_TRACING_V2 = os.getenv("LANGCHAIN_TRACING_V2", "false")
LANGCHAIN_API_KEY = os.getenv("LANGCHAIN_API_KEY")
Conceitos Fundamentais
1. LLMs e Chat Models
O LangChain suporta diversos provedores de LLM:
from langchain_openai import ChatOpenAI, OpenAI
from langchain_anthropic import ChatAnthropic
# Chat model (recomendado)
chat_model = ChatOpenAI(
model="gpt-4-turbo-preview",
temperature=0.7,
max_tokens=1000
)
# Completion model (legado)
llm = OpenAI(model="gpt-3.5-turbo-instruct")
# Claude
claude = ChatAnthropic(model="claude-3-opus-20240229")
2. Prompts e Templates
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
# Prompt simples
simple_prompt = ChatPromptTemplate.from_template(
"Você é um {role}. Responda a seguinte pergunta: {question}"
)
# Prompt com histórico de mensagens
chat_prompt = ChatPromptTemplate.from_messages([
("system", "Você é um assistente especializado em {topic}."),
MessagesPlaceholder(variable_name="history"),
("human", "{input}")
])
# Usar o prompt
messages = simple_prompt.format_messages(
role="especialista em Python",
question="Como otimizar loops?"
)
3. LCEL - LangChain Expression Language
A nova forma de criar chains no LangChain:
from langchain_core.output_parsers import StrOutputParser
from langchain_core.runnables import RunnablePassthrough
# Chain simples com LCEL
chain = prompt | chat_model | StrOutputParser()
# Chain com múltiplas etapas
from langchain_core.runnables import RunnableParallel
analysis_chain = (
RunnableParallel({
"summary": prompt_summary | llm | StrOutputParser(),
"sentiment": prompt_sentiment | llm | StrOutputParser(),
"keywords": prompt_keywords | llm | StrOutputParser()
})
)
# Executar
result = chain.invoke({"role": "dev", "question": "Explain async/await"})
Memory: Contexto e Histórico
O gerenciamento de memória é crucial para aplicações conversacionais.
Tipos de Memory
| Tipo | Uso | Prós | Contras |
|---|---|---|---|
| Buffer | Conversas curtas | Simples, contexto completo | Tokens crescem rápido |
| Summary | Conversas longas | Economiza tokens | Perde detalhes |
| Entity | Foco em entidades | Informação estruturada | Setup complexo |
| Vector | Conversas muito longas | Busca semântica | Precisa de DB vetorial |
Implementação Prática
from langchain.memory import ConversationBufferMemory, ConversationSummaryMemory
from langchain_community.chat_message_histories import ChatMessageHistory
# Buffer Memory - mantém tudo
buffer_memory = ConversationBufferMemory(
memory_key="history",
return_messages=True
)
# Summary Memory - resume conversas longas
summary_memory = ConversationSummaryMemory(
llm=chat_model,
memory_key="history",
return_messages=True
)
# Usando com LCEL
from langchain_core.runnables.history import RunnableWithMessageHistory
chain_with_history = RunnableWithMessageHistory(
chain,
lambda session_id: ChatMessageHistory(),
input_messages_key="input",
history_messages_key="history"
)
# Invocar com session_id
response = chain_with_history.invoke(
{"input": "Olá, meu nome é João"},
config={"configurable": {"session_id": "user_123"}}
)
RAG: Retrieval Augmented Generation
RAG é a técnica que permite aos LLMs acessar conhecimento externo, reduzindo alucinações e mantendo informações atualizadas.
Arquitetura RAG
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Documento │────▶│ Chunking │────▶│ Embedding │
└──────────────┘ └──────────────┘ └──────────────┘
│
▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Resposta │◀────│ LLM │◀────│ Vector Store │
└──────────────┘ └──────────────┘ └──────────────┘
▲
│
┌──────────────┐
│ Query │
└──────────────┘
Implementação Completa
from langchain_community.document_loaders import PyPDFLoader, TextLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import Chroma
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
# 1. Carregar documentos
loader = PyPDFLoader("documento.pdf")
documents = loader.load()
# 2. Dividir em chunks
text_splitter = RecursiveCharacterTextSplitter(
chunk_size=1000,
chunk_overlap=200,
separators=["\n\n", "\n", " ", ""]
)
chunks = text_splitter.split_documents(documents)
# 3. Criar embeddings e vector store
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
vectorstore = Chroma.from_documents(
documents=chunks,
embedding=embeddings,
persist_directory="./chroma_db"
)
# 4. Criar retriever
retriever = vectorstore.as_retriever(
search_type="similarity",
search_kwargs={"k": 4}
)
# 5. Criar RAG chain
rag_prompt = ChatPromptTemplate.from_template("""
Responda a pergunta baseado apenas no contexto fornecido.
Se não souber a resposta, diga que não sabe.
Contexto:
{context}
Pergunta: {question}
Resposta:
""")
def format_docs(docs):
return "\n\n".join(doc.page_content for doc in docs)
rag_chain = (
{"context": retriever | format_docs, "question": RunnablePassthrough()}
| rag_prompt
| chat_model
| StrOutputParser()
)
# 6. Usar
response = rag_chain.invoke("Qual é o tema principal do documento?")
Agents: Sistemas Autônomos
Agents são sistemas que podem usar ferramentas e tomar decisões autonomamente.
Criando um Agent com Tools
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_core.tools import tool
from langchain_community.tools import DuckDuckGoSearchRun
# Definir tools customizadas
@tool
def calculator(expression: str) -> str:
"""Calcula expressões matemáticas. Input: expressão como string."""
try:
return str(eval(expression))
except Exception as e:
return f"Erro: {e}"
@tool
def get_current_weather(city: str) -> str:
"""Obtém o clima atual de uma cidade."""
# Simular API de clima
return f"O clima em {city} está ensolarado, 25°C"
# Tools disponíveis
search = DuckDuckGoSearchRun()
tools = [calculator, get_current_weather, search]
# Criar agent
agent_prompt = ChatPromptTemplate.from_messages([
("system", """Você é um assistente útil com acesso a ferramentas.
Use as ferramentas quando necessário para responder perguntas.
Sempre explique seu raciocínio."""),
("human", "{input}"),
MessagesPlaceholder(variable_name="agent_scratchpad")
])
agent = create_openai_tools_agent(chat_model, tools, agent_prompt)
# Executor com memória e error handling
agent_executor = AgentExecutor(
agent=agent,
tools=tools,
verbose=True,
max_iterations=5,
handle_parsing_errors=True
)
# Usar
response = agent_executor.invoke({
"input": "Qual é a raiz quadrada de 144 vezes a temperatura em São Paulo?"
})
Tipos de Agents
| Tipo | Descrição | Quando Usar |
|---|---|---|
| OpenAI Tools | Usa function calling | GPT-3.5/4, mais confiável |
| ReAct | Reasoning + Acting | Explicações detalhadas |
| Plan and Execute | Planeja antes de agir | Tarefas complexas |
| Self-ask | Divide em sub-perguntas | Perguntas compostas |
Debugging com LangSmith
O LangSmith é a plataforma de observabilidade do LangChain:
import os
# Habilitar tracing
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "sua-api-key"
os.environ["LANGCHAIN_PROJECT"] = "meu-projeto"
# Agora todas as execuções são logadas automaticamente
response = chain.invoke({"question": "Test"})
Métricas Importantes
- Latência por componente
- Tokens utilizados
- Taxa de sucesso
- Custo por execução
- Traces detalhados
Boas Práticas e Patterns
1. Estrutura de Projeto
my_langchain_app/
├── src/
│ ├── chains/
│ │ ├── __init__.py
│ │ ├── rag_chain.py
│ │ └── conversation_chain.py
│ ├── agents/
│ │ ├── __init__.py
│ │ └── research_agent.py
│ ├── tools/
│ │ ├── __init__.py
│ │ └── custom_tools.py
│ ├── prompts/
│ │ ├── __init__.py
│ │ └── templates.py
│ └── config.py
├── tests/
├── .env
└── requirements.txt
2. Error Handling
from langchain_core.runnables import RunnableLambda
from tenacity import retry, stop_after_attempt, wait_exponential
@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10))
def safe_invoke(chain, input_data):
try:
return chain.invoke(input_data)
except Exception as e:
logger.error(f"Error invoking chain: {e}")
raise
# Fallback chain
fallback_chain = chain.with_fallbacks([
backup_chain,
RunnableLambda(lambda x: "Desculpe, não consegui processar sua solicitação.")
])
Conclusão
O LangChain democratiza o desenvolvimento de aplicações de IA, oferecendo abstrações poderosas e flexíveis que aceleram o desenvolvimento sem sacrificar a flexibilidade.
Checklist de Aprendizado
- Entender LLMs e Chat Models
- Dominar Prompts e Templates
- Implementar Memory para contexto
- Construir sistema RAG completo
- Criar Agents com Tools customizadas
- Configurar observabilidade com LangSmith
Recursos Adicionais
Documentação:
Comunidade:
Este guia é atualizado regularmente para acompanhar as mudanças do framework. Última atualização: Dezembro 2024.



