Arquitetura LangChain & LangGraph

Domine o moderno LangChain 1.x e LangGraph para construir aplicações LLM sofisticadas com agentes, gerenciamento de estado, memória e integração de ferramentas.

Quando Usar Esta Habilidade

• Construir agentes de IA autônomos com acesso a ferramentas
• Implementar fluxos de trabalho LLM complexos de múltiplos passos
• Gerenciar memória de conversação e estado
• Integrar LLMs com fontes de dados externas e APIs
• Criar componentes de aplicação LLM modulares e reutilizáveis
• Implementar pipelines de processamento de documentos
• Construir aplicações LLM de nível de produção

Estrutura do Pacote (LangChain 1.x)

langchain (1.2.x)         # High-level orchestration
langchain-core (1.2.x)    # Core abstractions (messages, prompts, tools)
langchain-community       # Third-party integrations
langgraph                 # Agent orchestration and state management
langchain-openai          # OpenAI integrations
langchain-anthropic       # Anthropic/Claude integrations
langchain-voyageai        # Voyage AI embeddings
langchain-pinecone        # Pinecone vector store

Conceitos Essenciais

1. Agentes LangGraph

LangGraph é o padrão para construir agentes em 2026. Ele oferece:

Recursos Principais:

• StateGraph: Gerenciamento explícito de estado com estado tipado
• Execução Durável: Agentes persistem através de falhas
• Humano no Loop: Inspecione e modifique o estado a qualquer momento
• Memória: Memória de curto e longo prazo entre sessões
• Checkpointing: Salve e retome o estado do agente

Padrões de Agente:

• ReAct: Raciocínio + Ação com create_react_agent
• Planejar e Executar: Nós separados de planejamento e execução
• Multi-Agente: Supervisor roteando entre agentes especializados
• Chamada de Ferramenta: Invocação estruturada de ferramentas com esquemas Pydantic

2. Gerenciamento de Estado

LangGraph usa TypedDict para estado explícito:

from typing import Annotated, TypedDict
from langgraph.graph import MessagesState

# Simple message-based state
class AgentState(MessagesState):
    """Extends MessagesState with custom fields."""
    context: Annotated[list, "retrieved documents"]

# Custom state for complex agents
class CustomState(TypedDict):
    messages: Annotated[list, "conversation history"]
    context: Annotated[dict, "retrieved context"]
    current_step: str
    results: list

3. Sistemas de Memória

Implementações modernas de memória:

• ConversationBufferMemory: Armazena todas as mensagens (conversas curtas)
• ConversationSummaryMemory: Resume mensagens mais antigas (conversas longas)
• ConversationTokenBufferMemory: Janela baseada em tokens
• VectorStoreRetrieverMemory: Recuperação por similaridade semântica
• LangGraph Checkpointers: Estado persistente entre sessões

4. Processamento de Documentos

Carregando, transformando e armazenando documentos:

Componentes:

• Document Loaders: Carrega de várias fontes
• Text Splitters: Divide documentos de forma inteligente
• Vector Stores: Armazena e recupera embeddings
• Retrievers: Busca documentos relevantes

5. Callbacks & Tracing

LangSmith é o padrão para observabilidade:

• Registro de requisição/resposta
• Rastreamento de uso de tokens
• Monitoramento de latência
• Rastreamento de erros
• Visualização de traces

Início Rápido

Agente ReAct Moderno com LangGraph

from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.memory import MemorySaver
from langchain_anthropic import ChatAnthropic
from langchain_core.tools import tool
import ast
import operator

# Inicializa LLM (Claude Sonnet 5 recomendado)
llm = ChatAnthropic(model="claude-sonnet-5")

# Define ferramentas com esquemas Pydantic
@tool
def search_database(query: str) -> str:
    """Busca no banco de dados interno por informações."""
    # Sua lógica de busca no banco de dados
    return f"Resultados para: {query}"

@tool
def calculate(expression: str) -> str:
    """Avalia com segurança uma expressão matemática.

    Suporta: +, -, *, /, **, %, parênteses
    Exemplo: '(2 + 3) * 4' retorna '20'
    """
    # Avaliação matemática segura usando ast
    allowed_operators = {
        ast.Add: operator.add,
        ast.Sub: operator.sub,
        ast.Mult: operator.mul,
        ast.Div: operator.truediv,
        ast.Pow: operator.pow,
        ast.Mod: operator.mod,
        ast.USub: operator.neg,
    }

    def _eval(node):
        if isinstance(node, ast.Constant):
            return node.value
        elif isinstance(node, ast.BinOp):
            left = _eval(node.left)
            right = _eval(node.right)

…