Esquema de registro de auditoría de agentes de IA: acciones, herramientas, aprobaciones y resultados
Un evento de auditoría de agente de IA es un registro duradero que conecta una acción solicitada con la identidad, la autoridad delegada, la política, la revisión humana, los efectos de herramientas, el resultado de negocio y la prueba de integridad. Este contrato público es neutral respecto al proveedor y utiliza los productores actuales de KLA solo en el mapeo de implementación.
JSON Schema draft 2020-12 · Publicado el 2026-07-28 · Nombres de campo normativos en inglés
Referencia rápida
- Definición
- Un evento de auditoría de agente de IA es un registro duradero que conecta una acción solicitada con la identidad, la autoridad delegada, la política, la revisión humana, los efectos de herramientas, el resultado de negocio y la prueba de integridad.
- Aplicabilidad
- Úselo para acciones consecuentes de agentes, incluidas una denegación de política o un intento fallido. Aplique a la implementación los requisitos legales, de privacidad, de retención y sectoriales locales.
- Evidencia mínima
- IDs estables, identidad del actor y del propietario, componentes versionados, autoridad solicitada, resultado de política, aprobación cuando se requiera, efectos, resultado, ordenación, controles de privacidad y estado de verificación.
- Ejemplo desarrollado
- El registro completo sigue una disposición de crédito sintética desde la solicitud, pasando por require_approval, una revisión autorizada, un efecto de herramienta, un resultado de negocio y una firma Ed25519 válida.
01
Esquema y registros saneados
Las cuatro URL versionadas inmutables respaldan la implementación, la validación, los papeles de trabajo de auditoría y las pruebas de regresión.
/ai-agent-audit-event/v1/schema.jsonDescargar Ejecución completaAcción aprobada válida con un efecto descendente./ai-agent-audit-event/v1/examples/complete-execution.jsonDescargar Acción denegadaDecisión block válida sin llamada a herramienta./ai-agent-audit-event/v1/examples/denied-action.jsonDescargar Fallo de manipulaciónRegistro estructuralmente válido cuya carga útil de evento firmada fue modificada./ai-agent-audit-event/v1/examples/tamper-failure.jsonDescargar 02
Una acción desarrollada
La muestra completa registra una disposición de crédito sintética. La política exige un suscriptor autorizado antes de que se ejecute la herramienta con capacidad de escritura.
- 01SolicitudUn usuario delega a un agente una acción de disposición de crédito con alcance acotado.
- 02PolíticaLa versión de política 4.2.1 devuelve require_approval para el importe registrado.
- 03Decisión humanaUn suscriptor sénior revisa la evidencia presentada y aprueba la solicitud vinculada.
- 04Efecto de herramientaUna llamada a herramienta idempotente actualiza el objetivo sintético y registra los resúmenes antes/después.
- 05PruebaEl hash de la carga útil canónica firmada y la firma Ed25519 se verifican con la clave de muestra publicada.
{
"schema_version": "1.0.0",
"event_id": "evt_01JZ8V4R9K2Q7M1W3D5N6P8X0A",
"actors": {
"agent": "agent_credit_review",
"accountable_owner": "role_head_credit_operations"
},
"requested_action": "credit.application.set_disposition",
"policy_decision": "require_approval",
"approval_decision": "approved",
"tool_status": "succeeded",
"business_outcome": "achieved",
"verification": "valid"
}03
Límites de los registros
Cada artefacto responde a una pregunta de auditoría distinta. Un procedimiento de aseguramiento en producción normalmente necesita los cuatro.
| Artefacto | Pregunta | Contenido típico | Límite de integridad |
|---|---|---|---|
| Registro operativo | ¿Qué informó un componente? | Mensajes, métricas, errores, latencia y contexto de tiempo de ejecución local. | Útil para operaciones. La completitud, la identidad, la autoridad y la retención pueden quedar sin especificar. |
| Evento de auditoría | ¿Quién o qué solicitó una acción gobernada, bajo qué autoridad y qué ocurrió? | Identidad, versiones, propósito, recurso, política, aprobación, efecto de herramienta, resultado, privacidad y referencias de integridad. | El registro tiene un esquema estable y un resultado de verificación explícito. La completitud de la población de origen sigue requiriendo conciliación. |
| Linaje de ejecución | ¿Cómo progresó una ejecución en orden? | Spans o eventos ordenados, relaciones padre-hijo, reintentos, llamadas a herramientas y estado. | El linaje aporta secuencia y causalidad. Puede enlazar con varios eventos de auditoría y artefactos de origen. |
| Paquete de evidencia | ¿Qué artefactos retenidos respaldan una aserción de auditoría? | Manifiesto, eventos de auditoría, linaje, registros de política y aprobación, recibos de origen, hashes, firmas, omisiones y redacciones. | La verificación del paquete comprueba la pertenencia de artefactos, los hashes, las firmas, las pruebas del libro mayor y las omisiones declaradas. |
04
Diccionario de campos
Los campos obligatorios se aplican a todos los registros. Los campos condicionales se aplican cuando existe el componente o la ruta de ciclo de vida nombrados. Los campos opcionales conservan detalle portable.
Sobre y ordenación
| Campo | Estado | Propósito |
|---|---|---|
| schema_version | Obligatorio | Selecciona el contrato de compatibilidad utilizado para analizar el registro. |
| audit_event.event_id | Obligatorio | Identifica de forma única este evento de auditoría. |
| audit_event.event_type | Obligatorio | Clasifica una acción completada o denegada. El estado de verificación permanece en integrity. |
| audit_event.occurred_at / recorded_at / sequence | Obligatorio | Separa la hora del evento de la hora de recopilación y conserva una ordenación determinista. |
| audit_event.correlation.correlation_id / execution_id | Obligatorio | Une los registros de política, aprobación, herramienta, resultado y evidencia sin una unión por marca de tiempo. |
| audit_event.correlation.trace_id / span_id / parent_event_id | Opcional | Enlaza el registro con OpenTelemetry o una traza equivalente y con un evento padre. Los identificadores W3C compuestos solo por ceros no son válidos. |
Alcance e identidad
| Campo | Estado | Propósito |
|---|---|---|
| audit_event.scope.organization_ref | Obligatorio | Transporta una referencia de alcance seudónima o controlada por la organización. |
| audit_event.scope.environment / retention_class | Obligatorio | Nombra el límite operativo y el tratamiento de retención aprobado. |
| audit_event.scope.region / legal_hold | Opcional | Registra la ubicación regional y cualquier retención legal que suspenda la eliminación ordinaria. |
| audit_event.actors.requester / agent / accountable_owner | Obligatorio | Vincula la solicitud, la identidad del agente y el rol humano u organizativo responsable. |
| audit_event.actors.delegated_user / service_identity | Condicional | Registra la autoridad en nombre de terceros y la identidad de la carga de trabajo cuando exista alguna de ellas. |
Versiones y autoridad solicitada
| Campo | Estado | Propósito |
|---|---|---|
| audit_event.components.agent | Obligatorio | Fija la Release del agente y el resumen opcional de configuración. |
| audit_event.components.model / prompt_template / orchestrator | Condicional | Fija cada componente que influyó en la acción. |
| audit_event.requested_action.action / purpose | Obligatorio | Indica la capacidad propuesta y el propósito de negocio aprobado. |
| audit_event.requested_action.resource / data_boundary_ref / environment | Obligatorio | Define el objetivo, el límite de datos gobernado y el entorno de ejecución. |
| audit_event.requested_action.amount | Condicional | Utiliza una cadena decimal más la moneda ISO 4217 cuando el valor financiero afecta a la política. |
Política y decisión humana
| Campo | Estado | Propósito |
|---|---|---|
| audit_event.policy.decision_id / policy_id / policy_version | Obligatorio | Identifica la decisión exacta y la versión de política que la rige. |
| audit_event.policy.policy_digest / inputs_digest | Obligatorio | Vincula la evaluación a representaciones protegidas de la política y de las entradas. |
| audit_event.policy.decision | Obligatorio | Transporta allow, warn, require_approval o block. |
| audit_event.policy.matched_rule_ids / reason_codes / evaluated_at | Obligatorio | Hace que el resultado sea explicable y ordenable antes de cualquier efecto. |
| audit_event.approval | Condicional | Obligatorio cuando la política devuelve require_approval. Los efectos de ejecución requieren una solicitud decidida y aprobada por un revisor humano. |
| audit_event.approval.reassigned_from / override / appeal | Opcional | Conserva hechos excepcionales del ciclo de vida de la decisión cuando el sistema de origen los admite. |
Ejecución y resultado
| Campo | Estado | Propósito |
|---|---|---|
| audit_event.tool_calls[] | Obligatorio | Enumera cada llamada a herramienta intentada. Las acciones bloqueadas, no aprobadas y no iniciadas requieren un arreglo vacío. |
| audit_event.tool_calls[].arguments_digest / result_digest | Obligatorio | Vincula argumentos y resultados protegidos sin colocar secretos en el evento. |
| audit_event.tool_calls[].downstream_effects[] | Condicional | Registra los recibos del sistema objetivo y los resúmenes del estado antes/después cuando se producen efectos. |
| audit_event.execution.status / business_outcome | Obligatorio | Separa la finalización técnica del resultado de negocio y vincula la semántica de evento completado o denegado. |
| audit_event.execution.rollback / incident_ref | Condicional | Conecta la recuperación y la investigación cuando se utiliza cualquiera de las dos rutas. |
| audit_event.lineage | Obligatorio | Enlaza la acción con un Lineage Record y sus IDs de evento ordenados. |
Evidencia, privacidad e integridad
| Campo | Estado | Propósito |
|---|---|---|
| audit_event.evidence.manifest_ref / artifacts[] | Obligatorio | Identifica el manifiesto del paquete y los resúmenes de los artefactos de respaldo. |
| audit_event.privacy.classification / redaction_status | Obligatorio | Indica la protección y la transformación aplicadas al registro. |
| audit_event.privacy.redactions[] / access_policy_ref | Obligatorio | Localiza los campos protegidos y la política que rige el acceso. Las entradas coinciden con el estado de redacción declarado. |
| integrity.canonicalization / hash_algorithm / record_hash | Obligatorio | Define y registra el resumen de los metadatos canónicos del sobre firmado y de audit_event. |
| integrity.previous_event_hash | Opcional | Conecta los registros cuando la implementación utiliza una secuencia de eventos enlazada por hash. La firma protege este enlace. |
| integrity.signature | Obligatorio | Transporta el algoritmo, el ID de clave, la clave pública de muestra y la firma separada del resumen. |
| integrity.verification | Obligatorio | Registra valid, failed o not_performed con la versión del verificador y los códigos de fallo. |
05
Verificación de integridad
La validez del esquema y la integridad criptográfica son comprobaciones separadas. La completitud de la población sigue siendo un procedimiento de auditoría aparte.
- 01Valide el sobre con el JSON Schema versionado.
- 02Construya la carga útil firmada a partir de schema_version, audit_event y los metadatos de integrity distintos de record_hash y signature.value.
- 03Canonice la carga útil firmada con el JSON Canonicalization Scheme de RFC 8785.
- 04Calcule SHA-256 y compárelo con integrity.record_hash usando el prefijo sha256:.
- 05Resuelva la clave de confianza por key_id. Verifique su validez y su estado de revocación en occurred_at.
- 06Verifique la firma Ed25519 sobre el resumen de 32 bytes.
- 07Verifique cada previous_event_hash frente a su vecino ordenado y a un ancla del primer enlace retenida de forma independiente antes de aceptar el orden de la secuencia.
- 08Concilie los IDs de evento y los resúmenes de artefactos con el linaje, los efectos en el sistema de origen y el manifiesto de evidencia.
- 09Registre cada código de fallo. Una comprobación fallida o no disponible no puede producir valid.
Ejemplos positivo y denegado
Ambos validan, reproducen sus hashes publicados y se verifican con la clave pública Ed25519 de muestra.
Ejemplo de manipulación
El sobre sigue siendo válido según el esquema. Su resultado de negocio cambió después de la firma, por lo que el hash recalculado difiere y la verificación registrarecord_hash_mismatch.
La clave de muestra incrustada hace que los archivos sean autoverificables. La verificación en producción debe confiar en las claves a través de un registro de claves separado. Una clave suministrada únicamente por el propio registro no puede establecer la identidad del emisor.
06
Correlación con OpenTelemetry
El contexto de traza une la telemetría y la evidencia de auditoría. No transporta la aserción de auditoría completa.
Transportar
Propague W3C traceparent a través del agente, la política, la aprobación, la pasarela de herramientas y las llamadas descendentes. Copie trace_id y el span_id de la acción en correlation.
Vincular
Añada atributos estables execution_id, event_id, decision_id, request_id y call_id. Mantenga las entradas protegidas, los tokens y el contenido bruto del modelo fuera de los atributos ordinarios de span.
Retener
La retención de telemetría puede ser más corta que la retención de auditoría. Conserve el registro de auditoría y la referencia de linaje resoluble después de que expiren las trazas activas.
07
Compatibilidad y versionado
Versione el contrato de forma independiente de las versiones del productor y de las herramientas.
Parche
Las aclaraciones, descripciones y ejemplos pueden cambiar sin modificar el comportamiento de validación. Las URL estables de v1 mantienen contenidos de archivo inmutables, por lo que un artefacto corregido recibe una nueva URL de versión.
Menor
Un nuevo campo opcional o una extensión de enum requiere un nuevo schema_version y una URL versionada. Los consumidores deben rechazar las versiones desconocidas hasta que declaren soporte.
Mayor
Los campos eliminados o renombrados, los cambios de significado, un estado obligatorio más estricto o los cambios de canonicalización requieren una nueva ruta mayor. Los productores pueden escribir en ambas versiones durante la migración.
Los consumidores deben conservar los registros desconocidos para su tratamiento forense y detener el procesamiento semántico cuando la versión del esquema no sea compatible. Nunca deben convertir silenciosamente un resultado de política o un estado de verificación no admitidos.
08
Mapeo a los productores actuales de KLA
El sobre portable es más amplio que cualquier productor individual de KLA. Estas fuentes definen la verdad de implementación actual.
| Área del contrato | Fuente actual | Mapeo | Estado |
|---|---|---|---|
| Identidad del evento de auditoría y anexado duradero | services/api/src/services/audit-logger.ts | AuditEvent proporciona evento, tenant, usuario, recurso, acción, resultado, correlación y contexto de seguridad. El logger replica los eventos con alcance de tenant en ImmuDB. | Fuente actual |
| Productores de eventos de herramienta, política y aprobación | services/execution-worker/src/services/audit-events.ts | Los productores del worker generan hashes de las entradas y resultados de herramientas, capturan la identidad de ejecución y de política, anexan eventos de solicitud y resolución de aprobación y adjuntan el ID de traza activo de OpenTelemetry. | Fuente actual |
| Cuatro resultados de política | services/shared/src/policy/contracts.ts | GateDecisionValueSchema define allow, warn, require_approval y block. Los ayudantes de auditoría más antiguos del worker todavía pueden escribir el resultado bloqueado como deny. | Fuente actual con normalización |
| Decisión de aprobación duradera | services/execution-api/src/services/approval-audit-outbox-worker.ts | La API de aprobación utiliza un outbox idempotente con arrendamiento para anexar un registro de decisión vinculado al tenant. El productor del lado de la solicitud permanece separado. | Fuente actual |
| Linaje de ejecución y correlación de trazas | services/execution-worker/src/services/lineage-trace-publisher.ts | Las ejecuciones gobernadas publican spans raíz y de paso con alcance de ejecución. workflow-observability.ts también emite atributos de política y aprobación a través de OpenTelemetry. | Fuente actual |
| Sealed Evidence Bundle y verificación sin conexión | packages/evidence-contract/src/index.ts | El manifiesto del paquete vincula tenant, exportación, artefactos, raíz de Merkle, hash del manifiesto, metadatos de firma, solicitud de fábrica, omisiones y redacciones. packages/evidence-verifier realiza las comprobaciones independientes. | Fuente actual |
Abstracciones deliberadas y campos no admitidos
- •KLA actualmente no emite este sobre público como un único registro de transmisión nativo. La referencia normaliza varios productores autoritativos en una sola unidad de auditoría.
- •El propietario responsable, los resúmenes completos de configuración de modelo y prompt, las versiones de herramientas, los resultados de negocio, la reversión y las referencias de incidentes no se rellenan de manera uniforme en todas las rutas de tiempo de ejecución de KLA.
- •La reasignación, la anulación y la apelación de una Decision Request son campos de ciclo de vida portables. Los productores actuales de KLA no exponen los tres como un único contrato normalizado a nivel de acción.
- •El contrato registra el rol requerido y la identidad del revisor humano. Los consumidores en producción deben verificar que el revisor tenía el rol requerido cuando se produjo la decisión.
- •KLA firma y verifica el manifiesto del Sealed Evidence Bundle y valida las pruebas del libro mayor y de los artefactos. No todos los registros actuales de KLA incorporan la forma de firma Ed25519 por registro utilizada en estos ejemplos portables.
- •Los ejemplos publican una clave pública de muestra para que los archivos sean autoverificables. Los sistemas en producción deben resolver las claves de confianza a través de un registro de claves gobernado de forma independiente y comprobar la revocación en el momento del evento.
Aplicar el contrato
Sitúe el registro dentro de un método de auditoría completo.
Utilice el marco empresarial para definir el alcance y las pruebas de control. Utilice el programa de auditoría para conciliar poblaciones, muestrear acciones, evaluar la evidencia e informar de las excepciones.