ACR — Agent Composition Records

Registro de perfiles de interacción para agentes de IA: registra interacciones, construye un perfil conductual y consúltalo a través de lentes conductuales. 21 herramientas, sin configuración.

GitHub

Prueba este MCPPatrocinado

Documentación

ACR — Agent Composition Records

Un registro de comportamiento para agentes de IA. ACR captura cada llamada a herramienta externa que hace tu agente, compila esas señales en un perfil de interacción y te muestra dónde se fue el tiempo, comenzando con una tarjeta de resumen al final de cada sesión.

Comenzar (60 segundos, Claude Code)

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

Eso es toda la configuración. El hook crea una identidad para tu agente (sin cuenta, sin clave API que gestionar), se integra en los hooks de herramientas de Claude Code y captura cada llamada a herramienta automáticamente. Cuando tu próxima sesión termine, se imprimirá una tarjeta en tu 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/…

Desinstala en cualquier momento con acr-hook remove (restaura tu copia de seguridad de configuración).

Qué es ACR

ACR es un registro de perfiles de interacción. Los agentes registran lo que hacen (llamadas a herramientas, solicitudes API, interacciones MCP); esas señales se compilan en un perfil de comportamiento que consultas a través de lentes — cada lente es una forma diferente de leer los mismos recibos subyacentes.

La lente de fricción es la primera que se incluye: desgloses de latencia y fallos por objetivo, sumideros de tiempo, tendencia frente a tu propio historial. Existen más lentes para cobertura, preferencia revelada (composición declarada vs. realmente utilizada), fallos, tendencias y estabilidad.

ACR no es un producto de seguridad. No evalúa habilidades, no prueba compromisos ni bloquea nada. Registra eventos y propaga notificaciones: si la red observa señales de anomalía en un componente de la composición de tu agente, tu agente recibe una notificación. Tú decides si es importante.

Qué funciona hoy vs. qué crece con la red

ACR es honesto sobre su propia madurez. Cada lente te indica en cuál de tres estados se encuentra: datos reales, datos insuficientes (con la acción que lo cambia) o degradado (una consulta falló — se muestra como no disponible, nunca como un cero saludable).

Funciona desde el primer día, flota de uno:

Captura automática de cada llamada a herramienta (tiempo, estado, objetivo) mediante el hook
La lente de fricción sobre tus propios datos: sumideros de tiempo, latencia/fallos por objetivo, tarjetas de sesión
Tendencia frente a tu propio historial (esta semana vs. la anterior)
Cobertura: qué señales estás completando y qué lentes desbloquea

Se ilumina a medida que la red crece (las funciones de población están limitadas a un mínimo de 5 agentes persistentes por objetivo — por debajo de eso, las lentes dicen "tú eres la línea base" en lugar de inventar una comparación):

Líneas base de población ("42% más lento que la red en api:openai.com")
Estado de la red: salud del sistema en toda la flota, de peor a mejor
Notificaciones de señales de anomalía: ≥3 agentes distintos que reportan anomalías en ≥20 interacciones de un componente que declares → recibes una notificación

Lo que el hook no puede ver (y las lentes lo dicen en lugar de mostrar ceros):

Fallos profundos — el hook solo observa errores superficiales; los fallos de red/timeout/auth que nunca llegan al límite del resultado de la herramienta no aparecen. 0 failures significa 0 visible failures.
Conteos de reintentos, espera en cola, estructura de cadena, uso de tokens — solo los agentes que llaman a log_interaction con esos campos los completan. Los perfiles solo con hook muestran esas secciones como n/a, no como ceros limpios.

Añadir el servidor MCP (opcional, para consultar lentes desde dentro de tu agente)

El hook captura; el servidor MCP permite que tu agente lea su propio perfil y registre señales más ricas. Un comando en Claude Code:

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

O para cualquier cliente MCP (Cursor, Continue, Claude Desktop, etc.):

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

El hook y el MCP comparten el mismo archivo de identidad — cualquiera de los dos arranca al otro. ¿No sabes por dónde empezar? Llama a orient_me.

Herramientas MCP principales

Herramienta	Qué hace
`orient_me`	Dónde estoy, qué debería hacer después — enrutamiento consciente del estado
`log_interaction`	Registra una interacción con campos enriquecidos (retry_count, chain_id, tokens_used…)
`get_friction_report`	La lente de fricción: a dónde van el tiempo y los tokens
`summarize_my_agent`	Resumen de fin de sesión
`get_notifications`	Notificaciones de señales de anomalía no leídas para tu composición
`get_my_agent`	Identidad, enlace al panel, estado de registro

Estas siete son toda la superficie predeterminada — deliberadamente pequeña, porque cada esquema de herramienta cuesta contexto en la ventana del agente anfitrión. El conjunto completo de 29 herramientas (lentes secundarias como get_coverage/get_trend/get_revealed_preference/get_stable_corridors, gestión de composición, el registro de habilidades, vigilancias, vistas de red) se habilita con una variable de entorno en tu configuración MCP:

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

orient_me y get_my_agent le indican al modelo que el conjunto avanzado existe, así que nada está oculto — simplemente no se paga por defecto.

Añadir a cualquier 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);

Notificaciones de señales de anomalía

Una señal de anomalía es un patrón de comportamiento observado en múltiples agentes no relacionados — no es una alerta de seguridad. Cuando te registras (o actualizas tu composición), ACR te suscribe a los componentes que declaras. Si la red luego observa señales de anomalía elevadas en uno de ellos — al menos 3 agentes distintos que reportan en al menos 20 interacciones — se entrega una notificación a tu 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.

Este camino se ejercita de extremo a extremo en CI (ver scripts/db-contract-test.mjs): los informes de anomalía sembrados en una habilidad suscrita deben producir una notificación, o la compilación falla. ACR no rastrea al humano detrás de un agente, por lo que las notificaciones llegan al agente, no al propietario.

El registro de habilidades

ACR observa habilidades que ya existen en registros públicos (npm, GitHub) y rastrea señales de comportamiento vinculadas a ellas: conteos de adopción, señales de anomalía, historial de versiones. No es un catálogo desde el que instalar ni una verificación de seguridad — registra lo que la red observó. La búsqueda clasifica primero las habilidades con señales; las entradas de catálogo sin una identidad utilizable se rechazan en el momento del rastreo.

Arquitectura

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.

Recopilación de datos

ACR recopila solo metadatos de interacción: nombres de sistemas objetivo, tiempos, estado, contexto de cadena y clase de proveedor. Sin contenido de solicitud/respuesta, claves API, prompts ni PII. Tu perfil de interacción es visible solo para ti; las líneas base de población usan estadísticas agregadas sobre agentes persistentes.

Lo que recopilamos: nombres de sistemas objetivo (mcp:github, api:stripe.com), tiempos de interacción (duración, marcas de tiempo, espera en cola, conteo de reintentos), estado de interacción, clase de proveedor del agente, hashes de composición (SHA-256 del contenido de SKILL.md), contexto de cadena, banderas de anomalía reportadas por el agente (solo categoría).

Lo que NO recopilamos: cargas útiles de solicitud/respuesta, credenciales, prompts o completaciones, PII, contenidos de archivos, ni la identidad del humano detrás del agente.

Retención (aplicada por los trabajos programados data-archival y agent-expiration): recibos de interacción 90 días y luego archivados en resúmenes diarios; notificaciones 90 días; registros de agentes expirados suavemente después de 90 días de inactividad; datos de observación de habilidades retenidos mientras se observa la habilidad.

Compartición con terceros: ninguna. Contacto: security@tethral.com · Términos completos

Bancos de pruebas

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)

El banco de pruebas db-contract existe porque las pruebas unitarias simulan la base de datos mientras que la producción usa CockroachDB — las diferencias de dialecto rompieron la misma consulta de lente tres veces antes de que se añadiera. Cada ruta de lente debe devolver 200, no degradada, y conteos que coincidan con los datos sembrados; la promesa de notificación se verifica de extremo a extremo.

Desarrollo

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

Regla de lanzamiento: cambiar packages/mcp-server, packages/acr-hook o un SDK requiere un aumento de versión (el CI de PR lo aplica), y las fusiones a master publican automáticamente cualquier paquete con versión aumentada. Una corrección fusionada que nunca llega a npm es una corrección que nunca ocurrió.

Opcional: usa ACR en tu propio trabajo mientras desarrollas en este repositorio. Copia .mcp.json.example a .mcp.json y cualquier cliente compatible con MCP que abra este directorio cargará el @tethral/acr-mcp publicado. Opt-in por diseño: .mcp.json está en gitignore para que los contribuyentes nunca se inscriban implícitamente. Para probar cambios locales de MCP, apunta command a node y args a ./packages/mcp-server/dist/cli/stdio.js después de pnpm build.

Licencia

MIT

Enlaces

API: https://acr.nfkey.ai
npm (hook): @tethral/acr-hook
npm (MCP): @tethral/acr-mcp
npm (SDK): @tethral/acr-sdk
PyPI: tethral-acr