O que são os Deep Agents do LangGraph? O ambiente de desenvolvimento explicado

Um único loop de chamada de ferramenta funciona bem para uma tarefa que termina em quatro etapas. Mas ele falha em trabalhos que levam uma hora. O modelo perde o fio da meada do que estava fazendo, o histórico da conversa excede a janela de contexto e um resultado grande de uma ferramenta acaba comprometendo todo o restante do processo.

O que separa uma demonstração de um agente funcional é o harness: planejamento para que o agente possa decompor e rastrear seu próprio trabalho, um local para armazenar estados intermediários que não seja o histórico de mensagens, delegação para que subtarefas tenham um contexto limpo e compactação para que execuções longas não se percam. O LangGraph Deep Agents é a solução empacotada da LangChain para esses quatro pontos.

O que são Deep Agents?

Deep Agents é um harness de agentes de código aberto, licenciado sob a MIT, criado pela equipe da LangChain e distribuído como o pacote deepagents no Python e deepagents no npm para JavaScript e TypeScript. Ele já acumulou cerca de 15.000 estrelas no GitHub desde o seu lançamento.

O ponto de entrada é uma única função:‍


from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[search, fetch_page, run_query],
)

agent.invoke({"messages": "Research LangGraph and write a summary"})

Essa chamada retorna um grafo LangGraph compilado, pronto para ser invocado ou implantado. Por trás, o harness já anexou uma ferramenta de planejamento, acesso ao sistema de arquivos, capacidade de subagente, sumarização e um prompt de sistema integrado que instrui o modelo sobre como usar tudo isso. Você fornece o modelo e suas ferramentas de domínio; o harness fornece a estrutura.

O pacote JavaScript publica pontos de entrada específicos para cada ambiente (deepagents para Node, deepagents/browser para uso seguro no navegador) e declara os pacotes de runtime da LangChain como dependências de par (peer dependencies), para que sua aplicação controle as versões e tudo seja resolvido em uma única cópia compartilhada.

O que o harness realmente adiciona?

O Deep Agents é montado a partir de middleware. Cada peça anexa ferramentas e instruções de prompt ao agente, e você pode substituir ou remover qualquer uma delas. Entender o conjunto padrão é a maneira mais rápida de compreender o que você está recebendo.

Middleware de Lista de Tarefas

Adiciona uma ferramenta write_todos . O agente divide um objetivo em tarefas, registra-as e atualiza o progresso conforme avança. Isso parece trivial, mas não é: um plano explícito e editável é o que permite que um modelo retome seu lugar após vinte chamadas de ferramentas, em vez de ficar à deriva.

Middleware de sistema de arquivos

Adiciona ls,read_file,write_file,edit_file,glob,grepedelete, além de uma ferramenta execute opcional quando o backend oferece suporte. O sistema de arquivos é a memória de trabalho do agente. Em vez de carregar uma extração de 40.000 tokens no histórico de mensagens, o agente a escreve em um arquivo e usa o grep para encontrar a parte de que precisa mais tarde.

Middleware de Subagente

Adiciona uma ferramenta task para delegar trabalho a subagentes, cada um executando com uma janela de contexto isolada. O agente principal recebe de volta um resultado em vez de toda a exploração que o produziu, o que é a forma mais eficaz de controle de contexto disponível.

Há também suporte a subagentes assíncronos via Protocolo de Agente, onde os subagentes retornam imediatamente com um ID de tarefa e o agente principal continua trabalhando enquanto eles são executados. Esses IDs de tarefa são persistidos no estado do agente em async_tasks, para que sobrevivam à compactação e ao descarregamento de contexto. Funciona com a LangGraph Platform ou qualquer servidor auto-hospedado que implemente a especificação do Protocolo de Agente.

Middleware de Resumo

Condensa o histórico de mensagens quando uma conversa ultrapassa o limite de contexto. Esta é a parte que a maioria das equipes escreve mal manualmente, geralmente truncando o início e perdendo silenciosamente as instruções originais.

Middleware de Cache de Prompt da Anthropic

Reduz automaticamente o processamento redundante de tokens em modelos da Anthropic. Em uma execução longa de agente, onde o prompt do sistema e as definições de ferramentas são reenviados a cada etapa, isso representa uma economia direta na fatura.

Middleware de Correção de Chamadas de Ferramentas

Repara o histórico de mensagens quando chamadas de ferramentas são interrompidas ou canceladas antes de retornarem resultados. Uma correção simples para um problema que, de outra forma, causaria erros de validação no lado do provedor no meio de uma execução.

Dois outros são anexados quando você usa os recursos relevantes: MemoryMiddleware persiste o contexto entre sessões, carregando a memória do agente a partir de arquivos AGENTS.md , e SkillsMiddleware habilita habilidades personalizadas.

O Sistema de Arquivos Virtual e seus Backends

O sistema de arquivos merece sua própria seção porque muito do que existe depende dele. Habilidades, memória, execução de código e gerenciamento de contexto leem e escrevem através do mesmo sistema de arquivos virtual, e o mesmo vale para suas próprias ferramentas e middlewares personalizados.

Ele é conectável. Os backends incluem estado em memória, disco local, armazenamento LangGraph, roteamento composto entre vários backends e backends de sandbox para execução isolada. Trocar de backend altera onde os arquivos residem fisicamente sem alterar o código do agente, o que permite que o mesmo agente seja executado em um notebook, em CI e em produção.

O harness também suporta regras de permissão declarativas que controlam quais arquivos e diretórios o agente pode ler ou escrever. As regras são passadas como uma lista na criação do agente, avaliadas na ordem de declaração com semântica de "primeira correspondência vence", e aplicam-se às ferramentas de sistema de arquivos integradas. Vale notar para quem projeta agentes com privilégio mínimo: subagentes declarativos não herdam as restrições de sistema de arquivos do pai. Você precisa fornecer ao subagente sua própria instância de FilesystemMiddleware para restringi-lo de forma independente.

Deep Agents é construído sobre o LangGraph, não é uma alternativa a ele

É aqui que a maioria das coberturas sobre o assunto se equivoca, por isso vale a pena ser direto. Pesquisar por "deep agents vs langgraph" sugere uma escolha entre duas opções. Não existe tal escolha. create_deep_agent() retorna um grafo LangGraph. Deep Agents é o LangGraph com um harness pré-montado por cima.

A LangChain descreve três camadas da mesma estrutura:

• Deep Agents quando você quer a estrutura completa com planejamento, gerenciamento de contexto e delegação já integrados
• create_agent quando você quer uma estrutura mais leve, sem o middleware incluído
• LangGraph quando o loop do agente em si não é o formato ideal e você precisa de um grafo personalizado

As camadas se complementam em vez de competir. Qualquer LangGraph CompiledStateGraph pode ser passado como um subagente para um agente complexo (deep agent), permitindo que a orquestração personalizada se encaixe junto aos padrões da estrutura. Você pode começar com create_deep_agent(), encontrar um fluxo de trabalho que o loop padrão não lida bem, construir essa parte específica como um grafo LangGraph e entregá-la à estrutura como um subagente. Nada é descartado.

Se você ainda está tentando entender onde o LangGraph se encaixa em relação ao ecossistema mais amplo do LangChain, nossa análise comparativa entre LangChain e LangGraph cobre essa camada.

Deep Agents vs create_agent vs LangGraph

A decisão tem menos a ver com capacidade e mais com o quanto da estrutura você deseja controlar. Cada padrão que você aceita é algo que você não precisa construir, mas também algo que não pode alterar sem descer um nível.

Quando usar cada camada

Use Deep Agents quando o trabalho for de longo prazo e abrangente: pesquisas que envolvem dezenas de fontes, alterações de código em vários arquivos, geração de documentos onde o agente precisa de um local para armazenar rascunhos. Use também quando quiser um agente funcional pronto para esta semana, em vez de no próximo mês.

Use create_agent quando você souber exatamente quais ferramentas precisa e a tarefa for concluída em poucos passos. Carregar uma ferramenta de planejamento e um sistema de arquivos virtual em um agente de classificação de três etapas apenas adiciona sobrecarga de prompt e latência desnecessárias.

Use o LangGraph diretamente quando o fluxo de controle for o problema real: ramificações explícitas, roteamento determinístico, etapas de aprovação humana em nós específicos, ciclos que não são apenas um loop de chamada de ferramenta. Se você sente que está lutando contra a estrutura para expressar seu fluxo, é porque você a superou. Para os padrões multiagentes que vão além de um único agente, nosso guia sobre orquestração multiagente cobre esse assunto.

Uma alternativa melhor para produção: TrueForge Agent Harness

O LangChain Deep Agents resolve grande parte do trabalho pesado dentro de um agente individual, incluindo planejamento, subagentes, ferramentas de sistema de arquivos, habilidades, memória e execução de longa duração. Mas, quando você começa a executar agentes em várias equipes, o problema deixa de ser a construção do agente e passa a seroperar a frota.

TrueForgeé o harness de agentes de código aberto e independente de fornecedor da TrueFoundry para essa camada de tempo de execução. Ele executa o loop do agente em torno do modelo, incluindo planejamento, chamadas de ferramentas, gerenciamento de contexto, aprovações e estado da sessão, permitindo que você utilize seus próprios modelos, servidores MCP e provedores de sandbox.

Você pode executá-lo localmente comnpx @truefoundry/trueforge, ou implante o mesmo harness para uma equipe usando Docker Compose ou Helm.Consulte a documentação do TrueForge.

Otimizando o tempo de execução do agente

O TrueForge também oferece vários mecanismos para controlar a quantidade de contexto e dados de ferramentas que chegam ao modelo.

Carregamento de ferramentas sob demandasignifica que os esquemas de ferramentas MCP são carregados conforme a necessidade, em vez de preencherem a janela de contexto antecipadamente. O Modo de Código permite que o agente encadeie várias chamadas de ferramentas dentro de um único script de sandbox, de modo que apenas o resumo impresso entre no contexto, e não cada resultado intermediário.Respostas de ferramentas muito grandes são transferidaspara um arquivo de sandbox e substituídas por um caminho e uma prévia. A compactação é acionada em 80% do limite de contexto do modelo e substitui o histórico antigo por um resumo estruturado, que é a resposta direta para a repetição. Subagentes são executados com seu próprio contexto limpo e retornam apenas o resultado.

O modelo de sandbox é a outra alavanca. A maioria das estruturas envolve toda a sessão em um contêiner. O TrueForge trata o sandbox como uma ferramenta e o inicializa apenas quando o agente realmente precisa executar código; assim, um servidor executa vários agentes simultaneamente e as tarefas que não envolvem código permanecem de baixo custo.

Muito mais que uma biblioteca Python

O TrueForge também é estruturado como um runtime, e não apenas como uma interface de biblioteca.

Oservidor principalexecuta o loop do agente e fornece streaming, portões de aprovação, delegação de subagentes, compactação e sessões persistentes. UmAPI HTTP e SDK TypeScript(@truefoundry/trueforge-sdk) expõe as mesmas capacidades programaticamente. Umainterface de chat e SDK de UI(@truefoundry/trueforge-ui) separada pode ser usada diretamente, personalizada ou incorporada a outro produto.

Isso oferece às equipes uma superfície de implantação que vai além da definição do agente em Python: o mesmo runtime pode alimentar uma aplicação, uma API ou uma experiência de agente incorporada.

Modelos, servidores MCP e provedores de sandbox são de sua escolha. Quando um modelo mais barato é lançado, você aponta para ele em vez de reescrever o agente, que é como o mesmo benchmark executado no GLM-5.2 resolveu cerca de 11 das 14 tarefas por US$ 2,90 por execução.

Deep Agents vs. Benchmark do TrueForge

A diferença entre um framework de agente e um runtime de agente fica mais clara quando você os compara com as mesmas cargas de trabalho. A TrueFoundry comparou oTrueForge e o Deep Agentsno Enterprise-Bench da DevRev, que consiste em 14 tarefas corporativas entre sistemas. Cada tarefa exige que o agente planeje, chame ferramentas MCP em um CRM, rastreador de projetos e repositório de documentos, combine os resultados e retorne uma resposta que atenda aos critérios de avaliação. Ambas as estruturas executaram as mesmas tarefas com os mesmos servidores MCP, e as respostas foram pontuadas por um juiz LLM cego.

ComOpus 4.8 mantido constante, os dois ambientes de execução produziram uma precisão de tarefa semelhante, mas seus custos de execução foram diferentes:

O benchmark mostra uma diferença relativamente pequena na precisão da tarefa, mas uma diferença muito maior no custo de execução. O TrueForge usoumenos de um quarto dos tokensusados pelo Deep Agents e foi aproximadamente2,5 vezes mais barato por execuçãono mesmo modelo.

The Runtime Layer for Production AI Agents

Run production agents with an open-source runtime for your models, MCP tools, sandboxing, approvals, and observability.

Explore TrueForge

View on GitHub

A diferença vem, em grande parte, de como os dois runtimes lidam com a orquestração e o contexto. O Deep Agents oferece recursos como planejamento, um sistema de arquivos virtual e subagentes, mas eles também podem adicionar mais orquestração e contexto a cada turno. O TrueForge adota uma abordagem mais enxuta, usando chamadas de ferramentas direcionadas e compactação de contexto para evitar o envio repetido de grandes históricos e respostas de ferramentas de volta ao modelo. Isso é importante porqueo custo de um agente não é determinado apenas pelo preço do modelo. Dois sistemas de agentes executando o mesmo modelo podem ter um consumo de tokens muito diferente, dependendo de como implementam o planejamento, o uso de ferramentas, o gerenciamento de contexto e os subagentes.

Conectando o Runtime do Agente à Camada de Plataforma

O TrueForge também pode se conectar ao AI Gateway e ao MCP Gateway da TrueFoundry para fornecer os controles que se tornam importantes quando os agentes deixam de ser projetos isolados, incluindoacesso centralizado a modelos, credenciais MCP, RBAC, orçamentos, guardrails, rotação de credenciais e rastreamento unificado. Isso transfere essas preocupações das definições individuais de agentes para uma camada de plataforma compartilhada.

Para equipes que avaliam o Deep Agents para produção, o benchmark é um lembrete útil de que o framework é apenas uma parte da pilha. Aarquitetura de runtime em torno do agente pode ter um impacto significativo no uso de tokens, na latência e no custo. O TrueForge foi projetado para fornecer essa camada de runtime, mantendo as escolhas de modelo e infraestrutura abertas.

Conclusão

Deep Agents, create_agent, e LangGraph ocupam diferentes níveis de abstração na pilha de agentes do LangChain. create_agent oferece um loop de agente leve, enquanto o LangGraph fornece as primitivas de grafo subjacentes para desenvolvedores que precisam definir o fluxo de execução por conta própria. O Deep Agents é construído sobre o LangGraph para oferecer um ambiente de agente mais completo, com planejamento, subagentes, gerenciamento de contexto e recursos de sistema de arquivos.

A escolha, portanto, resume-se a quanto do tempo de execução do agente você deseja controlar. Se um loop de agente padrão e os recursos integrados forem suficientes, o Deep Agents reduz a quantidade de infraestrutura que você precisa construir. Se você precisa de um loop leve, create_agent oferece um ponto de partida mais simples. Quando o fluxo de execução em si é o requisito principal, o LangGraph fornece as primitivas para projetá-lo explicitamente.

Para equipes que buscam além do ecossistema LangChain, TrueForge adota outra abordagem: um ambiente de agente de código aberto e independente de modelo que fornece a camada de tempo de execução, mantendo o modelo e a infraestrutura subjacente sob seu controle.

Perguntas frequentes

P: O que são os LangGraph Deep Agents?

‍R: O Deep Agents é o ambiente de agente de código aberto do LangChain, licenciado sob a licença MIT e construído sobre o LangGraph. Chamar create_deep_agent() retorna um grafo LangGraph compilado com planejamento, um sistema de arquivos virtual, delegação de subagentes, sumarização e cache de prompts já integrados como middleware. Ele existe para que as equipes não precisem construir manualmente a estrutura necessária para agentes de longa execução.

P: O Deep Agents substitui o LangGraph?

‍R: Não. O Deep Agents é construído sobre o LangGraph e retorna um grafo LangGraph. Eles são camadas da mesma pilha, não opções concorrentes. Use o Deep Agents quando o formato padrão de agente atender à sua tarefa e recorra ao LangGraph quando precisar de um fluxo de controle personalizado. Qualquer grafo LangGraph pode ser passado de volta para um deep agent como um subagente.

P: Qual middleware um deep agent inclui por padrão?

‍R: Seis componentes: TodoListMiddleware para planejamento, FilesystemMiddleware para operações de arquivo, SubAgentMiddleware para delegação com contexto isolado, SummarizationMiddleware para compactação de contexto, AnthropicPromptCachingMiddleware para economia de tokens em modelos da Anthropic, e PatchToolCallsMiddleware para reparar chamadas de ferramentas interrompidas. MemoryMiddlewareeSkillsMiddleware anexe ao usar memória ou habilidades.

P: O TrueFoundry oferece suporte a MCP e agentes de IA?

‍R: Sim. A TrueFoundry inclui um Gateway MCP, um Gateway de Agentes e um Registro de MCP e Agentes com controle de acesso em nível de ferramenta. Agentes criados em Deep Agents, LangGraph, CrewAI, AutoGen ou frameworks personalizados podem ser implantados e gerenciados centralmente.

P: Posso implantar o TrueFoundry na minha própria VPC ou on-premise?

‍R: Sim. A TrueFoundry é executada em sua VPC, on-premise, em ambientes isolados (air-gapped), híbridos ou em múltiplas nuvens, e nenhum dado sai do seu domínio. Este é o principal motivo pelo qual empresas em setores regulamentados a escolhem em vez de gateways apenas SaaS.

P: Ele se integra à minha stack de observabilidade existente?

‍R: Sim. O gateway é compatível com OpenTelemetry e se integra ao Grafana, Datadog, Prometheus ou qualquer ferramenta que você já utilize, rastreando cada solicitação desde o prompt até a execução da ferramenta e do modelo.

Leituras relacionadas

• CrewAI vs LangGraph — como o LangGraph se compara ao outro principal framework multiagente
• AutoGen vs LangGraph — a mesma comparação em relação ao framework da Microsoft
• Preços do LangGraph — quanto o LangGraph e a LangGraph Platform realmente custam
• Agentes de LLM: arquitetura e padrões — a introdução por trás desta publicação
• TrueForge: um ambiente de desenvolvimento de agentes open-source — nossa abordagem para o mesmo problema