Puntos clave
- Use una envoltura inmutable para identidad, orden, tenant, tiempo, versión e información de integridad.
- Modele solicitudes, decisiones de autorización, intentos de herramientas, aprobaciones y efectos externos como eventos separados.
- Valide evolución del esquema, redacción, acceso y compatibilidad de exportación antes de aceptar una versión nueva.
Separe la envoltura común del payload de negocio
La envoltura debe ser igual para todos los productores. Incluya identificador y tipo de evento, versión del esquema, tenant, ejecución y ejecución superior, actor, servicio emisor, entorno, región, tiempo observado, tiempo emitido, posición de secuencia e información de integridad. Mantenga los campos específicos dentro de un payload tipado.
Una envoltura inmutable permite consultar y verificar eventos producidos por gateways de modelos, runtimes de agentes, servicios de aprobación y adaptadores de herramientas sin que cada componente invente nombres distintos para los mismos conceptos.
- Use identificadores globalmente únicos y estables, no números de fila de una base de datos.
- Registre tanto el actor lógico como la identidad técnica usada en el límite del sistema.
- Distinga el tiempo del evento del tiempo de ingreso para detectar entregas tardías.
- Indique la versión de normalización y hash cuando calcule campos de integridad.
{
"schema_version": "1.0.0",
"event_id": "0198f2f2-7a3b-7d64-8e21-b7c9386c1801",
"event_type": "tool.completed",
"tenant_id": "tenant_acme",
"execution_id": "exec_20260823_1042",
"parent_event_id": "0198f2f2-6e31-7ad4-91ab-c5f93104dd12",
"actor": {
"type": "ai_agent",
"id": "agent:invoice-reviewer",
"credential_id": "workload:invoice-reviewer"
},
"source": {
"service": "agent-runtime",
"version": "2026.08.1"
},
"environment": "production",
"region": "us-east-1",
"event_time": "2026-08-23T10:42:31.184Z",
"observed_at": "2026-08-23T10:42:31.229Z",
"sequence": 42,
"integrity": {
"canonicalization": "jcs-v1",
"hash_algorithm": "sha-256",
"payload_hash": "sha256:77418e964aac33bbf7ad94e7a43b833c08d53dd8156a6ea1ad18d25e6c3c26fe",
"previous_event_hash": "sha256:b2e95e6a232cebc7a1ee00d8331212c888af5fb4225620f15adf7e5cc9444e46"
},
"payload": {
"tool": {
"name": "erp.create_credit_note",
"version": "2.3.1"
},
"operation_id": "op_1042",
"attempt": 1,
"authorization": {
"decision": "allow",
"policy_id": "finance-credit-note-v4"
},
"approval_id": "approval_7842",
"idempotency_key": "credit-note:CN-2026-1042",
"input_digest": "sha256:8cbb1f38093a5e9af1206feb9fd7f310e5333822f07778c2ede5629c666c9761",
"outcome": "succeeded",
"external_reference": {
"system": "erp",
"type": "credit_note",
"id": "CN-2026-1042"
},
"result_digest": "sha256:7e17a509ba134cf46597d97909f2a6eac27ce54b6fba1d4e30b816620af808d0"
}
}Defina tipos de evento alrededor de decisiones y efectos
Evite un evento único que afirme que una solicitud fue autorizada, ejecutada y completada. Emita registros separados para aceptación, decisión de política, llamada al modelo, propuesta de herramienta, aprobación humana, intento, confirmación externa, finalización, rechazo, fallo y resultado desconocido.
Conecte intentos mediante identificadores de ejecución, operación e idempotencia. Así un revisor puede distinguir un reintento de una nueva decisión y rastrear una transacción externa hasta la autoridad y las entradas exactas.
Evolucione el esquema sin reinterpretar evidencia anterior
Trate cada cambio como un contrato de compatibilidad. Añada campos opcionales cuando sea posible, publique una nueva versión si cambia el significado y conserve validadores para todas las versiones retenidas. No cambie la interpretación de un campo después de comprometer la evidencia.
Pruebe productores y consumidores con exportaciones históricas. Una versión nueva debe rechazar eventos mal formados, aislar versiones no admitidas y conservar campos desconocidos cuando se requiera una exportación reversible.
Incluya privacidad y revisión independiente en el diseño
Clasifique cada campo como obligatorio, opcional, sensible, resumido por hash, tokenizado o referenciado externamente. Registre la política de redacción y la versión de clave, pero no coloque credenciales ni prompts completos sin control en la envoltura canónica.
La exportación debe incluir definiciones de esquema, archivos de eventos, checksums, secuencias o pruebas de Merkle y un manifiesto de campos omitidos o protegidos. De este modo se puede verificar estructura e integridad sin entregar datos de origen innecesarios.