Escolhendo a stack

A situação

Você entra num time e o README diz “a gente usa Claude”. No emprego anterior o mesmo bot de pedidos estava em OpenAI. Um post manda jogar o LangChain fora. Um colega diz que tudo tem que ser LangGraph. O ticket da semana é só isto: classificar a mensagem do cliente e mandar fatura para um prompt, pedido para outro.

As três pastas resolvem o mesmo desenho. O que muda é quem escreve a sequência, o ramo e a retentativa. Aprender o nome de um fornecedor como se fosse a profissão deixa você recomeçando a cada troca de API.

O conceito

Um sistema com LLM tem quatro camadas. A biblioteca mora numa delas.

flowchart TD
  APP["1. Seu produto"]:::tool --> ORCH["2. Orquestração"]:::llm
  ORCH --> MODEL(["3. Provedor do modelo"]):::io
  ORCH --> SIDE["4. Busca, eval e trace"]:::tool

1. O produto: rotas, permissão, dinheiro, o texto que o cliente lê.
2. A orquestração: a ordem das chamadas, o ramo, o loop, a pausa. Pode ser uma função sua, LangChain, LangGraph, o SDK de agente de um provedor, Pydantic AI ou o Vercel AI SDK.
3. O provedor: OpenAI, Anthropic, Google, ou um modelo que você hospeda. Os quatro oferecem as mesmas operações: texto, saída com schema, ferramentas e streaming.
4. Os vizinhos: busca, eval e trace. LlamaIndex quando o índice é o produto. O eval continua seu. O trace pode ser LangSmith, Langfuse ou OpenTelemetry.

O padrão do catálogo descreve a camada 2. O SDK da aba Python descreve uma forma da camada 3. Trocar de aba não troca o padrão.

Quem escreve o caminho

Antes da biblioteca, decida o degrau em Chains, agentes e workflows. Chain, workflow e agente cabem em LangGraph. Usar LangGraph não transforma a moderação de anúncios em agente.

Você precisa	Escreva você	Biblioteca que já escreveu
Duas a quatro chamadas em ordem fixa	Funções	LangChain, se você vai trocar de provedor
Ramos, loop, pausa humana, retomada	Um punhado de funções	LangGraph
Loop de ferramentas até parar	Um while com teto	create_agent (LangChain 1.x, roda em LangGraph), OpenAI Agents SDK, Claude Agent SDK ou Pydantic AI
Chat com streaming na interface	A sua API	Vercel AI SDK
Perguntas sobre uma base de documentos	O seu retriever	LlamaIndex, quando o índice é o produto
Saída com schema	Pydantic ou Zod no SDK do provedor	with_structured_output, se a stack já é LangChain
Prompt que melhora a partir de um dataset	O seu eval	DSPy, quando o dataset é a especificação

init_chat_model("anthropic:claude-haiku-4-5") e init_chat_model("openai:gpt-4o-mini") devolvem o mesmo tipo de objeto. O prefixo é o fornecedor. O resto da função não muda. Isso é o que a aba LangChain está mostrando nas páginas de padrão: a decisão continua no seu if, o modelo é uma string.

O que todo provedor faz igual

Texto entra. Sai texto, um pedido de ferramenta ou um objeto no schema. A Anthropic devolve blocos em content e stop_reason. A OpenAI devolve choices[0].message e finish_reason. O Google usa outro envelope. Nenhum desses nomes deveria aparecer no módulo que grava a nota fiscal. O smell é Vazamento de Formato do Provedor.

LangChain e o Vercel AI SDK escondem o envelope. Um cliente fino que você escreve faz o mesmo serviço se você só tem dois pontos de chamada. A partir do terceiro, a abstração começa a se pagar, porque a troca de modelo deixa de ser um diff em cada arquivo.

Quando a biblioteca atrapalha

• A tarefa é uma chamada. Um grafo com um nó é um caminho mais longo para escrever uma função.
• Você precisa ver o loop para achar um orçamento estourado. create_agent esconde a volta. A aba Python de Loop ReAct é a que se lê primeiro.
• recursion_limit no LangGraph e max_turns no OpenAI Agents SDK contam passos do framework. Tempo, dinheiro e uma parada honesta continuam seus. Veja Condições de Parada.
• Um tutorial de 2023 importa langchain.chains.LLMChain. Essa API saiu para langchain-classic na versão 1.0. Leia o padrão nesta página e o import na documentação atual, não o contrário.

Experimente

Pegue a mensagem “quero a segunda via do boleto do pedido 8831” e marque a camada de cada peça. Cinco minutos.

Classificar billing ou orders     orquestração (workflow)
Chamar o modelo pequeno           provedor
O if que escolhe a rota           seu código
O prompt de financeiro            seu produto
SDK da Anthropic ou da OpenAI    adaptador, não a regra

A mesma classificação, dois fornecedores, uma função:

from typing import Literal

from langchain.chat_models import init_chat_model
from pydantic import BaseModel

class Route(BaseModel):
    kind: Literal["billing", "orders", "other"]
    confidence: float

# Troque só esta string. A forma é "provedor:modelo".
MODEL = "openai:gpt-4o-mini"
# MODEL = "anthropic:claude-haiku-4-5"
# MODEL = "google_genai:gemini-2.5-flash"

router = init_chat_model(MODEL, temperature=0).with_structured_output(Route)

def classify(message: str) -> Route:
    return router.invoke([
        ("system", "Classifique: billing, orders ou other."),
        ("human", message),
    ])

Se a sua função classify ainda importa anthropic ou openai no meio da regra de negócio, o vazamento está aí, não na escolha do modelo.

Checagem +20 XP de primeiraO time moderava anúncios com quatro caixas fixas e alguém quer reescrever em LangGraph com create_agent, 'porque agora é a stack certa'. O que você responde?

LangGraph serve, desde que as quatro caixas sejam arestas fixas. create_agent devolve ao modelo a liberdade de pular a imagem

Concordo: se vai usar LangGraph, o certo é o agente pronto

LangGraph é pesado demais; fique no SDK da Anthropic para sempre

O que isso muda

• Roteamento tem a decisão no código em três formas: SDK, LangChain e LangGraph.
• Encadeamento de Prompts usa o LangGraph quando o portão do meio é uma aresta, não um if solto.
• Saída Estruturada mostra o schema no SDK da Anthropic, no da OpenAI e no with_structured_output.
• Uso de Ferramentas e o Loop ReAct mostram o while à mão e o create_agent.
• RAG deixa a busca no seu código. LlamaIndex entra quando o índice é o produto, não para esconder a checagem da citação.
• Humano no Circuito usa interrupt e checkpointer do LangGraph quando a espera pode durar dias.

Comece pelo degrau. Escolha a biblioteca que escreve aquele degrau com menos código que você consiga ler numa terça de incidente.

Teste seu entendimento

Checagem +20 XP de primeiraO extrator de NF-e faz duas chamadas, sempre na mesma ordem, e o contrato com o provedor é de um ano. Um colega quer introduzir LangChain antes de escrever o eval. O que você faz?

Escreve as duas funções no SDK e deixa o LangChain para o dia em que o segundo provedor existir de verdade

Adota LangChain agora, porque todo código novo do time tem que nascer portável

Adota LangGraph, porque extração pode ganhar um ramo no futuro

Checagem +20 XP de primeiraO pagamento acima de R$ 500 espera um humano, às vezes até o dia seguinte. O loop em memória morre quando o processo reinicia. Qual peça resolve a espera?

Um modelo maior, para ele acertar sem pedir aprovação

interrupt no LangGraph, com um checkpointer que sobrevive ao processo

create_agent, porque aprovação humana é um tipo de ferramenta

Checagem +20 XP de primeiraO módulo contabil/emitir.py importa o tipo ContentBlock da Anthropic para ler o campo do CNPJ. Qual é o problema, e o LangChain resolveria sozinho?

O problema é o fornecedor. Trocar para OpenAI acaba com o vazamento

O problema é o envelope do provedor dentro da regra de negócio. Um adaptador seu, ou init_chat_model, devolve o tipo da nota. AIMessage no meio do contábil é o mesmo vazamento

Não há problema: o tipo do SDK é a forma mais honesta de ler a resposta

Checagem +20 XP de primeiraVocê achou um exemplo de RAG com RetrievalQA do LangChain de 2023. A página de RAG deste catálogo insiste em conferir os IDs citados no código. O que você copia?

O RetrievalQA, porque é a forma atual do framework

A checagem dos IDs, com a busca e a chamada no jeito da documentação atual

Nada de framework: a página Python com o SDK é a única forma aceita