Esquema de solicitud de acción de agente de IA
Una solicitud de acción registra la autoridad que un agente de IA pide usar antes de la evaluación de política y de cualquier efecto de herramienta. Esta referencia independiente conserva la forma de requested_action del evento de auditoría publicado y añade un action_request_id direccionable más correlación para uso independiente.
JSON Schema draft 2020-12 · Versión 1.0.0 · Nombres de campo normativos en inglés
Referencia rápida
- Definición
- Un registro independiente de una acción de agente solicitada: capacidad, propósito, recurso, límite de datos, entorno y hora de la solicitud.
- Cuándo se usa
- Créalo cuando un agente proponga una acción gobernada. Vincúlalo a los registros de política, aprobación, herramienta y auditoría mediante correlación.
- Campos obligatorios
- El ID de la solicitud, la versión del esquema, los ID de correlación, la acción, el propósito, el recurso, el límite de datos, el entorno y requested_at.
- Detalle opcional
- Incluye amount para acciones financieras y contexto de traza cuando la ejecución lleva identificadores de OpenTelemetry.
01
Esquema y ejemplos
Los artefactos versionados son autocontenidos. Los consumidores pueden validar la solicitud sin cargar el esquema del evento de auditoría.
/ai-agent-action-request/v1/schema.jsonDescargar Ejemplo de lectura básicaSolicitud sintética mínima sin importe financiero./ai-agent-action-request/v1/examples/basic-read.jsonDescargar Ejemplo de disposición de créditoAcción financiera sintética con importe y correlación de traza./ai-agent-action-request/v1/examples/credit-disposition.jsonDescargar 02
Objeto y orden de ejecución
La solicitud es el primer contrato duradero de la secuencia de referencia. La política la evalúa antes de que se registre una aprobación o un efecto de herramienta.
- 01SolicitudEl agente propone una acción sobre un recurso con nombre dentro de un límite de datos y un entorno declarados.
- 02CorrelacionarEl action_request_id identifica este registro independiente. correlation_id y execution_id lo conectan con el grafo de ejecución.
- 03EvaluarLa decisión de política registra allow, warn, require_approval o block para la misma correlación de ejecución.
- 04ContinuarUna llamada a herramienta sigue a una ruta permitida o con advertencia. Una ruta require_approval registra un evento de aprobación antes de un efecto.
03
Diccionario de campos
El diccionario cubre cada campo de nivel superior, miembro anidado de recurso, miembro de correlación y miembro financiero condicional.
Identidad independiente y correlación
| Campo | Estado | Propósito |
|---|---|---|
| schema_version | Obligatorio | Selecciona el contrato de compatibilidad usado para analizar el registro. |
| action_request_id | Obligatorio | Direcciona esta solicitud de forma independiente y la vincula a un evento de auditoría. Añadido para la publicación independiente. |
| correlation.correlation_id / execution_id | Obligatorio | Une la solicitud a los registros de política, aprobación, herramienta y auditoría sin una unión por marca de tiempo. Añadido para la publicación independiente. |
| correlation.trace_id / span_id / parent_event_id | Opcional | Lleva el contexto de traza de OpenTelemetry y un evento padre opcional. Los identificadores W3C compuestos solo por ceros no son válidos. |
Autoridad solicitada
| Campo | Estado | Propósito |
|---|---|---|
| action | Obligatorio | Nombra la capacidad que el agente propone usar. |
| purpose | Obligatorio | Indica el propósito de negocio suministrado a la evaluación de política. |
| resource.type / resource.id | Obligatorio | Identifica el recurso objetivo y su tipo de recurso. |
| data_boundary_ref | Obligatorio | Nombra el límite de datos gobernado asociado a la solicitud. |
| environment | Obligatorio | Identifica el entorno de ejecución suministrado a la solicitud. |
| requested_at | Obligatorio | Registra cuándo se solicitó la acción como una fecha y hora RFC 3339. |
| amount.value / amount.currency | Condicional | Lleva una cadena decimal y una moneda de tres letras en mayúsculas cuando el valor financiero afecta a la política. |
04
Ejemplo mínimo
Este ejemplo contiene los campos obligatorios para una acción de lectura sintética. El segundo ejemplo descargable añade amount y contexto de traza.
{
"schema_version": "1.0.0",
"action_request_id": "req_action_demo_0001",
"correlation": {
"correlation_id": "corr_credit_review_demo_0001",
"execution_id": "exec_credit_review_demo_0001"
},
"action": "read_case_summary",
"purpose": "review_credit_case",
"resource": {
"type": "credit_case",
"id": "case_demo_0001"
},
"data_boundary_ref": "boundary_credit_case_minimum",
"environment": "staging",
"requested_at": "2026-07-21T09:14:29.100Z"
}05
Validación y verificación de 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 recursivamente, siguiendo el enfoque del verificador publicado para el evento 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 resultado de verificación fallido y conserva el registro original para la investigación.
Solicitud válida según el esquema
Los ejemplos descargables validan contra draft 2020-12 y producen un digest sha256: reproducible a partir de su contenido canónico.
Comprobación de manipulación
Cambiar un campo como action 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 independiente por separado de las versiones de agentes, políticas y herramientas.
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 los cambios en la canonicalización requieren una nueva ruta de versión 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 esquema de auditoría embebido es la fuente normativa de campos. Los productores en tiempo de ejecución exponen campos relacionados que la forma pública independiente puede vincular y normalizar.
| Área del contrato | Fuente actual | Asignación | Estado |
|---|---|---|---|
| Forma embebida de la acción solicitada | apps/platform/src/lib/ai-agent-audit-event/v1/schema.json | El esquema del evento de auditoría define requested_action.action, purpose, resource, data_boundary_ref, environment, amount y requested_at. Esta página publica esos campos en el nivel superior. | Fuente de referencia publicada |
| Hechos de solicitud de herramienta en tiempo de ejecución | services/execution-worker/src/services/audit-events.ts | recordToolAuditEvent registra executionId, toolName, toolAction, ámbitos de datos y hashes de los parámetros y resultados de la herramienta. La función no emite este objeto de solicitud independiente normalizado. | Productor relacionado actual |
| Correlación de ejecución | services/execution-worker/src/services/audit-events.ts | Los registros de auditoría de herramienta llevan executionId y el ID de traza activo de OpenTelemetry. Los consumidores usan el objeto correlation independiente para unir esos hechos de tiempo de ejecución. | Productor relacionado actual |
| Vínculo entre política y auditoría | services/shared/src/policy/contracts.ts | Los contratos GateContext y GateDecision proporcionan los identificadores de ejecución del lado de la política y los valores de decisión canónicos usados después de evaluar esta solicitud. | Contrato consumidor actual |
Abstracciones deliberadas y campos no admitidos
- •El esquema omite los ID de base de datos de tenant, los ID internos de fila y la sintaxis de políticas de Cerbos.
- •El esquema lleva referencias a recursos y data_boundary_ref. No lleva contenidos brutos de recursos, prompts, salida del modelo, argumentos de herramienta ni resultados de herramienta.
- •El esquema no afirma que el solicitante esté autorizado. La decisión de política y la ruta de autorización consumidora establecen el resultado de control aplicable.
- •El esquema no prescribe cómo una implementación resuelve una referencia de límite de datos ni cómo conserva los datos referenciados.
- •El action_request_id independiente y el objeto correlation son adiciones para la publicación independiente. El objeto requested_action embebido no tiene ninguno de los dos campos.
- •Los ejemplos públicos contienen ID y marcas de tiempo sintéticos. No llevan datos de clientes ni material de credenciales.
08
Referencias relacionadas
Sigue la secuencia de ejecución gobernada desde la solicitud hasta la política, la aprobación y el evento de auditoría completo.
El resultado de política evaluado para esta acción solicitada.
El registro maker-checker usado cuando la política requiere aprobación humana.
El sobre de evento completo que conecta solicitud, política, aprobación, herramientas y resultado.
Aplica el contrato
Conecta la solicitud con el resto del registro de ejecución gobernada.
Usa el esquema de registro de auditoría para el sobre de evento completo y después sigue las referencias vinculadas de política y aprobación a lo largo de la secuencia de ejecución.