Esquema de evento de aprobación de agente de IA
Un evento de aprobación registra el ciclo de vida de la decisión de una acción de agente de IA gobernada que llegó a revisión humana. Esta referencia independiente conserva la definición de aprobación del evento de auditoría publicado y añade un approval_event_id direccionable más la correlación para su uso independiente.
JSON Schema draft 2020-12 · Versión 1.0.0 · Registro de decisión maker-checker
Referencia rápida
- Definición
- Un registro independiente del estado de una solicitud de aprobación, el rol requerido, el revisor humano cuando se decide, la decisión, los tiempos y las referencias opcionales a la justificación.
- Cuándo se usa
- Créalo después de que un resultado de política derive una acción a aprobación humana y regístralo cuando la solicitud se decida, venza o se cancele.
- Valores de decisión
- approved, rejected, expired y cancelled describen la decisión terminal representada por el evento.
- Maker-checker
- Las rutas de aprobación actuales comprueban approval:decide, el rol requerido, el estado pendiente y la separación de funciones antes de registrar una decisión.
01
Esquema y ejemplos de aprobación
El esquema versionado y dos ejemplos de decisión terminal son artefactos autocontenidos para validación e implementación de referencia.
/ai-agent-approval-event/v1/schema.jsonDescargar Ejemplo de evento aprobadoAprobación decidida con un revisor humano sintético./ai-agent-approval-event/v1/examples/approved.jsonDescargar Ejemplo de evento rechazadoRechazo decidido con un código de motivo y una referencia a la justificación./ai-agent-approval-event/v1/examples/rejected.jsonDescargar 02
Objeto y orden de ejecución
Un evento de aprobación se sitúa entre un resultado de política require_approval y cualquier efecto de herramienta aprobado. Las rutas de vencimiento y rechazo siguen siendo resultados denegados o no iniciados enlazables.
- 01SolicitudUn resultado de política require_approval crea una solicitud asociada a la correlación de ejecución y a un rol requerido.
- 02RevisiónUn revisor recibe la evidencia presentada y actúa a través de una ruta de aprobación con permiso approval:decide.
- 03ComprobaciónLas rutas actuales comprueban el rol requerido, el estado pendiente y la separación maker-checker. La aprobación también requiere un reconocimiento explícito.
- 04RegistroLa decisión se persiste y se escribe una obligación de auditoría duradera antes de señalar al flujo de trabajo bloqueado que se reanude.
03
Diccionario de campos
El diccionario cubre cada miembro de la aprobación, incluidos los condicionales del ciclo de vida y las referencias opcionales de reasignación, anulación y apelación.
Identidad independiente y correlación
| Campo | Estado | Propósito |
|---|---|---|
| schema_version | Obligatorio | Selecciona el contrato de compatibilidad usado para analizar el registro. |
| approval_event_id | Obligatorio | Direcciona de forma independiente este evento de aprobación y lo enlaza con un evento de auditoría. Añadido para la publicación independiente. |
| correlation.correlation_id / execution_id | Obligatorio | Une la aprobación con la secuencia de solicitud, política, herramienta y auditoría. Añadido para la publicación independiente. |
| correlation.trace_id / span_id / parent_event_id | Opcional | Transporta el contexto de traza de OpenTelemetry y un evento padre opcional. Los identificadores W3C compuestos solo por ceros no son válidos. |
Ciclo de vida de la solicitud de aprobación
| Campo | Estado | Propósito |
|---|---|---|
| request_id | Obligatorio | Identifica la solicitud de aprobación que se decide. Esto conserva el significado de approval.request_id incrustado. |
| status | Obligatorio | Indica si el evento está en estado decided, expired o cancelled. |
| requested_at / expires_at | Obligatorio | Registra los tiempos de solicitud y vencimiento como date-times RFC 3339. |
| required_role | Obligatorio | Nombra el rol requerido para decidir la aprobación. |
| decided_at | Obligatorio | Registra cuándo se registró la decisión terminal, el vencimiento o la cancelación. |
Decisión y referencias de apoyo
| Campo | Estado | Propósito |
|---|---|---|
| decision | Obligatorio | Transporta approved, rejected, expired o cancelled y coincide con el estado del ciclo de vida. |
| reviewer | Condicional | Identifica al revisor humano cuando el estado es decided. El tipo es siempre user. |
| presented_evidence_digest | Opcional | Vincula la decisión a la representación de la evidencia mostrada para la revisión. |
| reason_code / rationale_reference | Opcional | Proporciona un motivo estable y una referencia a una justificación de decisión más completa. |
| reassigned_from | Opcional | Conserva el principal anterior cuando una solicitud de aprobación cambia de asignatario. |
| override.authority_reference / reason_code | Opcional | Referencia la autoridad excepcional y su motivo cuando se registra una anulación. |
| appeal.status / reference | Opcional | Enlaza un ciclo de vida de apelación posterior y su referencia estable. |
04
Ejemplo mínimo
El registro aprobado muestra los campos obligatorios más el revisor necesario para un estado decidido. El registro rechazado proporciona una segunda decisión terminal.
{
"schema_version": "1.0.0",
"approval_event_id": "evt_approval_demo_0001",
"correlation": {
"correlation_id": "corr_credit_review_demo_0002",
"execution_id": "exec_credit_review_demo_0002"
},
"request_id": "approval_req_demo_0001",
"status": "decided",
"requested_at": "2026-07-21T11:03:18.240Z",
"expires_at": "2026-07-21T11:33:18.240Z",
"required_role": "kla:senior_approver",
"presented_evidence_digest": "sha256:9999999999999999999999999999999999999999999999999999999999999999",
"reviewer": {
"id": "user_reviewer_demo_0001",
"type": "user",
"display_name": "Synthetic reviewer",
"identity_provider": "demo-idp"
},
"decision": "approved",
"reason_code": "evidence_reviewed",
"rationale_reference": "rationale_demo_0001",
"decided_at": "2026-07-21T11:04:10.240Z"
}05
Validación y verificación de digest
La validación con JSON Schema comprueba la forma del estado y de la decisión. El verificador complementario reproduce un digest sha256: sobre el registro canónico y puede comprobar una firma Ed25519 separada opcional.
- 01Carga el esquema versionado desde la URL de descarga del JSON Schema.
- 02Valida el documento JSON con un validador draft 2020-12 y un complemento de formato date-time.
- 03Canonicaliza el registro independiente completo con las claves de objeto ordenadas de forma recursiva, siguiendo el enfoque del verificador de eventos de auditoría publicado.
- 04Calcula SHA-256 sobre los bytes canónicos y representa el resultado con el prefijo sha256:.
- 05Compara el digest calculado con el digest conservado por el procedimiento de evidencia que realiza la llamada.
- 06Cuando se proporciona una firma Ed25519 separada, resuelve su clave pública de forma independiente y verifica la firma sobre el digest de 32 bytes.
- 07Registra una discrepancia de hash o un fallo de firma como resultado de verificación fallido. Conserva el registro de decisión y su solicitud enlazada para revisión.
Ejemplos de decisión terminal
Los ejemplos aprobado y rechazado validan según draft 2020-12 y producen digests sha256: reproducibles a partir de su contenido canónico.
Comprobación de manipulación
Cambiar la decisión cambia tanto el significado del ciclo de vida como el digest canónico. El verificador informarecord_hash_mismatch.
El verificador independiente acepta una firma Ed25519 separada opcional. La confianza en una clave pública proviene del registro de claves gobernado de forma independiente por quien realiza la llamada.
06
Compatibilidad y versionado
Versiona el contrato del evento de aprobación de forma independiente del servicio de aprobación y del contrato de política.
Parche
Las aclaraciones, descripciones y ejemplos pueden cambiar mientras el comportamiento de validación se mantiene estable. Un artefacto inmutable corregido recibe una nueva URL versionada.
Menor
Los nuevos campos opcionales requieren un nuevo schema_version y una URL versionada. Los consumidores declaran soporte antes de procesar la nueva versión.
Mayor
Los campos eliminados o renombrados, los cambios de significado, un estado obligatorio más estricto o cambios en la canonicalización requieren una nueva ruta mayor.
Los consumidores conservan las versiones desconocidas para revisión y detienen el procesamiento semántico hasta que se declare soporte. La ruta v1 usa schema_version 1.0.0.
07
Cómo lo implementa KLA
El worker crea registros de auditoría de aprobación. Las rutas de la API aplican la autoridad de decisión y persisten una obligación de decisión duradera.
| Área del contrato | Fuente actual | Asignación | Estado |
|---|---|---|---|
| Eventos de solicitud y resolución de aprobación | services/execution-worker/src/services/audit-events.ts | El worker registra eventos de auditoría de aprobación solicitada y resuelta con campos relacionados con la ejecución, la aprobación, la gobernanza, la decisión, el motivo y la traza. Esta página normaliza esos hechos a la forma portátil del evento de aprobación. | Productor actual con normalización |
| Ruta de decisión maker-checker | services/execution-api/src/routes/approvals.ts | La ruta comprueba el permiso approval:decide, el rol requerido, el estado pendiente y la autoaprobación. Aprobar también requiere un reconocimiento explícito; una escalada mantiene la solicitud pendiente. | Consumidor y productor actual |
| Decision Desk y ruta de aprobación local | services/api/src/routers/approvals.ts | El router aplica las mismas reglas de permiso y de acceso maker-checker, valida los conjuntos de comprobaciones de política y evidencia, persiste un registro de decisión y coordina el estado de aprobación local o de execution-api. | Consumidor y productor actual |
| Vocabulario de decisión y versión | services/shared/src/policy/contracts.ts | El contrato de política compartido proporciona require_approval como la ruta que conduce a este evento y mantiene el versionado de la política independiente del esquema del evento de aprobación. | Contrato compartido actual |
Abstracciones deliberadas y campos no admitidos
- •El esquema omite los ID de base de datos de tenant, las columnas de la tabla de aprobaciones, la sintaxis de autorización de Cerbos y el contenido bruto de solicitudes o evidencia.
- •El esquema registra required_role y la identidad del revisor. No demuestra que el revisor tuviera ese rol en el momento de la decisión; los consumidores realizan esa comprobación de autoridad.
- •El esquema tiene los valores de estado terminal decided, expired y cancelled. La acción de escalada de la API actual mantiene la solicitud pendiente y no tiene un valor terminal escalated en este contrato.
- •El esquema transporta referencias opcionales de evidencia, justificación, reasignación, anulación y apelación. No define el paquete de evidencia, el procedimiento de apelación ni la política de autoridad de anulación.
- •El esquema no publica el correo electrónico del revisor, instantáneas de roles, comentarios ni recibos de decisión. Esos campos permanecen en los registros de decisión y auditoría de KLA y pueden enlazarse mediante los ID de correlación y de solicitud.
- •El approval_event_id independiente y el objeto correlation son adiciones para la publicación independiente. request_id conserva el significado de solicitud de aprobación del objeto approval incrustado.
08
Referencias relacionadas
Sigue la secuencia de ejecución desde la solicitud de acción hasta la decisión de política, la aprobación cuando se requiere y el evento de auditoría completo.
La acción que llegó a la evaluación de política.
El resultado require_approval que deriva la acción a revisión.
El sobre de evento completo que registra la solicitud, la decisión, la aprobación, el efecto y el resultado.
Aplica el contrato
Mantén la decisión humana enlazada a la rama de política que resuelve.
Usa los identificadores de correlación y de solicitud para conectar el evento de aprobación con la solicitud de acción, la decisión de política, el evento de auditoría completo y los registros de evidencia posteriores.