API de radiodifusión para agentes de IA: ejecución segura

Un agente envía un cambio en la programación. Se agota el tiempo de espera de la solicitud. ¿La rechazó el servidor o desapareció la respuesta tras aceptarse el cambio? Las API de emisión para agentes de IA necesitan una respuesta explícita a esa incertidumbre antes de que nadie active los reintentos automáticos.

Un agente puede ayudar a interpretar una prolongación de un programa, investigar información contradictoria y proponer una programación revisada. La API debe hacer cumplir los límites de los cambios autorizados al agente. Los siguientes diseños son patrones de ingeniería ilustrativos, no descripciones de endpoints existentes de Evrideo.

Asigne a las API de radiodifusión para agentes de IA un ámbito de aplicación limitado

Distinga entre la lectura de una programación, la edición de un borrador y la publicación de un cambio aprobado. Otorgue a cada integración únicamente los permisos que necesite y restrinja los lugares en los que se puede utilizar su token. Las directrices de seguridad de OAuth recomiendan privilegios mínimos y restricciones de audiencia, de modo que los servidores de recursos comprueben el recurso y la acción permitidos en cada solicitud. La RFC 9700 explica dichos límites.

Un token válido sigue requiriendo comprobaciones a nivel de objeto. El servidor debe verificar que este solicitante pueda editar el canal de esta cuenta cliente, incluidos los identificadores de activos anidados dentro de la solicitud. Mantenga las credenciales fuera del prompt del modelo y exponga operaciones pequeñas y tipificadas, en lugar de una herramienta HTTP o de shell de uso general.

Vincule la aprobación al cambio real

Para una acción de gran impacto, almacene la aprobación en el código de un servidor de confianza. Vincúlela al cambio propuesto, al canal de destino, a la revisión prevista de la programación, a la identidad del aprobador y a la fecha de caducidad. Una propuesta modificada requiere una nueva evaluación. Un campo approved: true generado por el modelo no constituye un permiso.

Las directrices de OWASP sobre «excesiva autonomía» recomiendan la aprobación humana para acciones de alto impacto y la autorización en los sistemas de destino. Aplique esa política también a los procesos que ejecutan tareas en cola. Una aprobación que caduque mientras un comando espera en una cola requiere una política de ejecución explícita.

Propuesta de agenteCanal designado, cambio exacto y revisión prevista

Servicio de control fiableCompruebe los permisos, la aprobación y el estado actual.

Servicio de ejecuciónRealice el seguimiento del trabajo, aplique el cambio e informe del resultado

El agente propone una operación. Los controles del lado del servidor siguen siendo responsables de la autorización, incluso en el momento de la ejecución.

Proteja la revisión de la programación

Supongamos que un agente prepara una sustitución tras leer la revisión 42. A continuación, un programador inserta un boletín urgente, creando la revisión 43. La publicación de la propuesta anterior del agente podría anular ese trabajo.

Una API puede exponer un ETag fuerte y exigir If-Match al escribir en dicho recurso. Una condición previa fallida suele generar 412 Precondition Failed. El cliente debe recuperar la programación actual y ajustar su propuesta antes de solicitar la aprobación de nuevo. La semántica HTTP define las solicitudes condicionales y distingue entre la aceptación y la finalización.

Para la ejecución asíncrona, no basta con comprobar la revisión cuando un trabajo entra en la cola. Defina una reserva o una comprobación atómica de la versión cuando se aplique el cambio. La aprobación y la revisión de la programación deben seguir coincidiendo con la operación que se está ejecutando.

Haga que los reintentos repitan la misma operación

La idempotencia permite a un cliente repetir una operación lógica sin duplicar el efecto deseado. Mantenga la misma clave de operación y la carga útil sin cambios para un reintento admitido. Defina la cuenta cliente a la que pertenece la clave, la coincidencia de la carga útil, el periodo de retención y el tratamiento de los duplicados simultáneos.

El contrato de idempotencia de la API v1 de Stripe es un ejemplo de implementación útil: una vez iniciada la ejecución, las claves repetidas devuelven el resultado guardado, y los parámetros diferentes se rechazan. Sus reglas de retención y de repetición de errores pertenecen a dicha API; una integración de radiodifusión requiere su propio contrato documentado.

La deduplicación debe extenderse al ejecutor. Un registro de la base de datos seguido de un mensaje de cola no rastreado deja una ventana de fallo. Documente cómo la identidad de la operación llega a los sistemas posteriores y cómo la recuperación determina si se ha producido algún efecto. Una caché de claves de solicitud por sí sola no puede garantizar una ejecución «exactamente una vez».

1. 1
   El agente envía la operación K

   La API comprueba la propuesta y registra el trabajo J en relación con la clave de operación.

2. 2
   La respuesta se ha perdido

   El cliente agota el tiempo de espera. Es posible que la tarea J siga ejecutándose.

3. 3
   El cliente determina el resultado

   Consulte el registro de la operación mediante acceso autenticado o reenvíe la operación K según el contrato documentado. Mantenga la carga útil sin cambios.

4. 4
   Verifique cada etapa

   Lea el estado de la tarea, confirme la configuración aplicada y compruebe la señal de salida cuando el cambio deba estar en antena.

Si el registro de estado no está disponible, el resultado puede seguir siendo desconocido. Encargue su verificación a un ingeniero si la API no permite determinarlo de forma segura.

Los identificadores de tareas del diagrama son ejemplos. Muestran por qué es peligroso generar una clave nueva tras cada tiempo de espera: el servidor podría tratar cada intento como una instrucción independiente.

Establezca un plazo para la incertidumbre

Las directrices de AWS sobre tiempos de espera, reintentos y fluctuaciones explican que un tiempo de espera no garantiza que se hayan evitado los efectos secundarios. Configure un número finito de intentos, una espera creciente entre intentos, con un máximo y una variación aleatoria, además de un plazo global que incluya los reintentos del SDK y el tiempo de espera. Realizar reintentos de forma independiente en varias capas puede multiplicar la carga.

Vuelva a intentar únicamente los fallos transitorios documentados. Los fallos de permiso, las propuestas no válidas y las revisiones caducadas requieren corrección. Defina el último momento de ejecución segura para un cambio en la emisión; un comando que se ejecute con éxito fuera de plazo puede seguir siendo erróneo desde el punto de vista operativo.

Detener los reintentos no cancela un trabajo aceptado. La cancelación requiere su propio estado y sus propias reglas de gestión de conflictos. Cuando el resultado siga siendo desconocido, mantenga ese estado y remita la operación a un ingeniero, en lugar de inventar un éxito o un fallo.

Compruebe el resultado antes de finalizar la tarea

202 Accepted confirma la aceptación para su procesamiento. Realice un seguimiento por separado de la aceptación, la configuración aplicada y la salida observada, incluyendo los estados de fallo y caducidad. Una lista de reproducción guardada no garantiza que el programa previsto haya llegado a la salida. Especifique el acuse de recibo y la observación con marca de tiempo necesarios para cada etapa.

Registre la identidad de quien ejecuta la acción, la referencia de aprobación, la huella digital de la solicitud, las revisiones de la programación y las transiciones de tareas sin registrar información confidencial. Pruebe solicitudes duplicadas simultáneas, cargas útiles modificadas, aprobaciones caducadas, fallos tras la aceptación y respuestas perdidas tras la aplicación. Compruebe que un agente no pueda eludir dichos controles a través de otro punto de conexión.

Las API de radiodifusión para agentes de IA necesitan estos contratos siempre que una decisión propuesta se traduzca en una modificación en un canal. Comience con un flujo de trabajo delimitado, analice sus rutas de fallo y acuerde quién se encarga de los resultados inciertos. Explore Evrideo Broadcast o hable con nuestro equipo sobre los flujos de trabajo que su canal necesita soportar.