🧠 Avançado I — Arquitetura e Extensão

LangGraph é a biblioteca que modela o agente como um grafo de nodes que lêem/escrevem um state compartilhado. O DeerFlow usa LangGraph como backbone do lead_agent.

Sem entender nodes, edges e state reducers, você não consegue depurar por que o agente tomou uma decisão nem estender o harness sem quebrar invariantes.

StateGraph; conditional edges; checkpoints; reducers; streaming via astream_events; persistência de state entre turnos.

O lead_agent é o grafo central que recebe a mensagem do usuário, decide planejar ou agir, dispara skills ou custom agents e costura os resultados na resposta final.

Toda interação passa por ele. Se você não sabe onde entra o prompt, onde saem as tools e onde aparece o output, não há como customizar de forma segura.

Plan → act → observe → respond; integração com skills via descoberta; dispatch para custom agents; encerramento quando o plano está completo.

O harness é o motor reutilizável (grafo, memória, tools, sandbox). A app é o que roda em cima: API gateway, frontend, canais IM, integrações específicas.

Saber o que é harness e o que é app define onde uma feature nova deve morar — e evita forks desnecessários do core quando uma extensão resolveria.

HARNESS_APP_SPLIT.md; boundary de dependências; embedded client; app gateway; reuso do mesmo harness em múltiplas apps.

O conjunto de políticas que decide o que entra e sai do prompt a cada turno: histórico, memórias, resultados de tools, instruções de sistema.

Estender sem conhecer context engineering enche a janela e degrada o agente silenciosamente — o bug aparece como "o modelo ficou burro".

Compactação automática; summarization de trechos antigos; priorização por relevância; contrato de retorno curto das sub-tasks.

Camadas de validação que checam entradas, saídas e chamadas de tool antes/depois de executar — bloqueiam prompts maliciosos e operações perigosas.

Quem deploya sem guardrails ou mexe neles às cegas vira manchete. A git log recente do DeerFlow mostra vários fixes exatamente aqui.

Input/output validators; allow/deny lists de tools; policy engine; integração com middleware; failure modes e fallback.

Lab prático: ligar LangSmith, rodar uma query complexa e inspecionar o trace completo para entender a sequência real de nodes e tools.

Ver o trace de verdade derruba mitos: o que parecia lento muitas vezes é uma tool externa e não o modelo — e o que parecia mágica vira mecânica.

LangSmith API key; run tree; tokens por node; latência por edge; identificar hot paths; exportar trace como evidência.

Camada que roda antes e depois de cada chamada do agente, permitindo logar, validar, transformar input/output e interromper execução quando necessário.

Middleware é onde moram telemetria, auditoria, rate limits e políticas. Tudo que você quer observar ou controlar passa por aqui.

Pre/post hooks; ordem de execução; short-circuit; contexto compartilhado entre middlewares; integração com guardrails.

Quando o lead_agent decide delegar para um custom agent, ele coloca o agent_name no state e o middleware roteia a execução para o agente correto.

Todo custom agent novo depende desse protocolo. Sem entender como o despacho funciona, custom agents "somem" sem erro explícito.

Registry de agentes; resolução de agent_name; troca de system prompt; retorno de controle; fallback para lead quando não há match.

Modelo propõe tool call → middleware valida → tool executa → resultado volta para o state → modelo observa e decide o próximo passo.

Cada etapa pode falhar de um jeito diferente. Saber onde cada erro aparece é a diferença entre debugar em minutos ou em horas.

Schema validation; argumentos inválidos; async wrapping; timeouts; resultado estruturado vs. raw; retrospecção no próximo turno.

Políticas para lidar com tool call que falha: retornar erro estruturado para o modelo decidir, tentar de novo, usar fallback ou abortar a task.

Erro mal tratado faz o agente repetir a mesma chamada quebrada ou entrar em loop. Recuperação correta mantém o fluxo resiliente.

Exception wrapping; mensagens de erro legíveis para o LLM; retry policies; circuit breaker; logging estruturado para postmortem.

Escrever um middleware simples que registra toda tool call, argumentos, resultado e tempo de execução — e plugá-lo no harness sem mexer no core.

É o "hello world" de quem vai estender o DeerFlow. Quem não consegue fazer um logger não vai conseguir fazer um guardrail.

Registro do middleware; hooks on_tool_start/end; formato JSON-line; integração com LangSmith; overhead aceitável.

Uma skill é um diretório com metadados, prompt de sistema, tools opcionais e instruções de uso. Vamos abrir deep-research linha por linha.

Sem conhecer o contrato real de uma skill, todo esforço de criar uma nova vira chute. Ler skills prontas é o caminho mais curto.

skill.yaml; description/trigger; system prompt; tool bindings; arquivos auxiliares; convenções do catálogo público.

Uma skill que ajuda você a criar outras skills: faz perguntas, gera o scaffold, sugere descrição e testa o trigger — é um copiloto do autor.

Usar a meta-skill cai direto em boas práticas que levaria semanas para descobrir sozinho. É o atalho oficial.

Fluxo guiado; scaffold padrão; geração de description; avaliação de trigger; integração com skill registry.

A arte de escrever a description da skill para que o lead_agent a acione só quando deve — nem menos, nem mais.

Descrição ruim causa os dois piores bugs: skill que nunca dispara e skill que dispara em tudo. Ambos desgastam a confiança do usuário.

Use when; do not use when; exemplos positivos/negativos; disambiguação com skills vizinhas; avaliação por casos de teste.

Conjunto de casos de teste que validam trigger, comportamento em sucesso e comportamento em falhas previsíveis da skill.

Sem testes, toda alteração na description é roleta-russa com o comportamento do agente em produção.

Evals de trigger; golden tests de output; comparação entre versões; CI rodando evals; métricas de acurácia.

Construir do zero uma skill que faz pesquisa cruzando dados do IBGE e do Portal da Transparência, com tools próprias e prompt afiado.

Um lab real força você a pensar em auth, rate limit, formato de retorno e citação de fontes — as partes que "no papel" parecem triviais.

API pública do IBGE; API do Portal da Transparência; caching local; citações inline; entregável em markdown.

Sub-agent é chamado dentro de uma task para isolar contexto. Custom agent é uma persona roteada pelo lead_agent com SOUL próprio e ciclo de vida longo.

Misturar os dois é o erro mais comum de quem chega ao DeerFlow vindo de outros frameworks. O design inteiro depende da distinção.

Task-local vs. conversation-level; contexto isolado vs. contexto herdado; retorno resumido vs. diálogo contínuo; uso típico de cada um.

SOUL é o conjunto de arquivos que define identidade, tom, escopo, tools autorizadas e políticas de um custom agent. É a config-pai do agente.

É onde você desenha um agente que se comporta como especialista em algo específico sem ficar brigando com o prompt do lead.

Arquivos do SOUL; agent_name; system prompt próprio; toolset restrito; memórias/rotinas dedicadas; versionamento.

RFC oficial que documenta motivação, design e processo para criar um custom agent novo — é o "manual do autor" reconhecido upstream.

Ler o RFC encurta meses de discussão. Ele já responde "por que isso e não aquilo" para a maioria das decisões que você vai tomar.

Motivação; requisitos não-funcionais; alternativas rejeitadas; open questions; impacto em memória e guardrails.

Um framework de decisão: se é uma capacidade pontual com gatilho claro, skill; se é uma persona duradoura com escopo inteiro, custom agent.

Escolher errado aumenta o custo de manutenção e confunde usuários. Essa é a decisão de design mais frequente no dia a dia.

Escopo pontual vs. amplo; reuso dentro de outras skills; posse de memória; custo de SOUL; heurística de "se em dúvida, skill primeiro".

Criar um custom agent security-auditor com SOUL próprio, plugar num canal Slack dedicado e fazer ele auditar snippets e PRs.

É o exercício que junta SOUL, despacho, tools e canal IM em um único fluxo funcional — exatamente o caso de uso empresarial real.

SOUL para auditoria; toolset restrito a leitura; Slack bot; roteamento por canal; memórias de achados recorrentes.

RFC que introduziu as tools grep e glob no DeerFlow, definindo schema, semântica, paginação e integração com o sandbox.

É o melhor exemplo escrito do contrato esperado de uma tool nativa — serve de modelo quando você for criar a sua.

Schema pydantic; paginação e limite; formato de retorno; integração com sandbox; tratamento de erros previsíveis.

MCP (Model Context Protocol) é o padrão para expor tools externas via stdio ou HTTP/SSE. O DeerFlow consome MCP servers como fonte adicional de tools.

MCP é como você integra sistemas legados sem mexer no core do harness — escreve um server pequeno e pronto.

Transport stdio vs. HTTP/SSE; tool registration; schema; configuração no config.yaml; namespacing de tools MCP.

Quando o MCP server exige auth, o DeerFlow negocia tokens via client_credentials (service-to-service) ou refresh_token (usuário).

Todo MCP server sério em empresa precisa disso. Quem ignora OAuth vira um projeto de POC que nunca sobe.

client_credentials; refresh_token; token caching; scopes; renovação automática; falha graceful quando o token expira.

Expor uma API interna existente como MCP server e fazer uma skill do DeerFlow consultá-la — de ponta a ponta, incluindo auth e erros.

É o lab que valida se você entendeu MCP, OAuth, tool schema e integração com skill. Tudo junto, como no mundo real.

MCP SDK; tool schemas auto-gerados; OAuth2 do lado do server; cliente configurado no config.yaml; verificação end-to-end.