Claude Agent SDK e LangGraph criam agentes de IA, mas discordam sobre quem decide o próximo passo. Esta comparação analisa o loop de agente contra o grafo explícito, as ferramentas integradas, estado e persistência, aprovação humana, dependência de modelo e custos em produção, e depois apresenta uma regra simples para escolher entre os dois.
Escolher entre o Claude Agent SDK e o LangGraph se resume a uma pergunta: quem deve decidir o que acontece em seguida, o modelo ou o seu código? O Claude Agent SDK entrega à sua aplicação o mesmo loop de agente que roda dentro do Claude Code, então o Claude escolhe as próprias ferramentas e os próprios passos. O LangGraph oferece uma máquina de estados. Você desenha os nós e as arestas, e o modelo faz o trabalho em cada parada. Os dois criam agentes de IA capazes. Só discordam sobre quem segura o volante.
Esta comparação analisa fluxo de controle, ferramentas, estado, aprovação humana, escolha de modelo e custos em produção, para que você escolha um deles antes de escrever mil linhas da coisa errada.
Se o seu agente é, na maior parte, "dê a um modelo capaz boas ferramentas e deixe que ele trabalhe", comece pelo Claude Agent SDK. Se o seu agente é um fluxo de trabalho com etapas fixas, ramificações, novas tentativas e pontos de auditoria, comece pelo LangGraph. A maior parte da confusão desaparece quando você encaixa seu projeto em uma dessas duas formas.
Aqui está o lado a lado antes dos detalhes:
| Pergunta | Claude Agent SDK | LangGraph |
|---|---|---|
| Ideia central | Loop de agente pronto em torno do Claude | Grafo de nós, arestas e estado compartilhado |
| Quem escolhe o próximo passo | O modelo | Seu grafo, com o modelo trabalhando dentro dos nós |
| Modelos | Claude, pela API da Anthropic, Amazon Bedrock ou Google Vertex AI | Qualquer modelo com integração no LangChain |
| Ferramentas integradas | Leitura, escrita e edição de arquivos, shell, busca, busca na web | Nenhuma; você vincula as suas |
| Estado | Sessões com gerenciamento automático de contexto | Estado tipado com um checkpoint por etapa |
| Aprovação humana | Modos de permissão e hooks | Interrupções e retomada |
| Linguagens | Python, TypeScript | Python, JavaScript e TypeScript |
| Melhor uso | Agentes de código, pesquisa, arquivos e shell | Fluxos de trabalho empresariais com várias etapas e roteamento rígido |
💡 Regra prática: conte os passos que você consegue escrever com antecedência. Se dá para listá-los num guardanapo, desenhe um grafo. Se a resposta honesta for "depende do que o agente encontrar", use o loop.
A Anthropic lançou isso primeiro como Claude Code SDK e depois o renomeou para Claude Agent SDK, porque as pessoas o usavam para muito mais do que programação. Você instala claude-agent-sdk para Python ou @anthropic-ai/claude-agent-sdk para TypeScript, chama query() com um prompt e algumas opções, e recebe as mensagens em streaming enquanto o agente trabalha.
Por baixo está o mesmo harness que alimenta o Claude Code. Ele envia contexto ao Claude, executa as ferramentas que o Claude pede, devolve os resultados e repete até o Claude decidir que a tarefa terminou. O que você recebe sem escrever nada disso:
CLAUDE.md e skills carregados do sistema de arquivosO LangGraph vem da equipe do LangChain e foi feito para agentes com estado e de longa duração. Ele chegou à versão 1.0 no fim de 2025. Você define um esquema de estado, escreve os nós como funções comuns, conecta-os com arestas fixas ou condicionais e compila o resultado em um grafo executável.
O grafo é o produto. Cada etapa lê o estado compartilhado e devolve uma atualização, então você pode ver exatamente em que ponto uma execução está a qualquer momento. Os checkpointers salvam esse estado após cada etapa, o que torna possível pausar, retomar e reproduzir. O LangGraph é agnóstico de modelo: qualquer modelo de chat com integração no LangChain se encaixa em um nó, e o LangSmith adiciona rastreamento quando você quer acompanhar as execuções.
Esta é a verdadeira bifurcação do caminho. No SDK, o Claude escolhe o próximo movimento a cada turno: ler outro arquivo, executar um comando, pesquisar na web ou parar. No LangGraph, as arestas escolhem, e o modelo só decide dentro do nó que recebeu.
| Característica | Loop (Claude Agent SDK) | Grafo (LangGraph) |
|---|---|---|
| Previsibilidade | Menor, o modelo improvisa | Maior, os caminhos são declarados |
| Flexibilidade | Alta, lida com tarefas que você não previu | Limitada pelas arestas que você desenhou |
| Depuração | Leia a transcrição das chamadas de ferramenta | Inspecione o estado em cada nó |
| Tempo até a primeira demo | Minutos | Uma tarde para um grafo real |
| Falha típica | Divagação, chamadas extras de ferramenta | Um caminho rígido com um ramo faltando |
Nenhuma abordagem está errada. Um loop lida com surpresas, como um relatório de bug que se revela um problema de configuração. Um grafo garante o processo, como "sempre valide o endereço antes de cobrar o cartão".
Pegue um trabalho simples: auditar um módulo de autenticação e relatar as funções mais arriscadas. Veja como fica com o Claude Agent SDK:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob"],
system_prompt="You review code for security risks.",
)
async for message in query(
prompt="Audit the auth module and list the three riskiest functions.",
options=options,
):
print(message)
asyncio.run(main())
Isso é o programa inteiro. O Claude decide quais arquivos abrir, em que ordem, e quando já viu o suficiente.
Agora o mesmo trabalho no LangGraph, com uma etapa de revisão garantida. Os auxiliares run_audit e passes_checks são marcadores para o seu próprio código:
from typing import TypedDict
from langgraph.graph import StateGraph, START, END
class State(TypedDict):
question: str
report: str
approved: bool
def audit(state: State) -> dict:
return {"report": run_audit(state["question"])}
def review(state: State) -> dict:
return {"approved": passes_checks(state["report"])}
def route(state: State) -> str:
return "done" if state["approved"] else "retry"
builder = StateGraph(State)
builder.add_node("audit", audit)
builder.add_node("review", review)
builder.add_edge(START, "audit")
builder.add_edge("audit", "review")
builder.add_conditional_edges("review", route, {"done": END, "retry": "audit"})
graph = builder.compile()
Aqui, você escreveu o processo: todo relatório passa por revisão, e uma revisão reprovada sempre volta para a etapa de correção. O modelo nunca consegue pular a revisão. O preço é o trabalho de infraestrutura: mais código, mais decisões e um grafo para manter.
O SDK cuida da delegação com subagentes. Você define cada auxiliar com uma descrição, um prompt e uma lista restrita de ferramentas, e o agente principal repassa o trabalho a eles. Cada subagente roda no próprio contexto, o que mantém a janela do agente principal limpa. É rápido de configurar, e as decisões de delegação continuam com o Claude.
O LangGraph modela o mesmo conceito como subgrafos ou um nó supervisor que roteia para nós de trabalhadores. As transferências são explícitas, o estado compartilhado é tipado e você pode testar cada trabalhador isoladamente. Quando cinco agentes precisam cooperar numa ordem fixa, essa explicitude compensa. Quando os agentes são especialistas independentes, pode parecer burocracia.
O SDK já vem com uma caixa de ferramentas completa, e por isso parece produtivo desde o primeiro dia. Um agente que consegue ler um repositório, editar arquivos e rodar testes funciona assim que você passa allowed_tools. Ferramentas personalizadas entram por servidores MCP em processo ou por qualquer servidor MCP externo. Restringir a caixa importa tanto quanto encher: o Bash é poderoso, então entregue-o apenas aos agentes que precisam dele.
O LangGraph começa com uma bancada vazia. As ferramentas são funções que você vincula a um modelo dentro de um nó, e um nó de ferramentas pronto executa as chamadas. Isso significa mais configuração e mais liberdade: uma ferramenta pode ser qualquer coisa que Python ou JavaScript consiga chamar, e você decide o que cada nó pode acessar.
O SDK acompanha uma sessão. Cada execução tem um ID, e você pode retomá-la depois com todo o histórico da conversa, ou bifurcá-la para testar outra direção. O harness compacta turnos antigos para que tarefas longas não sufoquem no contexto.
O LangGraph acompanha um checkpoint para cada etapa, agrupado por thread. Você pode retomar uma thread depois de uma falha, reproduzir a partir de uma etapa anterior ou editar o estado e ramificar a partir dali. Um armazenamento separado guarda a memória de longo prazo compartilhada entre threads, como preferências do usuário.
💡 A diferença: uma sessão lembra da conversa. Um checkpoint lembra em que ponto o fluxo de trabalho está. Se o seu agente precisa recomeçar na etapa quatro de sete, em outro servidor, os checkpoints são o encaixe natural.
Agentes que mexem com dinheiro, dados de produção ou e-mails de clientes precisam de uma pessoa no circuito. As duas ferramentas oferecem isso, em lugares diferentes.
O SDK protege as ações. Os modos de permissão vão de pedir confirmação para tudo, a aceitar edições de arquivo automaticamente, até um modo somente leitura para planejamento. Você pode permitir ou negar ferramentas pelo nome, fornecer um callback que aprova cada chamada e anexar hooks que rodam antes de uma ferramenta executar e podem bloqueá-la ou reescrevê-la. Um hook que recusa qualquer comando de shell contendo rm -rf é uma função curta.
O LangGraph protege as etapas. Um nó chama interrupt(), o grafo para e o checkpointer guarda tudo. Horas ou dias depois, uma pessoa responde, você retoma com um Command e a execução continua exatamente do mesmo ponto, mesmo em outra máquina. Isso torna simples construir filas de aprovação, como reembolsos acima de um limite.
Qual é melhor? Se você se preocupa com o que o agente tem permissão de fazer, as permissões do SDK servem. Se você se preocupa com quando uma pessoa precisa dar aval em um processo de negócio, as interrupções do LangGraph servem.
O Claude Agent SDK roda modelos Claude. Você pode acessá-los pela API da Anthropic ou por provedores de nuvem como Amazon Bedrock e Google Vertex AI, mas não pode trocar por outro fornecedor. Se o Claude já é a sua escolha, isso é um recurso, porque o harness é ajustado para a forma como o Claude usa ferramentas.
O LangGraph é neutro. Você pode rodar um nó num modelo rápido e barato para roteamento, outro num modelo forte de raciocínio, e trocar qualquer um com uma mudança de configuração. Antes de se comprometer, rode o mesmo prompt de agente em vários modelos na PicassoIA: Claude Sonnet 5 para programação e uso de ferramentas equilibrados, Claude Opus 4.7 para raciocínio mais difícil, Claude Fable 5 para tarefas complexas de programação, GPT 5.6 Sol, Gemini 3.1 Pro e Kimi K2.6, que é apresentado para a criação de agentes. Se um fornecedor claramente vencer na sua tarefa, a questão da dependência se responde sozinha.
Um agente do SDK roda o runtime do Claude Code, então implante-o onde esse runtime pode rodar, normalmente um contêiner com sistema de arquivos bloqueado. Como o agente pode executar comandos de shell, o sandboxing não é opcional. Para visibilidade, você tem o fluxo de mensagens, as transcrições salvas e hooks que registram cada chamada de ferramenta.
Agentes do LangGraph são serviços comuns. O LangSmith rastreia cada nó, um estúdio visual permite percorrer o estado passo a passo, e existe uma opção de implantação hospedada para grafos de longa duração. A execução durável por meio de checkpoints significa que um redeploy ou uma falha não apaga uma execução em andamento.
Os dois são gratuitos para instalar. A conta são os tokens do modelo mais a hospedagem. Os loops tendem a custar mais quando a tarefa é vaga, porque o modelo pode abrir dez arquivos quando três bastariam. Os grafos permitem limitar isso: envie passos fáceis para um modelo pequeno, limite as novas tentativas com um limite de recursão e dispense o modelo por completo nas etapas determinísticas. O outro lado é que um loop muitas vezes chega a um resultado funcional mais cedo em trabalhos abertos, porque ninguém precisa desenhar o grafo antes.
Eles não são mutuamente exclusivos. Um padrão comum usa o LangGraph como fluxo de trabalho externo, com um nó que chama o Claude Agent SDK para a parte aberta, como "corrija os testes que estão falhando". O grafo cuida do roteamento, da aprovação e das novas tentativas. O SDK cuida do meio confuso.
| Sua situação | Melhor escolha |
|---|---|
| Desenvolvedor solo lançando um agente de código esta semana | Claude Agent SDK |
| Fluxo de suporte com aprovações de reembolso | LangGraph |
| Assistente de pesquisa construído sobre o Claude | Claude Agent SDK |
| Pipeline que mistura modelos de três fornecedores | LangGraph |
| Etapa de reparo aberta dentro de um fluxo regulamentado | Os dois |
💡 Vale lembrar: os dois projetos lançam mudanças com rapidez. Confira as notas de versão de cada um antes de confiar em qualquer detalhe aqui, especialmente nomes de opções e valores padrão.
A melhor forma de resolver um debate sobre frameworks é testar em algo pequeno. O mesmo vale para o visual. Seu projeto de agente vai precisar de uma imagem de destaque para o README, uma foto para o post de lançamento ou um moodboard para a página do produto, e a Picasso IA torna isso rápido.
Teste seu prompt de agente com o Claude Sonnet 5 na PicassoIA:
Depois, crie algo para acompanhar. Descreva uma cena, como uma equipe de software diante de um quadro branco sob luz suave da manhã, fotografada em filme 35mm, e gere em segundos. Explore todos os modelos disponíveis em picassoia.com/en/all-models, teste três ou quatro prompts e veja até onde uma única frase leva você. Seu próximo agente merece um lançamento bonito.
Escolha seu idioma
