Esquema de respuesta de decisión de política de agentes de IA
Una respuesta de decisión de política registra la identidad de la política, las entradas protegidas, el resultado canónico, las reglas coincidentes, los códigos de motivo y la hora de evaluación. Esta referencia independiente conserva el subobjeto policy del evento de auditoría publicado y añade un policy_decision_event_id direccionable más la correlación para su uso independiente.
JSON Schema draft 2020-12 · Versión 1.0.0 · Cuatro valores de decisión canónicos
Referencia rápida
- Definición
- Una respuesta independiente de la evaluación de políticas con identidad de la política, digests de entradas y de política, una decisión canónica, reglas coincidentes y códigos de motivo.
- Cuándo se usa
- Créala después de evaluar una solicitud de acción y antes de que la ruta de ejecución continúe, se detenga para aprobación o se interrumpa.
- Valores de decisión
- allow, warn, require_approval y block son los valores canónicos del contrato de política compartido.
- Acción denegada
- El ejemplo block registra destination_outside_declared_boundary en reason_codes y no contiene campos de ejecución porque esta página describe el objeto de decisión.
01
Esquema y ejemplos de decisión
El esquema y los cuatro ejemplos de decisión están disponibles como artefactos versionados inmutables. Cada valor de decisión tiene un registro concreto.
/ai-agent-policy-decision/v1/schema.jsonDescargar Ejemplo allowDecisión para una acción dentro del alcance declarado./ai-agent-policy-decision/v1/examples/allow.jsonDescargar Ejemplo warnDecisión que continúa la ruta actual del worker con un marcador de advertencia./ai-agent-policy-decision/v1/examples/warn.jsonDescargar Ejemplo de aprobación requeridaDecisión que dirige la acción a una solicitud de aprobación humana./ai-agent-policy-decision/v1/examples/require-approval.jsonDescargar Ejemplo blockDecisión de acción denegada con un código de motivo de límite./ai-agent-policy-decision/v1/examples/block.jsonDescargar 02
Objeto y orden de ejecución
La respuesta sigue a la solicitud de acción. Su decisión selecciona la ruta antes de una llamada a una herramienta o de un efecto de negocio.
- 01SolicitudLa solicitud de acción del agente aporta la acción, el propósito, el recurso, el límite de datos y el entorno.
- 02EvaluaciónEl evaluador vincula el resultado a policy_id, policy_version, policy_digest, inputs_digest, las reglas coincidentes y los códigos de motivo.
- 03Enrutamientoallow continúa la acción. warn continúa la ruta actual del worker y emite un marcador de advertencia. require_approval crea una ruta de aprobación humana. block detiene la acción.
- 04RegistroLa decisión sigue siendo enlazable con los registros posteriores de aprobación, herramienta y auditoría mediante la correlación.
03
Diccionario de campos
El diccionario cubre todos los miembros obligatorios y opcionales, incluidas las adiciones independientes de identidad y correlación.
Identidad independiente y correlación
| Campo | Estado | Propósito |
|---|---|---|
| schema_version | Obligatorio | Selecciona el contrato de compatibilidad usado para analizar el registro. |
| policy_decision_event_id | Obligatorio | Direcciona de forma independiente este registro de decisión y lo enlaza con un evento de auditoría. Añadido para la publicación independiente. |
| correlation.correlation_id / execution_id | Obligatorio | Une el resultado de política con la secuencia de solicitud, aprobación, 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. |
Identidad de la política y entradas protegidas
| Campo | Estado | Propósito |
|---|---|---|
| decision_id | Obligatorio | Identifica la decisión de evaluación de política dentro del sistema de gobernanza de origen. |
| policy_id / policy_version | Obligatorio | Nombra la política y la versión exacta de la política usada en la evaluación. |
| policy_digest / inputs_digest | Obligatorio | Vincula el resultado a las representaciones protegidas de la política y de las entradas. |
Explicación de la decisión
| Campo | Estado | Propósito |
|---|---|---|
| decision | Obligatorio | Contiene allow, warn, require_approval o block. |
| evaluated_at | Obligatorio | Registra cuándo se completó la evaluación de la política como una fecha y hora RFC 3339. |
| matched_rule_ids | Obligatorio | Enumera los identificadores únicos de las reglas que coincidieron durante la evaluación. |
| reason_codes | Obligatorio | Enumera al menos un identificador único que explica el resultado seleccionado. |
04
Ejemplo mínimo
El registro allow muestra el objeto de decisión completo más pequeño. Las descargas añaden los casos warn, require_approval y block.
{
"schema_version": "1.0.0",
"policy_decision_event_id": "evt_policy_decision_demo_0001",
"correlation": {
"correlation_id": "corr_credit_review_demo_0001",
"execution_id": "exec_credit_review_demo_0001"
},
"decision_id": "dec_demo_0001",
"policy_id": "policy_credit_case_access",
"policy_version": "4.2.1",
"policy_digest": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
"inputs_digest": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
"decision": "allow",
"evaluated_at": "2026-07-21T09:14:29.180Z",
"matched_rule_ids": [
"rule_case_summary_read"
],
"reason_codes": [
"within_declared_scope"
]
}05
Validación y verificación del digest
La validación con JSON Schema comprueba la forma. 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 mismo enfoque que el verificador publicado de eventos de auditoría.
- 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 suministra 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 un resultado de verificación fallido. Una forma válida por sí sola no demuestra que el registro no haya cambiado.
Cuatro resultados válidos según el esquema
Los ejemplos allow, warn, require_approval y block se validan contra draft 2020-12 y producen digests sha256: reproducibles a partir de su contenido canónico.
Comprobación de manipulación
Cambiar reason_codes mantiene el documento estructuralmente legible mientras cambia 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 de respuesta de forma independiente de los paquetes de políticas y de las versiones del evaluador.
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 su compatibilidad antes de procesar la nueva versión.
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 consumidores conservan las versiones desconocidas para su revisión y detienen el procesamiento semántico hasta que se declare la compatibilidad. La ruta v1 usa schema_version 1.0.0.
07
Cómo lo implementa KLA
El contrato de política compartido define el vocabulario de decisión. Las rutas del worker y de ejecución registran la evaluación y la ruta de gobernanza posterior.
| Área del contrato | Fuente actual | Asignación | Estado |
|---|---|---|---|
| Vocabulario de decisión canónico | services/shared/src/policy/contracts.ts | GateDecisionValueSchema y POLICY_SCHEMA_VERSION definen allow, warn, require_approval, block y la versión 1.0.0 del esquema de política. | Contrato compartido actual |
| Registro de la decisión | services/execution-worker/src/services/audit-events.ts | recordPolicyDecisionAuditEvent registra la identidad de la política, la decisión, el motivo, la regla, el flujo de trabajo y los detalles de ejecución. Su helper heredado acepta deny para el resultado bloqueado, por lo que esta página usa el valor canónico compartido block. | Productor actual con normalización |
| Ruta seleccionada por la decisión | services/execution-worker/src/workflows/workflow-spec-runner.ts | La ruta del flujo de trabajo continúa allow y warn, marca warn como advertencia, solicita aprobación para require_approval y detiene block. | Consumidor de ejecución actual |
| Enlace con la auditoría | services/execution-worker/src/services/audit-events.ts | Los productores de auditoría de política y aprobación conservan los identificadores de ejecución y el contexto de traza activo para que una decisión pueda unirse al registro de ejecución que la rodea. | Productor relacionado actual |
Abstracciones deliberadas y campos no admitidos
- •El esquema omite los documentos de política de Cerbos, los cuerpos de reglas JSON Logic, las cargas de entitlements y la configuración del evaluador.
- •El esquema registra digests de la política y de las entradas. No publica el texto protegido de la política, los argumentos de la solicitud, los prompts, la salida del modelo ni datos personales sin procesar.
- •El esquema registra una decisión canónica. No codifica cada señal de control interna, clasificación, remediación o traza de juez que transporta el contrato compartido GateDecision más amplio.
- •El esquema registra los ID de reglas coincidentes y los códigos de motivo. No afirma que un código de motivo demuestre la autorización, el aislamiento de tenants ni la completitud de la población de origen.
- •El policy_decision_event_id independiente y el objeto correlation son adiciones para la publicación independiente. El objeto policy incrustado no tiene ninguno de los dos campos.
- •Los ejemplos son registros sintéticos. Sus valores de digest demuestran las restricciones de los campos y no contienen identificadores de clientes ni de producción.
08
Referencias relacionadas
Sigue la solicitud, la decisión de política, la aprobación cuando se requiere y el evento de auditoría completo en orden de ejecución.
La acción solicitada que evalúa esta respuesta de política.
El registro maker-checker usado cuando el resultado es require_approval.
El sobre de evento completo para la solicitud, la política, la aprobación, la herramienta, el resultado y el registro de integridad.
Aplica el contrato
Mantén el resultado de política junto a la solicitud que evaluó.
Usa las referencias de la solicitud de acción y de la aprobación con esta respuesta y, después, usa el esquema de registro de auditoría para conservar la secuencia completa de ejecución gobernada.