OpenAI Agents SDK vs LangGraph: comparação prática para escolher o framework

Uma equipe monta um protótipo de agente de suporte com LangGraph. Quando ele começa a rodar, fica claro que a maioria dos nós faz a mesma coisa: chama um modelo e depois chama uma ferramenta. O código está organizado, mas o boilerplate aparece. Então surge a pergunta: dá para trocar por OpenAI Agents SDK e remover essa camada?

Outro cenário é mais delicado. Um agente de relatórios roda 20 minutos por dia e, no meio do caminho, precisa esperar uma pessoa aprovar o SQL para continuar. Nesse ponto, “menos código” deixa de ser a única métrica. Pausar, retomar e auditar passam a importar mais. OpenAI Agents SDK tem sessions e guardrails, mas consegue substituir checkpoints e interrupts do LangGraph?

Os dois cenários levam à mesma pergunta: OpenAI Agents SDK parece leve, mas ele serve para substituir LangGraph ou apenas parte das tarefas? A decisão real é entender se seu agente só precisa de modelos, ferramentas e delegação, ou se já precisa de estado persistente, pausas humanas, execução retomável e replay para auditoria.

Primeiro esclareça a camada: não é a mesma abstração

Antes de falar em substituição, vale separar os papéis. A OpenAI descreve Agents SDK como um toolkit leve, fácil de usar e com poucas abstrações para construir agentic apps. O centro é agent loop, tool calls, handoff, guardrails e tracing. LangGraph se posiciona como infraestrutura de orquestração de baixo nível para workflows longos e com estado. O centro é grafo de estado explícito, persistência por checkpoint, interrupts, resume, time travel e fault tolerance.

Um se parece mais com um runtime de conversa e delegação. O outro se parece mais com uma máquina de estados direcionada. A diferença de abstração fica assim:

Essa tabela mostra a divisão principal: Agents SDK fica mais perto de primitivas de runtime de agente, enquanto LangGraph fica mais perto de orquestração de workflow com estado. Se você só precisa de um agent loop que chama ferramentas e às vezes delega para um agente especialista, Agents SDK pode bastar. Se a tarefa precisa pausar, retomar, ser auditada ou continuar após uma falha, checkpoints e interrupts do LangGraph são a parte importante.

Não é uma discussão sobre qual é “mais forte”. Eles atuam em camadas diferentes. Agents SDK é como um SDK com tracing para rodar agentes. LangGraph é como um motor de máquina de estados com camada de persistência. Se seu processo pode ser desenhado como transições claras de estado, LangGraph geralmente combina melhor. Se é basicamente “modelo + ferramentas + escalonamento ocasional”, Agents SDK pode ser mais leve. Para entender melhor por que prompts não substituem uma máquina de estados, veja máquinas de estado de agentes e limites de workflow.

Matriz de capacidades: 10 dimensões práticas

Camadas diferentes não impedem uma comparação prática. A tabela abaixo compara os dois frameworks em 10 dimensões de engenharia:

As diferenças mais importantes estão em persistência de estado, recuperação de falhas e workflows reproduzíveis. Sessions do Agents SDK servem para continuidade de conversa. Checkpointers do LangGraph salvam o estado inteiro do grafo: histórico de nós, variáveis intermediárias e entradas externas em espera. Se um agente de relatórios cai no meio da execução, Agents SDK normalmente precisa começar do zero. LangGraph pode continuar do último checkpoint e evitar repetir etapas concluídas.

Outra diferença importante é HITL. Agents SDK tem guardrails e HITL API, úteis para validar entradas e saídas, mas o mecanismo de guardrail é um tripwire: quando dispara, a execução para. Interrupts do LangGraph são pausas da máquina de estados. interrupt() pode pausar dentro de um nó, o checkpointer salva o estado atual e depois a execução retoma com Command(resume=...). Isso permite pausar antes de um tool call, aguardar aprovação e continuar. Guardrails do Agents SDK servem melhor para “parar se a entrada estiver fora do escopo” do que para “pausar, revisar e continuar”. Para uma visão mais completa, veja design de aprovação human-in-the-loop para agentes.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

A terceira diferença é replay. Time travel do LangGraph permite voltar a qualquer checkpoint, inspecionar estado e caminho de execução, e depurar ou auditar. Tracing do Agents SDK visualiza o caminho, mas não volta a um estado histórico para reexecutar dali. Se o cenário exige responder “por que ele escolheu esse ramo duas horas atrás?”, LangGraph combina melhor.

O que Agents SDK oferece: primitivas centrais

OpenAI Agents SDK gira em torno de cinco primitivas: Agents, Handoffs, Guardrails, Tracing e Sessions/HITL/MCP. Na prática:

Agents: um agente combina um LLM, instructions, tools e comportamento runtime opcional. Esse comportamento inclui handoffs para outros agentes, guardrails para checagens de input/output e structured outputs para formatos específicos. Agent e Runner trabalham juntos para o SDK gerenciar agent loop, turns, tool calls, guardrail checks e delegação por handoff.

Handoffs: um handoff permite que um agente delegue trabalho para outro. Na prática, o agente de destino é exposto ao LLM como uma ferramenta. handoff() pode configurar agente destino, nome e descrição da ferramenta, on_handoff, input_type, input_filter e is_enabled. Isso funciona bem em cenários com especialistas, como um agente de suporte que classifica o problema e passa para suporte técnico ou consulta de pedidos.

Guardrails: guardrails atuam em duas camadas: input e output. Input guardrails verificam a entrada do usuário antes de ela chegar ao agente. Output guardrails verificam a resposta antes de ela ser retornada. Um tripwire interrompe a execução. Isso serve para “parar se a entrada estiver fora do escopo” ou “bloquear saída com informação sensível”. Os exemplos oficiais usam um modelo mais rápido para checar se a solicitação está dentro do escopo.

Tracing: o SDK traz tracing para LLM generations, tool calls, handoffs, guardrail checks e custom events dentro de um agent run. Cada span registra tempos e metadata, ajudando em debug, visualização e monitoramento de workflows. O tracing vem ativado por padrão, e trace_include_sensitive_data controla se campos sensíveis são registrados.

Sessions, HITL e MCP tools: sessions dão continuidade de conversa: vários runs com o mesmo session_id compartilham histórico. A HITL API pode aguardar entrada externa durante a execução, mas seu modelo de interrupção não é a mesma abstração dos interrupts do LangGraph. MCP tools permitem que um agente chame ferramentas expostas por MCP servers, gerenciadas como function tools.

Essas primitivas cobrem agent loop, tool calling, delegação, validação, tracing e continuidade de conversa. Elas não oferecem grafo de estado explícito, persistência por checkpoint, interrupts, resume, time travel nem fault tolerance. Se a tarefa é “modelo + ferramentas + delegação ocasional”, Agents SDK pode bastar. Se precisa de “pausa para aprovação + retomada + continuar após falha + auditoria de estado”, LangGraph atende melhor.

Pontos fortes do LangGraph: mecanismos de estado

Os pontos fortes do LangGraph estão na gestão de estado e recuperação: Checkpointers, Interrupts, Time travel, Fault tolerance e Stores. Na prática:

Checkpointers: checkpointers salvam thread graph state como checkpoints. Isso inclui histórico de nós, variáveis intermediárias, entradas externas em espera e posição atual. Cada checkpoint é um snapshot completo de estado, usado para continuidade de conversa, HITL, time travel e fault tolerance. A documentação oficial distingue: sessions do Agents SDK não são checkpointers do LangGraph. Sessions preservam conversa; checkpointers preservam snapshots do estado do grafo.

Interrupts: interrupt() pode pausar a execução dentro de um graph node. O checkpointer salva o estado atual e espera entrada externa. A retomada usa Command(resume=...), e o mesmo thread_id funciona como cursor persistente. A documentação lista padrões como approval workflows, review/edit state, interrupting tool calls e validating human input. Isso difere de guardrail tripwires do Agents SDK: interrupt pausa a máquina de estados; guardrail para a execução.

Time travel: time travel permite voltar a qualquer checkpoint e ver o estado e o caminho de execução daquele momento. Serve para auditoria, debug e reprodução de problemas, por exemplo “por que ele escolheu esse ramo duas horas atrás?”. Tracing do Agents SDK visualiza um caminho, mas não reexecuta a partir de um estado histórico.

Fault tolerance: fault tolerance é a capacidade de continuar depois de uma falha. Se um agente de relatórios cai no meio do run, LangGraph pode retomar do último checkpoint e evitar repetir etapas concluídas. Agents SDK não tem fault tolerance integrada, então o run geralmente recomeça.

Stores: stores salvam dados de longo prazo entre threads, como preferências de usuário, histórico ou estado de negócio. A documentação separa stores de checkpointers: checkpointers salvam thread graph state; stores salvam dados persistentes entre threads. Se vários agent runs precisam compartilhar estado, stores são a camada adequada.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Esses mecanismos tornam LangGraph mais adequado a workflows longos e com estado: tarefas longas, múltiplos ramos, execução retomável, estado auditável e intervenção humana. Se o projeto já precisa disso, a complexidade do LangGraph se justifica. Se é apenas um tool agent simples ou specialist handoff, Agents SDK é mais leve.

Quando usar Agents SDK

Com base na matriz e nas primitivas, Agents SDK combina melhor com estes cenários:

1. Tool agents simples: busca, resumo e escalonamento ocasional para uma pessoa. Por exemplo, um agente de Q&A de base de conhecimento interna recupera documentos, resume a resposta e, se não tiver certeza, orienta o usuário a falar com suporte. Não precisa de recuperação de estado complexa nem fluxo de aprovação; tools, handoffs e guardrails podem bastar.

2. Handoff para vários especialistas: cenários que delegam para vários agentes especializados. Um agente de suporte classifica o tipo de problema e delega para suporte técnico, consulta de pedidos ou reembolso. Handoffs do Agents SDK são literalmente “agent as tool”, então o padrão encaixa bem.

3. Protótipos rápidos: projetos que precisam validar uma ideia sem desenhar um grafo de estado explícito no começo. Agents SDK tem menos código e sobe mais rápido. Se o protótipo mostra que não precisa de checkpoint ou interrupt, ele pode ir para produção com Agents SDK.

4. Aderência ao ecossistema OpenAI: se o projeto usa principalmente modelos OpenAI, Responses API ou OpenAI hosted tools, Agents SDK é o toolkit oficial e integra com menos atrito. Agentes de voz em tempo real, sandbox agents ou ferramentas hospedadas pela OpenAI são exemplos naturais.

5. Outra camada já gerencia estado: se o projeto já tem banco de dados de negócio, fila ou motor de workflow, Agents SDK pode rodar só o agent loop. Um nó usa Agents SDK para chamar ferramentas, enquanto banco e fila ficam donos do estado.

O padrão comum é simples: sem grafo de estado explícito, sem persistência por checkpoint, sem fluxo de interrupt + resume e sem time travel. Se o projeto tem esse perfil, começar com Agents SDK economiza trabalho.

Quando manter LangGraph

Se o projeto entra nos casos abaixo, a complexidade do LangGraph provavelmente vale a pena:

1. Tarefas longas (20+ minutos): agentes de relatórios, processamento de dados ou análises complexas podem rodar mais de 20 minutos e cair ou expirar no meio. Checkpointers e fault tolerance do LangGraph permitem continuar do último checkpoint. Agents SDK não tem fault tolerance integrada e tende a repetir desde o começo.

2. Aprovação humana é necessária: cenários de tool call interrupt, como apagar dados, enviar email ou mudar permissões, exigem aprovação antes de continuar. Interrupts do LangGraph podem pausar antes do tool call, salvar estado pelo checkpointer e retomar com Command(resume=...). Guardrails do Agents SDK são “disparou, parou”, não “pausa para revisão e continua”.

3. Estado auditável é necessário: alguns sistemas precisam reproduzir estados históricos, revisar caminhos de execução ou auditar decisões. Uma pergunta de compliance como “por que ele escolheu esse ramo duas horas atrás?” exige mais que um trace. Time travel do LangGraph volta a um checkpoint; tracing do Agents SDK mostra o caminho, mas não reexecuta de um estado histórico.

4. A execução precisa continuar após falhas: se um agente cai no meio do run ou a rede falha, o sistema deve continuar e não começar de novo. Fault tolerance do LangGraph retoma de checkpoint. Agents SDK começa do zero. Se a tarefa tem dependências externas, como chamadas API ou escritas em banco que não podem ser repetidas, essa diferença é crítica.

5. Múltiplos ramos, routing condicional ou máquina de estados de negócio: workflows com estados explícitos, condições e transições de negócio combinam melhor com LangGraph. Exemplo de pedido: pagamento aprovado -> envio; pagamento falhou -> cancelamento; pagamento expirou -> intervenção humana. Esse fluxo fica mais claro com grafo de estado explícito do que com handoffs do Agents SDK.

O requisito comum é estado explícito: persistência por checkpoint, interrupts, resume, time travel ou fault tolerance. Se o projeto precisa disso, a complexidade do LangGraph não é excesso; é parte da segurança do sistema.

Decisão de substituição: checklist de quatro passos

Mesmo depois dos cenários, a decisão pode continuar nebulosa. Use este checklist:

Passo 1: liste os requisitos centrais

Quebre o requisito em capacidades concretas: tool calling, recuperação de estado, aprovação humana, tarefas longas, branching, replay para auditoria e recuperação de falhas. Não escreva só “precisamos de um agente”. Seja específico. “Um agente de relatórios roda 20 minutos, espera aprovação de SQL e deve continuar após um crash” são três requisitos: tarefa longa, aprovação e recuperação.

Passo 2: mapeie os requisitos fortes na matriz

Pegue a lista do passo 1 e mapeie nas 10 dimensões acima. “Tarefa longa + aprovação + recuperação de falhas” corresponde a persistência de estado, HITL e recuperação. Agents SDK é fraco ou ausente nessas dimensões, enquanto LangGraph é forte. Se seus requisitos fortes ficam nas fraquezas do Agents SDK, a substituição provavelmente não é adequada.

Passo 3: decida se precisa de um grafo de estado explícito

Faça uma pergunta: meu processo pode ser desenhado como transições claras de estado? Se sim, como um pedido com sucesso, falha, timeout e próximos passos, o grafo explícito do LangGraph combina melhor. Se é principalmente “modelo + ferramentas + delegação ocasional” sem fluxo fixo, Agents SDK pode ser mais leve.

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Passo 4: avalie a tolerância do time à complexidade

LangGraph exige que o time desenhe grafos, estado e nós. Se a tolerância à complexidade é baixa, comece com um protótipo em Agents SDK e só adicione uma camada de estado se necessário. Se o time já tem experiência com workflows ou máquinas de estado, a complexidade do LangGraph pode não pesar.

Depois desses quatro passos, você deve conseguir escolher Agents SDK, LangGraph ou um híbrido. Se ainda está escolhendo frameworks em uma visão mais ampla, use a checklist de engenharia de AI Agents em 2026 como complemento.

Caminhos de migração para projetos LangGraph existentes

Se você já tem um protótipo LangGraph e quer reduzir complexidade com Agents SDK, use esta tabela:

Se você já usa Agents SDK e quer saber quando subir para LangGraph, use esta tabela:

Exemplo de padrão híbrido: não é preciso substituir tudo. LangGraph gerencia o grafo de estado externo, enquanto um nó usa Agents SDK para rodar um agente de tarefa curta. Um agente de relatórios pode usar LangGraph para o fluxo principal: preparação de dados -> geração de SQL -> aprovação humana -> execução da consulta -> exportação. Os nós de geração SQL e exportação não precisam de checkpoints ou interrupts próprios, então podem usar agent loop e tool calls do Agents SDK, enquanto LangGraph mantém o estado.

A chave é responsabilidade: LangGraph é dono da camada de estado; Agents SDK executa nós curtos. Não é uma escolha binária, e sim uma divisão pelas forças de cada ferramenta.

Conclusão

OpenAI Agents SDK e LangGraph não são uma escolha binária. A pergunta real é se você precisa de uma camada de estado. Se o projeto só precisa de agent loop, tool calls, delegação e validação — como Q&A de base de conhecimento, triagem de suporte ou protótipo rápido — comece com Agents SDK. É mais leve e mais rápido para colocar de pé. Se o projeto precisa de recuperação de tarefa longa, aprovação humana, auditoria de estado ou continuação após falhas — como agentes de relatórios, workflows de pedidos ou processos de compliance — checkpoints, interrupts, time travel e fault tolerance do LangGraph são capacidades necessárias.

Você não precisa forçar a substituição. Um híbrido prático é deixar LangGraph gerenciar o grafo de estado externo e Agents SDK rodar nós curtos. A decisão começa pelos requisitos: liste as necessidades centrais, mapeie as mais fortes na matriz e decida se vai manter, substituir ou combinar.

Próximo passo: se você já tem um protótipo LangGraph, use a tabela de migração para identificar quais nós podem ir para Agents SDK. Se ainda está escolhendo framework, use o checklist de quatro passos para decidir primeiro se o projeto precisa de um grafo de estado explícito.