Covenant Framework: como funciona a camada de governança para sistemas multi-agente de IA

O que foi lançado

Um desenvolvedor identificado no GitHub como asalsali publicou o Covenant Framework, um repositório de código aberto (edição Community) que promete resolver um problema específico de sistemas multi-agente de IA: coordenação. O projeto foi anunciado no Hacker News sob o título “Covenant, a governance framework for multi-agent AI systems” e está hospedado em github.com/asalsali/covenant-framework-community. Até o momento da publicação, o repositório tinha 4 estrelas, o que indica um projeto ainda inicial e pouco testado pela comunidade.

O framework roda dentro do Claude Code (ambiente de linha de comando da Anthropic para agentes de código) ou do OpenAI Codex CLI, sem dependências externas. A proposta central é dar estrutura, ciclo de vida e controle de qualidade para quando múltiplos agentes de IA trabalham juntos em um mesmo projeto.

Como funciona o mecanismo de governança

Antes de entrar nos detalhes técnicos, vale entender o problema que o Covenant tenta resolver. Quando você orquestra vários agentes de IA (um pesquisa código, outro escreve, outro revisa), surgem perguntas que não têm resposta óbvia: quem segue quais regras, como os agentes se comunicam entre si, quando param para revisar o próprio trabalho e como o sistema se recupera quando um agente falha ou trava. O Covenant tenta responder essas perguntas com quatro peças: um agente central de interface, um documento de regras imutável, um ciclo de vida com portões de verificação e um sistema de memória entre execuções.

O Interpreter como único ponto de contato

Você nunca fala diretamente com os agentes que fazem o trabalho pesado. Existe um agente chamado Interpreter que é o único que conversa com o usuário. Ele lê o seu pedido, verifica o estado atual do sistema (o que já foi feito, que agentes existem, que memórias estão disponíveis), propõe um plano dizendo quais agentes específicos vai acionar, e espera sua aprovação antes de agir. Só depois que você responde algo como “go”, os agentes são de fato criados (o termo usado é spawn), executam suas tarefas, escrevem um relatório de saída e são desligados.

Esse padrão de “um agente de interface, vários agentes de execução” não é exclusivo do Covenant, mas o projeto formaliza isso como regra arquitetural fixa, não como escolha de implementação.

A Constitution: regras que todo agente herda

O framework define uma Constitution com 36 seções de regras que, segundo a documentação, são imutáveis e herdadas por todo agente criado no sistema. Isso funciona como uma camada de configuração global que todo agente lê antes de começar a trabalhar, independente de qual tarefa específica ele vai executar. Não há, no material disponível, o conteúdo detalhado dessas 36 seções, então não dá para saber com precisão o que exatamente elas regulam além do que aparece descrito no ciclo de vida.

Doze tipos de agentes com papéis fixos

O Covenant define 12 tipos de agentes com funções pré-definidas: Interpreter, Analyst, Writer, Synthesist, Guardian, Shepherd, Scribe, Stress Tester, Futility Review, Goal Challenge, James e Executor. A ideia é que cada tipo tenha um escopo de atuação claro (por exemplo, um Analyst pesquisa e investiga, um Writer implementa, um Stress Tester tenta quebrar o que foi feito). Isso é diferente de frameworks onde você define agentes genéricos e atribui papéis via prompt: aqui os papéis já vêm modelados na estrutura do sistema.

O ciclo de vida do agente e os três portões

Todo agente passa por quatro fases: SPAWN (criação), GENESIS PHASE, EXECUTE e SHUTDOWN. A documentação descreve três checkpoints obrigatórios (chamados de gates) ao longo desse ciclo:

• Gate 1, na criação: o agente é obrigado a ler seu mandato (escopo da tarefa), a Constitution e aprendizados anteriores registrados na memória do sistema antes de fazer qualquer coisa.
• Gate 2, durante a execução: o agente precisa trabalhar dentro do escopo definido pelo mandato, sem invadir a área de outro agente que esteja rodando em paralelo.
• Gate 3, no desligamento: o agente é obrigado a escrever um relatório de saída (exit report), arquivar esse relatório e notificar a memória do agente pai antes de encerrar.

Vale registrar que essa tabela aparece truncada no README original do projeto, então essa é uma reconstrução razoável da lógica descrita, não uma transcrição literal.

Sistema de memória entre execuções

O componente que dá continuidade ao sistema é o memory system. Ele é composto por exit reports (o relatório que cada agente escreve ao terminar), memos estruturados, uma camada de memória semântica e ciclos de consolidação que, presumivelmente, resumem e comprimem histórico para não acumular contexto infinito. É esse mecanismo que permite ao Interpreter, na próxima conversa, saber o que já foi tentado e o que já foi aprendido, sem que o usuário precise repetir contexto.

Runtime hooks

A edição Community inclui 4 runtime hooks: agent gate (controle de quem pode ser criado e quando), token logging (registro de consumo de tokens), shutdown orchestration (coordenação do encerramento de agentes) e session checks (verificação de estado da sessão). São pontos de interceptação no fluxo de execução, o tipo de mecanismo que normalmente você implementaria manualmente num orquestrador multi-agente caseiro.

O que isso significa na prática

A forma mais rápida de experimentar, segundo a documentação do projeto, é via CLI (interface de linha de comando) descrevendo o que você quer:

pip install covenant-cli
covenant create "A research app that searches papers and writes reviews"

Isso gera um projeto completo com código de agente real, entradas e saídas tipadas, relatórios de saída e herança de memória já configurados, segundo a descrição do README.

Para instalar o framework diretamente dentro de um projeto existente com Claude Code:

# Novo projeto
git clone https://github.com/asalsali/covenant-framework-community.git my-project
cd my-project && claude

# Projeto existente (Claude Code)
curl -sL https://raw.githubusercontent.com/asalsali/covenant-framework-community/main/install.sh | bash

# Via npm
npm i covenant-framework

O fluxo de interação descrito no material é assim: você escreve um pedido em linguagem natural, o Interpreter responde com um plano dizendo quais agentes vai acionar, e você confirma com um “go” antes de qualquer agente ser de fato criado. Não há arquivo de configuração para escrever nem dashboard para montar, pelo menos na proposta do projeto.

O repositório também tem um exemplo mínimo em examples/quickstart/, descrito como demonstração de governança “em menos de 30 segundos”, útil para quem quer ver o mecanismo funcionando sem montar um projeto real primeiro.

Onde quebra

Alguns pontos que limitam onde e como esse framework se aplica hoje:

• Dependência de ferramentas específicas: o Covenant roda dentro do Claude Code ou do OpenAI Codex CLI. Se sua stack de agentes não usa nenhuma dessas duas ferramentas, o framework, na forma descrita, não se aplica diretamente (existe uma integração com CrewAI documentada separadamente, mas não detalhada no material disponível).
• Licença não é uma licença open source padrão: o projeto usa a “Covenant Public License v1.0”, uma licença customizada, não MIT, Apache ou GPL. Isso importa para quem for usar em produto comercial: vale ler os termos completos antes de assumir que é livre para qualquer uso.
• Edição Community é deliberadamente limitada: a tabela de comparação no próprio README mostra que a edição Network (paga, presumivelmente) tem 22 comandos avançados e 7 hooks avançados a mais que a Community. O material não detalha o que são esses comandos e hooks adicionais nem o preço da edição Network.
• Benchmark sem metodologia auditável no material disponível: o README cita um resultado de 67,4% de sucesso sem retentativa no Terminal-Bench 2.0 (89 tarefas), contra 42% de uma baseline “ad-hoc”. Não há, na página consultada, link para o benchmark completo, script de reprodução ou detalhes de como a baseline foi definida. Isso não invalida o número, mas também não permite verificá-lo de forma independente a partir do material fornecido.
• Projeto muito recente e pouco adotado: com 4 estrelas no GitHub no momento da publicação, ainda não há evidência de uso em produção fora dos exemplos citados pelo próprio autor (como o “covenant-hedge-fund”, descrito como projeto de exemplo).

O que não dá para afirmar ainda

Não testamos o framework rodando um caso real com múltiplos agentes em paralelo, então não dá para confirmar se os “gates” de fato previnem conflito de escopo na prática ou se isso depende de o modelo por trás do agente (Claude ou GPT via Codex) seguir instruções de forma consistente. Também não é possível afirmar, a partir do material disponível, como o sistema se comporta com um número grande de agentes simultâneos, nem qual é a latência ou o custo em tokens adicional que a camada de governança introduz sobre o custo normal de rodar os agentes. O material menciona “token logging” como um dos runtime hooks, o que sugere que o próprio projeto reconhece esse como um custo a ser monitorado, mas não fornece números. Por fim, não há no material informação suficiente sobre quem mantém o projeto além do autor original, nem sobre plano de suporte a longo prazo.

Como testar isso você mesmo

O caminho mais direto para experimentar sem comprometer um projeto real é instalar o covenant-cli em um diretório novo e vazio:

pip install covenant-cli
covenant create "Um app simples que le um arquivo CSV e gera um resumo"

Depois, inspecione a estrutura de pastas gerada (procure pelos exit reports e pelos arquivos de mandato de cada agente) antes de rodar qualquer tarefa mais séria. Se você já usa Claude Code no dia a dia, vale também clonar o exemplo de examples/quickstart/ do repositório e rodar dentro dele, comparando o comportamento com e sem o framework ativo, para ter uma base própria de comparação em vez de depender só do número de benchmark divulgado.