ACR — Agent Composition Records

Registro de perfil de interação para agentes de IA — registre interações, construa um perfil comportamental, consulte-o através de lentes comportamentais. 21 ferramentas, zero configuração.

GitHub

Experimente este MCPPatrocinado

Documentação

ACR — Registros de Composição de Agentes

Um registro comportamental para agentes de IA. O ACR captura cada chamada de ferramenta externa que seu agente faz, compila esses sinais em um perfil de interação e mostra onde o tempo foi gasto — começando com um cartão de resumo ao final de cada sessão.

Comece agora (60 segundos, Claude Code)

npm i -g @tethral/acr-hook && acr-hook init

Essa é toda a configuração. O hook cria uma identidade para seu agente (sem conta, sem chave de API para gerenciar), conecta-se aos hooks de ferramentas do Claude Code e captura automaticamente cada chamada de ferramenta. Quando sua próxima sessão terminar, um cartão será exibido no seu terminal:

── ACR session card ──
  142 tool calls | 4.1% of active time waiting
  Top sinks: platform:bash 38s · mcp:github 12s
  Full report: https://dashboard.acr.nfkey.ai/agents/…

Desinstale a qualquer momento com acr-hook remove (restaura o backup das suas configurações).

O que é o ACR

O ACR é um registro de perfis de interação. Agentes registram o que fazem (chamadas de ferramentas, requisições de API, interações MCP); esses sinais são compilados em um perfil comportamental que você consulta por meio de lentes — cada lente é uma forma diferente de ler os mesmos recibos subjacentes.

A lente de atrito é a primeira disponibilizada: detalhamento de latência e falhas por destino, gargalos de tempo, tendência em relação ao seu próprio histórico. Existem mais lentes para cobertura, preferência revelada (composição declarada vs. realmente usada), falhas, tendências e estabilidade.

O ACR não é um produto de segurança. Ele não avalia habilidades, testa comprometimento ou bloqueia nada. Ele registra eventos e propaga notificações: se a rede observar sinais de anomalia em um componente da composição do seu agente, seu agente recebe uma notificação. Você decide se isso importa.

O que funciona hoje vs. o que cresce com a rede

O ACR é honesto sobre sua própria maturidade. Cada lente informa em qual dos três estados está: dados reais, dados insuficientes (com a ação que muda isso) ou degradado (uma consulta falhou — exibida como indisponível, nunca como um zero saudável).

Funciona no primeiro dia, frota de um:

Captura automática de cada chamada de ferramenta (tempo, status, destino) via hook
A lente de atrito nos seus próprios dados: gargalos de tempo, latência/falhas por destino, cartões de sessão
Tendência em relação ao seu próprio histórico (esta semana vs. semana passada)
Cobertura: quais sinais você está preenchendo e quais lentes isso desbloqueia

Ativa-se conforme a rede cresce (recursos populacionais são limitados a um mínimo de 5 agentes persistentes por destino — abaixo disso, as lentes dizem "você é a referência" em vez de inventar uma comparação):

Referências populacionais ("42% mais lento que a rede em api:openai.com")
Status da rede: saúde do sistema em toda a frota, do pior para o melhor
Notificações de sinais de anomalia: ≥3 agentes distintos relatando anomalias em ≥20 interações de um componente que você declara → você é notificado

O que o hook não consegue ver (e as lentes informam isso em vez de mostrar zeros):

Falhas profundas — o hook observa apenas erros superficiais; falhas de rede/timeout/autenticação que nunca chegam ao limite do resultado da ferramenta não aparecem. 0 failures significa 0 visible failures.
Contagens de tentativas, espera na fila, estrutura de cadeia, uso de tokens — apenas agentes que chamam log_interaction com esses campos os preenchem. Perfis somente com hook exibem essas seções como n/d, não como zeros limpos.

Adicione o servidor MCP (opcional, para consultar lentes de dentro do seu agente)

O hook captura; o servidor MCP permite que seu agente leia seu próprio perfil e registre sinais mais ricos. Um comando no Claude Code:

claude mcp add acr -s user -- npx -y @tethral/acr-mcp@latest

Ou para qualquer cliente MCP (Cursor, Continue, Claude Desktop, etc.):

{
  "mcpServers": {
    "acr": {
      "command": "npx",
      "args": ["-y", "@tethral/acr-mcp@latest"]
    }
  }
}

O hook e o MCP compartilham o mesmo arquivo de identidade — qualquer um inicializa o outro. Não sabe por onde começar? Chame orient_me.

Ferramentas MCP principais

Ferramenta	O que faz
`orient_me`	Onde estou, o que devo fazer a seguir — roteamento ciente do estado
`log_interaction`	Registra uma interação com campos ricos (retry_count, chain_id, tokens_used…)
`get_friction_report`	A lente de atrito: para onde vão tempo e tokens
`summarize_my_agent`	Resumo de fim de sessão
`get_notifications`	Notificações não lidas de sinais de anomalia para sua composição
`get_my_agent`	Identidade, link do painel, estado de registro

Essas sete são toda a superfície padrão — deliberadamente pequena, porque cada esquema de ferramenta custa contexto na janela do agente host. O conjunto completo de 29 ferramentas (lentes secundárias como get_coverage/get_trend/get_revealed_preference/get_stable_corridors, gerenciamento de composição, registro de habilidades, monitoramentos, visualizações de rede) é habilitado com uma variável de ambiente na sua configuração MCP:

{ "command": "npx", "args": ["-y", "@tethral/acr-mcp@latest"], "env": { "ACR_ADVANCED": "1" } }

orient_me e get_my_agent informam ao modelo que o conjunto avançado existe, para que nada fique oculto — apenas não seja pago por padrão.

Adicione a qualquer agente (SDK)

npm install @tethral/acr-sdk    # TypeScript/Node.js
pip install tethral-acr          # Python

import { ACRClient } from '@tethral/acr-sdk';

const acr = new ACRClient();

// Register your agent's composition
const reg = await acr.register({
  public_key: 'your-agent-key-here-min-32-chars',
  provider_class: 'anthropic',
  composition: { skill_hashes: ['hash1', 'hash2'] },
});

// Log an interaction (the foundation — every lens reads these)
await acr.logInteraction({
  target_system_id: 'mcp:github',
  category: 'tool_call',
  status: 'success',
  duration_ms: 340,
});

// Query the friction lens
const friction = await acr.getFrictionReport(reg.agent_id, { scope: 'day' });

// Check for anomaly signal notifications
const notifs = await acr.getNotifications(reg.agent_id);

Notificações de sinais de anomalia

Um sinal de anomalia é um padrão comportamental observado em múltiplos agentes não relacionados — não é um alerta de segurança. Quando você registra (ou atualiza) sua composição, o ACR assina você aos componentes que declara. Se a rede observar posteriormente sinais elevados de anomalia em um deles — pelo menos 3 agentes distintos relatando em pelo menos 20 interações — uma notificação é entregue ao seu agente:

[HIGH] Component in your composition reported anomalies
   3 agents reported anomalies across 41 interactions.
   Anomaly rate: 34.1%. Review with your operator before continuing use.

Esse caminho é exercitado de ponta a ponta no CI (veja scripts/db-contract-test.mjs): relatórios de anomalia semeados em uma habilidade inscrita devem produzir uma notificação, ou o build falha. O ACR não rastreia o humano por trás de um agente, então as notificações chegam ao agente, não ao proprietário.

O registro de habilidades

O ACR observa habilidades que já existem em registros públicos (npm, GitHub) e rastreia sinais comportamentais vinculados a elas: contagens de adoção, sinais de anomalia, histórico de versões. Não é um catálogo do qual você instala e não é uma verificação de segurança — ele registra o que a rede observou. A busca classifica primeiro habilidades com sinais; entradas de catálogo sem identidade utilizável são rejeitadas no momento da coleta.

Arquitetura

Agents (Claude, OpenClaw, custom)
  |
  +--> Capture hook (@tethral/acr-hook — primary capture path)
  |      PreToolUse/PostToolUse receipts, SessionEnd card
  |
  +--> MCP Server (@tethral/acr-mcp) or SDK (@tethral/acr-sdk / tethral-acr)
  |      Lens queries, log_interaction, notifications
  |
  +--> Resolver API (Cloudflare Workers, edge-cached)
  |      Lookups, composition checks, notification feed
  |
  +--> Ingestion API (Vercel serverless)
  |      Registration, interaction receipts, lens queries, notifications
  |
  +--> CockroachDB (distributed SQL)
  |      Interaction profiles, agent registry, skill observation data
  |
  +--> Scheduled jobs (GitHub Actions -> /api/cron/*)
         system-health aggregation + chain analysis (15 min)
         skill signal computation + watch evaluation + pattern detection (30 min)
         friction baselines + data archival + agent expiration (daily)
         Every run writes a heartbeat; /health reports pipeline liveness
         separately from network activity.

Coleta de dados

O ACR coleta apenas metadados de interação: nomes de sistemas de destino, tempo, status, contexto de cadeia e classe do provedor. Nenhum conteúdo de requisição/resposta, chaves de API, prompts ou PII. Seu perfil de interação é visível apenas para você; referências populacionais usam estatísticas agregadas sobre agentes persistentes.

O que coletamos: nomes de sistemas de destino (mcp:github, api:stripe.com), tempo de interação (duração, carimbos de data/hora, espera na fila, contagem de tentativas), status da interação, classe do provedor do agente, hashes de composição (SHA-256 do conteúdo de SKILL.md), contexto de cadeia, flags de anomalia relatadas pelo agente (apenas categoria).

O que NÃO coletamos: cargas úteis de requisição/resposta, credenciais, prompts ou conclusões, PII, conteúdos de arquivos ou a identidade do humano por trás do agente.

Retenção (aplicada pelos jobs agendados data-archival e agent-expiration): recibos de interação por 90 dias, depois arquivados em resumos diários; notificações por 90 dias; registros de agentes expiram suavemente após 90 dias de inatividade; dados de observação de habilidades retidos enquanto a habilidade for observada.

Compartilhamento com terceiros: nenhum. Contato: security@tethral.com · Termos completos

Harnesses de teste

node scripts/test-agent-lifecycle.mjs   # full agent lifecycle against the live API
node scripts/e2e-smoke.mjs              # do -> read-back loop through the default lens (runs in CI on schedule)
node scripts/db-contract-test.mjs       # every migration, cron, and lens against a real CockroachDB (runs in PR CI)

O harness db-contract existe porque testes unitários simulam o banco de dados enquanto a produção roda CockroachDB — diferenças de dialeto quebraram a mesma consulta de lente três vezes separadas antes de ser adicionado. Cada rota de lente deve retornar 200, não degradada, e contagens que correspondam aos dados semeados; a promessa de notificação é verificada de ponta a ponta.

Desenvolvimento

pnpm install                    # Install dependencies
pnpm build                      # Build all packages
pnpm test:unit                  # Run unit tests
node scripts/run-migration.mjs up      # Run DB migrations

Regra de lançamento: alterar packages/mcp-server, packages/acr-hook ou um SDK exige um aumento de versão (o CI do PR aplica isso), e merges para master publicam automaticamente qualquer pacote com versão aumentada. Uma correção mesclada que nunca chega ao npm é uma correção que nunca aconteceu.

Opcional: use o ACR enquanto trabalha neste repositório. Copie .mcp.json.example para .mcp.json e qualquer cliente com suporte a MCP que abrir este diretório carregará o @tethral/acr-mcp publicado. Opt-in por design: .mcp.json está no gitignore para que contribuidores nunca sejam inscritos implicitamente. Para testar alterações locais no MCP, aponte command para node e args para ./packages/mcp-server/dist/cli/stdio.js após pnpm build.

Licença

MIT