ADR-0065 — Postura sobre agent frameworks externos (CrewAI, AutoGen, LangGraph): roubar padrões, não dependências

Status: Aprovado Data: 2026-06-29 Decisor: Marcelo Lermen Origem: Sessão de board 2026-06-29 — análise estratégica provocada pela pergunta "tem algo a aprender/trazer de CrewAI, AutoGen, LangGraph para a empresa autônoma?". Decisão tomada após mapear o runtime atual da Tynna contra o estado real desses frameworks (jun/2026). Generaliza o precedente da análise Ruflo numa postura canônica para não re-litigar a cada framework que viraliza. Relacionado: blueprint empresa autônoma (docs/business/architecture/2026-06-01-blueprint-empresa-autonoma.md, §1 integrar>construir, §2 as 4 camadas) · ADR-0063 (funil único de invocação) · ADR-0055 (quality bar — exemplo de "integrar" Promptfoo sem adotar como engine) · ADR-0027 (Paperclip source-of-truth) · análise precedente docs/business/architecture/2026-06-27-analise-ruflo-vs-tynna.md ("roubar os padrões, não a dependência") · ADR-0047 (discovery antes de executar) · CLAUDE.md §0 (norte: autonomia sem direcionamento certeiro = retrabalho)

---

Contexto

A popularidade cíclica de frameworks de orquestração de agentes (CrewAI, AutoGen/Microsoft Agent Framework, LangGraph e similares) gera pressão recorrente para avaliar adoção. Sem uma postura canônica, cada framework novo que viraliza abre o mesmo debate — custo de atenção alto, decisão repetida. O board precisava de um enquadramento definitivo.

A análise 2026-06-27-analise-ruflo-vs-tynna.md já estabeleceu o precedente com o Ruflo (ex-Claude-Flow): "roubar padrões, não a dependência". Este ADR generaliza essa postura para o trio mais citado (CrewAI, AutoGen, LangGraph) e a transforma em regra de governança aplicável a qualquer framework de agente que surja.

O pano de fundo concreto: AutoGen entrou em modo manutenção e foi fundido pela Microsoft com o Semantic Kernel no Microsoft Agent Framework (GA 1.0, abril/2026); a comunidade forkou em AG2. LangGraph e CrewAI reescrevem APIs com frequência. O mercado é instável — exatamente o oposto do que uma empresa que opera 24/7 sem o controller precisa.

Decisão

Não adotar CrewAI, AutoGen ou LangGraph (nem similares) como engine de orquestração do core da Tynna. Roubar padrões, não dependências.

Adoção como biblioteca isolada de um único agente é permitida apenas sob exceção controlada (ver seção abaixo). A fundamentação é em seis pontos:

1. Já temos o fosso que eles não têm. O runtime da Tynna (scripts/events/consume.ts + packages/agent-runtime/{autonomous-dispatch,circuit-breaker,policy}.ts) já faz routing por registry, autorização L1–L4, billing reader com custo real via cost_ledger e circuit-breaker fail-closed. Nenhum dos três frameworks oferece esses guardrails de governança — billing cap por agente, breaker, autonomia faseada — que são justamente o diferencial de uma empresa autônoma. O charter standard (docs/business/agents/_charter-standard.md) é um superconjunto do role/goal/backstory do CrewAI: inclui autonomy_level, bounded_context, events_publishes/consumes, KPIs e ACAP.

2. O que nos falta em durabilidade já tem destino — Trigger.dev, não um agent framework. Achado técnico relevante (fonte: análise Diagrid): o "checkpointing" do LangGraph, CrewAI e Google ADK não é durable execution — salvam snapshot mas a recuperação é manual (resume() explícito), são single-process/monolíticos, sem dedup distribuído nem exactly-once. Durable execution real é Temporal/Trigger.dev/Dapr/DBOS. Hoje operamos pgmq + GitHub Actions como interino (claim idempotente via on-conflict-do-nothing + retry por visibility timeout); a aposta durável é Trigger.dev self-host (blueprint §2). Trocar por checkpointing de framework seria downgrade.

3. Churn é risco estrutural para empresa 24/7. AutoGen foi fundido e gerou fork de comunidade; LangGraph e CrewAI reescrevem API a cada ~12 meses. Acoplar o core a tecnologia com esse perfil de estabilidade contraria o norte de "empresa que opera sem o controller". O custo de migração forçada num sistema event-driven de produção é alto demais.

4. A própria Anthropic recomenda evitar frameworks pesados. O guia "Building Effective Agents" (Anthropic) orienta preferir padrões simples e composáveis: prompt chaining, routing, parallelization, orchestrator-worker, evaluator-optimizer. A Tynna já implementa todos: Tynna Lead + especialistas = orchestrator-worker; EDDOps + verificação adversarial = evaluator-optimizer; funil único (ADR-0063) = routing. Não há lacuna que justifique a camada extra.

5. Mismatch de stack. CrewAI, AutoGen/MS AF e LangGraph são Python (ou .NET/Python). O runtime da Tynna é TypeScript (tsx, packages/ TS). Adotar qualquer um injeta runtime Python no ecossistema TS. Se um dia um framework de agente TS-native fizesse sentido, o candidato natural seria Mastra (TS-native, já cogitado como executor no agent-build.yml) — não os três mencionados.

6. Direcionamento certeiro — o ponto decisivo. Os gargalos reais admitidos no blueprint: data/events vazio, quality-score stubbed (0.7 hardcoded, não-bloqueante), loop financeiro sem circulação (spentMonthlyCents=0), drift charter↔runtime. Nenhum desses é resolvido por CrewAI, AutoGen ou LangGraph — são problemas de instrumentação e enforcement do nosso próprio modelo. Adotar engine novo agora seria o anti-padrão EuGestor (construir/adotar sem direcionamento = retrabalho; CLAUDE.md §0). A alavanca está em fechar o Caminho B (ADR-0063 Fatia 2), ligar o quality-score real e fazer o loop financeiro circular.

O que roubamos

Padrões absorvidos sem dependência de biblioteca:

Exceção controlada

LangGraph (ou framework equivalente) como biblioteca isolada de um único agente é permitido se e somente se:

(a) houver um agente com fluxo de decisão cíclico genuinamente complexo (evaluate→retry com muitos branches) difícil de expressar no padrão consume.ts atual; (b) o uso for isolado atrás de src/connectors/ (regra universal: toda chamada externa via connector — CLAUDE.md global §5); (c) a adoção for precedida de discovery formal conforme ADR-0047, com evidência de que o framework resolve o problema melhor que evoluir o runtime próprio.

Hoje, nenhum caso satisfaz a condição (a). A exceção não abre porta imediata — serve para não vetar o futuro de forma absoluta caso o problema real apareça.

Alternativas consideradas

Avaliações posteriores (mantêm a postura)

Registro de frameworks/projetos avaliados depois deste ADR, para fechar o re-litígio:

Consequências

Positivas

• Não abre vetor de supply-chain. Frameworks de agente com churn alto e mantenedor único (padrão do mercado atual) são vetores de risco que a política do CISO deveria barrar de qualquer forma.
• Elimina re-litígio. A próxima vez que um framework viralizar, a resposta é este ADR — não uma nova análise do zero.
• Mantém o fosso intacto. A governança L1–L4 + billing real + charter ACAP é o diferencial competitivo; terceirizar a orquestração para um framework genérico dilui esse fosso sem contrapartida.
• Clarifica a agenda real. O foco permanece nos gargalos reais: fechar o Caminho B (ADR-0063), ligar quality-score real, fazer o loop financeiro circular.

Negativas / riscos (com mitigação)

• Risco de reinventar a roda se surgir caso de uso genuíno. Mitigação: a exceção controlada existe para esse caso; a condição de ativação é clara (discovery formal + problema real + connector isolado).
• Pode parecer "NIH syndrome" externamente. Mitigação: a decisão não é "nunca integrar nada"; é "não substituir o core de governança por commodity instável". A Tynna integra commodity onde faz sentido (ADR-0055 integrou Promptfoo para eval; Pinterest API para publicação). O diferencial é a governança, não o encanamento.

Enforcement — gate check-denylist.mjs (known limitations)

O gate bloqueante que operacionaliza esta postura vive em scripts/security/check-denylist.mjs e é rodado no workflow .github/workflows/supply-chain.yml. A denylist canônica é docs/security/supply-chain-denylist.txt (board/CISO edita lá). Depois da rodada de hardening TYN-2216:

• Camada (a) — package.json. Aliases npm: (ex. "shim": "npm:agentdb@1") NÃO batem no match dessa camada porque o nome da chave (shim) não bate na denylist. É limitação conhecida.
• Camada (b) — pnpm-lock.yaml. Continua pegando o pacote canônico (agentdb@...) no lockfile, porque o pnpm materializa a entrada real. Fica como defesa efetiva do vetor alias.
• CODEOWNERS. .github/CODEOWNERS exige review do board para os 4 artefatos que compõem o gate (lista, workflow, script, o próprio CODEOWNERS), evitando o vetor "no mesmo PR remove a linha da denylist e adiciona o pacote banido".

Mudanças na denylist ou no gate vão ao board (autoridade L3, ADR-0029 §5).

Rollback plan

Esta postura é reversível por design: se um gargalo concreto de orquestração surgir e um discovery formal (ADR-0047) demonstrar que um framework resolve melhor que evoluir o runtime próprio, reabre-se a decisão via novo ADR. Nenhum dado de produto, schema ou infra é tocado por esta decisão — é postura de governança, não mudança estrutural.