Arquitetura do DeepAgents: ferramentas de planejamento, subagentes e sistema de arquivos

Por que seu AI Agent sempre quebra quando a tarefa fica complexa?

Você pede para ele pesquisar um tema técnico e, depois de 20 passos, a qualidade da saída começa a cair. Pede para refatorar uma codebase e, depois de mexer por um bom tempo, ele perde até funcionalidades que já existiam. Pede um relatório longo e, no meio do caminho, ele começa a repetir frases vazias.

Eu já caí nessa armadilha. Na época, usei um Agent tradicional para pesquisa profunda e queria que ele investigasse as melhores práticas de LangGraph. No começo, a saída era bem organizada. Depois de mais de trinta passos, ele começou a “perder a memória”: esqueceu materiais que já tinha consultado, bagunçou o framework de análise original e entregou um relatório remendado, cheio de contradições.

A raiz desses problemas é a mesma: agentes tradicionais são “Shallow”. Eles só executam uma etapa reativa por vez. Não têm planejamento, não têm sistema de memória, não dividem a tarefa em subtarefas. É como pedir para uma pessoa escrever um relatório de 5000 palavras sem dar um roteiro; no meio do caminho, ela provavelmente sai do trilho.

Mas Claude Code, Deep Research e Manus conseguem concluir tarefas complexas, como refatorar projetos com milhares de linhas de código ou produzir relatórios de pesquisa com dezenas de páginas. Que método eles usam?

A resposta é a arquitetura Deep Agent. A LangChain empacotou essa arquitetura no pacote DeepAgents. Vamos desmontar seus quatro pilares: ferramentas de planejamento, subagentes, sistema de arquivos e system prompts.

Por que precisamos de Deep Agents?

Comecemos por um fato: em tarefas com mais de 10 etapas, a taxa de sucesso de um Agent tradicional cai mais da metade.

Não é chute. Os dados de pesquisa do Prompting Guide mostram que, quando uma tarefa passa de 10 passos, a qualidade da saída de um Shallow Agent começa a cair claramente. Por quê? Porque ele não tem “cérebro”.

O desenho tradicional de um Agent é reativo: recebe uma instrução -> chama uma ferramenta -> retorna um resultado. Cada passo é independente. Não há planejamento de longo prazo nem gestão de estado intermediário. Pense em alguém que precisa limpar uma casa inteira, mas não recebe uma ordem de limpeza e não pode registrar quais cômodos já foram feitos. Essa pessoa talvez limpe metade da cozinha, corra para a sala e depois esqueça que a cozinha ficou inacabada.

Três cenários de colapso são os mais comuns:

Tarefas de pesquisa profunda. Você pede ao Agent para investigar um tema técnico, por exemplo, “melhores práticas de LangGraph em produção”. Ele começa a buscar, ler documentação e extrair informações. Depois de 20 passos, materiais já consultados são empurrados para fora da Context Window, e novos resultados de busca sobrescrevem o framework de análise anterior. No fim, sai um relatório sem coerência entre começo e fim.

Tarefas de refatoração de código. Você pede ao Agent para refatorar um projeto com milhares de linhas. Ele altera um módulo, depois outro, mas esquece a relação de dependência entre os dois. Ao final, funcionalidades que antes rodavam passam a quebrar.

Geração de conteúdo longo. Você pede ao Agent para escrever um artigo técnico de 5000 palavras. Por volta da palavra 2000, ele começa a repetir o que já disse ou se afasta do recorte original.

O núcleo desses problemas é a perda de controle do Context.

Claude Code consegue lidar com refatorações de projetos com milhares de linhas, Deep Research consegue produzir relatórios estruturados com dezenas de páginas, e Manus consegue executar tarefas complexas de múltiplos passos. Não é mágica. É uma estrutura comum: a arquitetura Deep Agent.

Deep Agent significa dar um “cérebro” ao Agent: ele sabe planejar, decompor tarefas, gerenciar memória e verificar progresso. A LangChain encapsulou essa arquitetura no DeepAgents. Vamos ver o desenho concreto.

A arquitetura de quatro pilares do DeepAgents

A filosofia de design do DeepAgents é clara: quebrar tarefas complexas em unidades gerenciáveis, cada uma com responsabilidade definida.

Os quatro pilares trabalham juntos: Planning Tools cuidam do planejamento e do acompanhamento de progresso; Sub-agents trazem divisão especializada e isolamento de Context; File System resolve o armazenamento de memória; System Prompts definem limites de comportamento. Eles funcionam como uma orquestra: há um maestro (Planning), grupos de instrumentos diferentes (Sub-agents), armazenamento da partitura (File System) e regras de execução (System Prompts).

Planning Tools: dar um “cérebro” ao Agent

O núcleo das Planning Tools é todo_write.

O funcionamento é interessante: na essência, é um no-op, uma operação vazia. Ele não executa nenhuma tarefa real; apenas cria e atualiza uma lista de tarefas. Só que essa lista fica na Context Window como working memory, permitindo que o Agent “veja” seu plano e seu progresso durante toda a execução.

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

Começar →Anúncio

Por exemplo, se você pede ao Agent para fazer uma pesquisa técnica, ele primeiro usa todo_write para criar um plano:

- [ ] Buscar a documentação oficial do LangGraph
- [ ] Ler o design de State Machine do LangGraph
- [ ] Extrair casos de melhores práticas
- [ ] Resumir os principais padrões de design
- [ ] Gerar um relatório estruturado

Sempre que conclui uma tarefa, o Agent atualiza a lista e troca [ ] por [x]. Assim, independentemente de quantos passos ele execute, consegue ver a qualquer momento o próprio progresso: o que terminou, o que ainda não começou e o que está em andamento.

Isso resolve um problema central: consistência de objetivos de longo prazo.

Quando um Agent tradicional chega ao passo 20, talvez já tenha esquecido qual era o objetivo definido no passo 1. Já a todo list de um Deep Agent funciona como um lembrete colado na geladeira, sempre dizendo: “o que você precisa fazer mesmo?”.

"As planning tools do Claude Code e do Manus seguem esse mesmo princípio: usar a Context Window como working memory para manter o Agent na direção certa"

Sub-agents: divisão especializada e isolamento de Context

Sub-agents são o segundo pilar de um Deep Agent.

A lógica de design é esta: um orquestrador principal (Orchestrator) cuida do planejamento geral e da distribuição de tarefas, enquanto vários subagentes especializados executam trabalhos específicos. Cada subagente tem sua própria Context Window e, ao concluir, retorna apenas o resultado final ao orquestrador.

Isso traz quatro vantagens importantes:

Context Preservation. A Context Window do orquestrador não é poluída pelas etapas intermediárias dos subagentes. Em um Agent tradicional, uma tarefa de busca joga todos os resultados, conteúdos de páginas e processos de extração dentro do Context. Com Sub-agent, ao terminar, ele retorna apenas um resultado limpo: “encontrei estas informações-chave”. O Context do orquestrador continua limpo.

Specialized Expertise. Cada subagente pode se concentrar em uma área. research_subagent cuida de busca e extração de informações, writer_subagent organiza conteúdo, coder_subagent analisa código. Essa especialização ajuda cada subagente a trabalhar melhor dentro do seu domínio.

Reusability. O mesmo subagente pode ser chamado por vários orquestradores. Por exemplo, research_subagent pode servir para tarefas de pesquisa, escrita e análise. Escreva uma vez, use em vários lugares.

Fine-Grained Permissions. Subagentes podem ter limites de permissão diferentes. Alguns só leem arquivos, outros podem escrever, outros podem acessar a rede. Esse controle fino reduz riscos de segurança.

"A arquitetura Orchestrator-Sub-agent, também chamada de Task Decomposition Pattern, decompõe tarefas complexas em subtarefas e entrega cada uma a uma unidade especializada de processamento"

Como implementar isso na prática? DeepAgents oferece uma API simples:

from deepagents import create_deep_agent, create_subagent

# Definir subagentes
research_subagent = create_subagent(
    name="research",
    tools=[internet_search, read_url],
    description="Responsável especificamente pela busca e extração de informações"
)

writer_subagent = create_subagent(
    name="writer",
    tools=[write_file],
    description="Responsável especificamente pela organização e saída de conteúdo"
)

# Criar o Agent principal
agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    tools=[todo_write, read_file, write_file]
)

Quando o orquestrador chama um subagente, DeepAgents lida automaticamente com a troca de Context e a transmissão de resultados.

File System: contornar o limite da Context Window

Esta é a solução central de um Deep Agent para o problema de memória.

Context Window tem limite de tamanho. Claude fica em torno de 200K tokens; GPT-4, cerca de 128K tokens. Para tarefas curtas, isso basta. Mas, em tarefas longas, como processar milhares de linhas de código ou ler dezenas de documentos, esse espaço enche rápido.

A ideia do File System Backend é inteligente: usar referências a arquivos em vez de carregar tudo diretamente.

O Agent não enfia todo o conteúdo na Context Window. Ele armazena resultados intermediários no sistema de arquivos. Quando precisa de um arquivo, usa a ferramenta read_file para ler sob demanda. É como fazer pesquisa: você não memoriza todas as referências; organiza os materiais em documentos e abre quando precisa consultar.

DeepAgents oferece três tipos de Backend:

StateBackend. Armazenamento em memória, adequado para ambientes de teste e tarefas curtas. O estado do Agent e os resultados intermediários ficam na memória e desaparecem ao fim da sessão. É rápido, mas não persistente.

FilesystemBackend. Armazenamento no sistema de arquivos local, adequado para produção e cenários que exigem persistência. Os resultados intermediários do Agent são gravados em arquivos locais e podem ser lidos na próxima execução. É persistente, mas depende do armazenamento local.

StoreBackend. Armazenamento em nuvem, adequado para implantação corporativa e cenários com auditoria. O estado do Agent fica em um banco de dados na nuvem, com suporte a controle de versão e logs de auditoria. É confiável, mas a configuração é mais complexa.

A escolha do Backend depende do seu cenário. Para testes rápidos, use StateBackend. Para produção, use FilesystemBackend. Para aplicações corporativas que exigem auditoria, use StoreBackend.

A tabela de Context Management Strategy da FlowHunt explica bem a diferença entre esses modelos:

Por padrão, DeepAgents usa um modelo Hybrid: informações-chave ficam no Context, enquanto grandes volumes de dados ficam no sistema de arquivos.

System Prompts: a peça-chave subestimada

System Prompts são o pilar mais fácil de subestimar entre os quatro.

Muita gente acha que System Prompt é só algumas instruções simples, como “você é um assistente útil”. Mas, em um Deep Agent, System Prompts são documentos de engenharia com centenas ou milhares de linhas.

O System Prompt do Claude Code tem centenas de linhas e define normas completas de chamada de ferramentas, fluxo de operação de arquivos e restrições de estilo de código. O System Prompt do Deep Research tem mais de mil linhas, incluindo metodologia de pesquisa, regras de extração de informação e modelos de formato de saída.

Por que um System Prompt precisa ser tão detalhado?

Porque um Agent encontra muitos casos de borda em tarefas longas. Instruções curtas não cobrem todos os cenários. Um System Prompt detalhado serve para:

Definir limites de comportamento. Em que situação chamar todo_write, quando delegar a um sub-agent, quando retornar diretamente o resultado. Essas regras precisam ser detalhadas o suficiente para o Agent tomar decisões corretas.

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

Ganhar 15% off →Anúncio

Padronizar chamadas de ferramentas. Como cada ferramenta deve ser usada, qual é o formato dos parâmetros, como tratar o resultado retornado. Por exemplo, a ferramenta read_file recebe um caminho de arquivo ou um ID de arquivo? Ela retorna conteúdo bruto ou resumo?

Definir formato de saída. Cada tipo de tarefa exige um formato diferente. Relatórios de pesquisa usam estrutura Markdown; refatorações de código usam formato diff; geração de conteúdo usa modelos específicos.

A Middleware Architecture do DeepAgents injeta System Prompts automaticamente. Você não precisa escrever milhares de linhas à mão; o framework gera com base na configuração. Mas entender a função dos System Prompts é importante: eles são a “constituição” do comportamento do Agent.

Terminamos os quatro pilares. Agora vamos ao código.

Análise prática de código com DeepAgents

Veja um exemplo completo de código para implementar um Agent de pesquisa técnica.

from deepagents import create_deep_agent, create_subagent
from langchain_community.tools import TavilyInternetSearch

# 1. Definir ferramentas
search_tool = TavilyInternetSearch(
    name="internet_search",
    description="Buscar informações na internet"
)

# 2. Definir subagentes
research_subagent = create_subagent(
    name="research",
    tools=[search_tool],
    system_prompt="Você é especialista em busca de informações.\
                   Sua tarefa é buscar e extrair informações-chave.\
                   Retorne apenas resultados de pesquisa estruturados, sem incluir etapas intermediárias.",
    description="Subagente responsável pela busca de informações"
)

writer_subagent = create_subagent(
    name="writer",
    tools=[],  # writer não precisa de ferramentas externas
    system_prompt="Você é especialista em organização de conteúdo.\
                   Sua tarefa é organizar resultados de pesquisa e gerar um relatório estruturado.\
                   Use formato Markdown, com uma estrutura clara de seções.",
    description="Subagente responsável pela saída de conteúdo"
)

# 3. Criar Deep Agent
agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    tools=[todo_write, read_file, write_file],
    backend="filesystem"  # Usar armazenamento no sistema de arquivos
)

# 4. Executar tarefa
result = agent.invoke(
    "Pesquisar as melhores práticas de LangGraph e \
     gerar um relatório estruturado de pesquisa"
)

O fluxo de execução é este:

Primeiro passo: Plan. O Agent chama todo_write para criar uma lista de planejamento.

todo_write([
    "Buscar a documentação oficial do LangGraph",
    "Ler o design da arquitetura principal",
    "Extrair casos de melhores práticas",
    "Resumir padrões de design",
    "Gerar relatório estruturado"
])

Segundo passo: Delegate. O Agent chama research_subagent para executar a tarefa de busca.

call_subagent("research", "Buscar documentos relacionados a melhores práticas de LangGraph")

research_subagent chama a ferramenta internet_search, obtém resultados de busca, extrai informações-chave e retorna um resultado estruturado limpo ao orquestrador. A Context Window do orquestrador recebe apenas um resumo como “encontrei 5 melhores práticas importantes”, não o conteúdo bruto de todos os resultados de busca.

Terceiro passo: Update. O Agent atualiza a todo list e marca o status de conclusão.

todo_write([
    "[x] Buscar a documentação oficial do LangGraph",
    "[x] Ler o design da arquitetura principal",
    "[ ] Extrair casos de melhores práticas",
    ...
])

Quarto passo: continuar a execução. O Agent chama writer_subagent para organizar o conteúdo e, depois, usa write_file para gerar o relatório final.

call_subagent("writer", "Organizar os resultados de pesquisa e gerar o relatório")
write_file("langgraph_best_practices.md", report_content)

O log de execução ficaria assim:

[Step 1] todo_write: criar 5 itens de tarefa
[Step 2] call_subagent(research): iniciar busca de informações
[Step 3] internet_search: buscar "LangGraph best practices"
[Step 4] read_url: ler 3 documentos oficiais
[Step 5] subagent_complete: research retorna resultado estruturado
[Step 6] todo_write: atualizar progresso, 2 itens concluídos
[Step 7] call_subagent(writer): iniciar organização do conteúdo
[Step 8] subagent_complete: writer retorna relatório em Markdown
[Step 9] write_file: gravar relatório em arquivo
[Step 10] todo_write: todas as tarefas concluídas

Durante todo o fluxo, a Context Window do orquestrador permanece limpa: apenas lista de tarefas e resumos retornados pelos subagentes, sem o ruído das etapas intermediárias.

Esse é o poder de um Deep Agent: fluxo estruturado, gestão de Context e divisão especializada.

Comparação com outros frameworks de Agent

DeepAgents não é a única opção. Há outros frameworks no mercado, como LangGraph, AutoGen, CrewAI e SmolAgents. Cada um tem foco próprio e se encaixa em cenários diferentes.

Uma tabela ajuda a ver rapidamente:

Algumas diferenças importantes:

DeepAgents vs LangGraph. DeepAgents é uma camada de alto nível sobre LangGraph, focada no padrão Deep Agent. Ele já encapsula capacidades comuns como Planning Tools, File System Backend e Sub-agent Management. Você não precisa montar tudo sozinho. LangGraph é mais baixo nível, oferece máquina de estados e orquestração de workflow, permite definir livremente cada nó e aresta, mas exige que você implemente Memory e Planning por conta própria.

Resumindo: se quiser montar rapidamente um Deep Agent, use DeepAgents; se quiser personalização de baixo nível, use LangGraph.

DeepAgents vs AutoGen. AutoGen é o framework da Microsoft, com suporte a conversas multiagente e orquestração de Pipeline. Sua característica é permitir que agentes conversem entre si, formando debates, negociações e outros padrões complexos de interação. DeepAgents fica mais perto de decomposição e execução de tarefas; AutoGen, de colaboração e comunicação entre agentes.

Resumindo: se quiser colaboração entre equipes de agentes, debate e negociação, use AutoGen; se quiser decomposição de tarefas e divisão especializada, use DeepAgents.

DeepAgents vs CrewAI. CrewAI enfatiza “role-playing”: cada agente tem uma função diferente, como pesquisador, editor ou programador, e eles colaboram para concluir a tarefa. É parecido com o padrão Sub-agent do DeepAgents, mas CrewAI enfatiza mais a persona e a interação entre papéis, enquanto DeepAgents enfatiza decomposição e isolamento de tarefas.

Resumindo: se quiser simular colaboração de equipe e papéis, use CrewAI; se quiser decomposição técnica de tarefas, use DeepAgents.

DeepAgents vs SmolAgents. SmolAgents é um framework leve da Hugging Face. Sua característica é ser code-first: o Agent escreve Python diretamente para executar tarefas, em vez de chamar ferramentas. Ele serve bem para prototipagem rápida, mas não é adequado para tarefas longas e complexas.

Resumindo: se quiser testar rapidamente um Agent simples, use SmolAgents; se quiser tarefas longas e complexas, use DeepAgents.

"A escolha do framework depende do seu cenário. DeepAgents é adequado para raciocínio complexo, LangGraph para sistemas em produção, AutoGen e CrewAI para colaboração multiagente, e SmolAgents para validar ideias rapidamente. Não existe framework universal; existe o framework adequado"

Implantação em produção e melhores práticas

Ao usar DeepAgents em produção, há alguns pontos importantes.

Estratégia de escolha do Backend

A lógica de escolha entre os três Backends é:

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

StateBackend: ambiente de teste e tarefas curtas. A vantagem é velocidade: todos os dados ficam na memória, sem atraso de IO em leitura e escrita. A desvantagem é a falta de persistência: depois que o Agent reinicia, o estado se perde. Serve para testes unitários, validações rápidas e tarefas de curta duração.

FilesystemBackend: ambiente de produção e necessidade de persistência. A vantagem é confiabilidade: os dados são gravados no sistema de arquivos e ainda podem ser lidos após reinício. A desvantagem é o custo de IO: ler e escrever arquivos é mais lento que memória. Serve para produção, tarefas longas e cenários que exigem persistência.

StoreBackend: uso corporativo e auditoria. A vantagem é controle: os dados ficam em um banco de dados na nuvem, com suporte a versionamento e logs de auditoria. A desvantagem é a complexidade: exige configurar conexão de banco de dados e gestão de permissões. Serve para aplicações corporativas, requisitos de conformidade e necessidades de auditoria.

Um exemplo de configuração:

from deepagents import create_deep_agent, FilesystemBackend

agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    backend=FilesystemBackend(
        base_path="/var/agent-state",  # Caminho de armazenamento
        max_file_size=10 * 1024 * 1024,  # Máximo de 10 MB por arquivo
        cleanup_after_days=30  # Limpar arquivos antigos após 30 dias
    )
)

Design da granularidade dos subagentes

Não divida demais.

Há quem quebre uma tarefa de pesquisa em 10 subagentes: search_google, search_bing, read_wikipedia, read_github, extract_summary, extract_quotes, format_markdown, check_citations… O resultado é que o orquestrador gasta mais tempo chamando subagentes do que executando a tarefa real.

Um desenho razoável usa de 3 a 5 subagentes principais:

• research: responsável por toda busca e extração de informações
• analysis: responsável por processamento de dados e raciocínio lógico
• writer: responsável por organização e saída de conteúdo
• reviewer: responsável por checagem de qualidade e validação, se necessário

Cada subagente deve ter fronteiras claras de responsabilidade. O subagente research não deveria organizar conteúdo; o subagente writer não deveria buscar informações. Com responsabilidades separadas, as chamadas ficam claras.

Otimização de desempenho

Dois pontos são essenciais:

Leitura de arquivos sob demanda. Não use read_file para carregar todos os resultados intermediários de uma vez. Durante a execução, o Agent lê arquivos relacionados conforme a necessidade da tarefa atual. O mecanismo de referências a arquivos do DeepAgents existe para isso: o caminho fica no Context, e o conteúdo só é carregado quando necessário.

Uso adequado de Context Summarization. Em tarefas longas, a Context Window pode acumular muito conteúdo. DeepAgents suporta resumo automático de etapas intermediárias, comprimindo logs longos de execução em descrições curtas de estado. Isso economiza espaço de Context, mas exige atenção à precisão do resumo: informações importantes não podem se perder.

agent = create_deep_agent(
    ...,
    context_management={
        "summarization_threshold": 50000,  # Acionar resumo em 50K tokens
        "preserve_last_n_steps": 5  # Preservar detalhes dos últimos 5 passos
    }
)

Tratamento de erros e verificação

Deep Agents têm fluxos longos, então a chance de erro também cresce. É preciso ter mecanismos de tratamento:

LLM-as-a-Judge. Use outro LLM para verificar a qualidade da saída do Agent. Por exemplo, reviewer_subagent pode checar se o relatório gerado por writer_subagent tem falhas lógicas ou informações ausentes.

Pontos de intervenção humana. Defina confirmações humanas em decisões críticas. Por exemplo, depois que o Agent conclui a pesquisa, ele pausa e espera o usuário confirmar se a direção está correta antes de continuar.

agent = create_deep_agent(
    ...,
    verification={
        "auto_verify": True,  # Ativar verificação automática
        "human_checkpoint": "before_output"  # Confirmação humana antes da saída
    }
)

Resumo

Vamos recapitular os quatro pilares do DeepAgents:

Planning Tools dão capacidade de planejamento ao Agent. todo_write funciona como working memory por meio da Context Window e mantém a consistência de objetivos de longo prazo.

Sub-agents criam divisão especializada e isolamento de Context. O Context do orquestrador permanece limpo, e as etapas intermediárias executadas pelos subagentes não poluem o fluxo principal.

File System resolve o limite da Context Window. Referências a arquivos substituem carregamento direto, e a leitura sob demanda economiza espaço.

System Prompts definem os limites de comportamento do Agent. Documentos de engenharia com centenas ou milhares de linhas cobrem diversos casos de borda.

Esses quatro pilares trabalham juntos para levar o Agent de “execução reativa” a “raciocínio estruturado”. O sucesso de Claude Code, Deep Research e Manus mostra que essa arquitetura funciona.

Próximos passos recomendados:

• Experimente construir seu primeiro Agent de tarefa longa com DeepAgents. O repositório oficial no GitHub tem exemplos completos: langchain-ai/deepagents.
• Leia a documentação oficial da LangChain para se aprofundar. A documentação do DeepAgents fica em docs.langchain.com/oss/python/deepagents.
• Acompanhe a série prática de desenvolvimento com IA. Em seguida virão mais análises profundas de arquitetura de Agent, incluindo design de máquina de estados com LangGraph e otimização de sistemas de Agent Memory.