Diseño seguro de acciones de agentes OpenAPI

Un documento OpenAPI puede indicar a un agente cómo llamar a un endpoint. Por sí solo, no puede decirle qué significa una llamada, cuándo debe intervenir una persona ni cómo comportarse después de un fallo ambiguo. Tratar cada operación documentada como una acción para agentes produce herramientas que parecen completas en una demostración y se vuelven peligrosas en el uso cotidiano.

Una acción útil es más pequeña que un endpoint. Tiene un propósito limitado, entradas que el agente puede justificar, un resultado sobre el que puede actuar, una decisión de aprobación vinculada a las consecuencias y un plan explícito para los fallos. Haz ese trabajo de diseño antes de conectar una operación a un agente. Adaptarlo después del primer cobro duplicado, cambio accidental en producción o token filtrado es una forma terrible de aprender la lección.

Una operación todavía no es una acción para agentes

Un endpoint, una operación de OpenAPI y una acción para agentes responden a preguntas distintas. Se suelen confundir porque una operación de OpenAPI ofrece un punto de partida práctico, pero las diferencias determinan si la automatización sigue siendo comprensible.

Un endpoint es una dirección como /v1/deployments. Una operación añade un método HTTP, así que POST /v1/deployments es diferente de GET /v1/deployments. Una acción para agentes añade el contrato humano y operativo: qué objetivo persigue, qué argumentos acepta, qué efectos puede producir, qué pruebas cuentan como éxito y quién debe dar su consentimiento.

La especificación OpenAPI define un Operation Object con campos como operationId, parameters, requestBody, responses y security. Usa esos campos como indicios, no como una lista automática de publicación. Una operación con un esquema perfectamente definido puede seguir siendo una pésima acción para agentes si su descripción oculta un efecto en producción detrás de un nombre inofensivo.

Considera estas dos operaciones:

GET  /v1/projects/{project_id}/builds/{build_id}
POST /v1/projects/{project_id}/builds/{build_id}/promote

La primera recupera un registro. La segunda podría cambiar el tráfico, publicar artefactos o modificar un canal de lanzamiento. La ruta solo da una pista de esa diferencia. El diseño de la acción debe expresarla con claridad.

He visto equipos exponer una herramienta genérica request porque su API ya tenía un archivo OpenAPI limpio. El agente podía entonces construir rutas, cadenas de consulta y cuerpos arbitrarios. Eso no es un catálogo de acciones. Es ejecución remota de código contra una API empresarial, con mejor puntuación.

No expongas una operación hasta que puedas escribir una frase con este formato: «Esta acción [hace algo concreto] sobre [un objeto limitado] y devuelve [pruebas del estado resultante]». Si no puedes escribirla sin verbos vagos como «gestionar», «procesar» o «manejar», la acción sigue siendo demasiado amplia.

Empieza por las consecuencias, no por el esquema de solicitud

La aprobación debe depender de las consecuencias de una llamada, no de su verbo HTTP ni de la aparente sencillez de su cuerpo JSON. Un POST pequeño puede crear una obligación irreversible. Un GET detallado puede revelar datos privados. Un DELETE quizá solo elimine un borrador desechable, mientras que un PATCH puede revocar el acceso de todos los demás.

Antes de revisar los campos, describe el efecto con términos que reconocería la persona responsable del sistema. Pregunta qué cambia si el servidor ejecuta la llamada dos veces, la ejecuta para el objeto equivocado o la ejecuta cinco minutos más tarde de lo previsto por el agente. Estas preguntas separan la recuperación rutinaria de una acción que necesita revisión.

Uso cuatro clases de consecuencias al revisar una operación candidata:

• Observación: obtiene información limitada y no produce cambios en el servidor.
• Cambio reversible: crea, actualiza o elimina algo con una forma práctica y documentada de deshacerlo.
• Compromiso externo: envía un mensaje, inicia un trabajo de pago, publica material o cambia un estado visible para el cliente.
• Cambio irreversible o amplio: elimina registros permanentemente, rota accesos, modifica permisos o afecta a muchos objetos.

Estas clases no son un modelo de permisos. Obligan a describir las cosas con honestidad. Una operación «crear factura» pertenece al compromiso externo aunque la solicitud tenga solo dos campos. Una operación «reiniciar entorno» puede convertirse en un cambio amplio cuando un entorno contiene muchos servicios.

No deduzcas la seguridad a partir del nombre del método. HTTP define GET como seguro en el sentido del protocolo, lo que significa que el cliente no debería solicitar cambios de estado mediante él. Es una convención, no una prueba de que un servidor concreto la respete. He encontrado endpoints de diagnóstico que actualizaban cachés, iniciaban la generación de informes y consumían capacidad escasa cuando se llamaban repetidamente. Prueba el comportamiento real, no el que sugiere el verbo.

También debes separar el efecto de una acción de la sensibilidad de su resultado. Obtener un token de acceso puede ser una operación de solo lectura, pero devolver ese valor a un agente anula el sentido de controlar la llamada. Obtener un registro privado de cliente puede requerir aprobación aunque la API no cambie ni un byte.

Una buena ficha de acción registra ambas dimensiones con lenguaje claro:

Action: promote_preview_build
Effect: Changes one named preview build into the staging release channel.
Scope: One project and one build ID.
Result: Release ID, resulting channel, and server timestamp.
Human consent: Required for every call.
Retry: Never retry automatically unless the server accepts the same idempotency token.

Esa ficha suele revelar carencias semánticas de la API antes de que el agente escriba una sola línea de código. Si nadie puede decir si un reintento es seguro, la acción no está lista.

Las entradas necesitan límites que el agente no pueda esquivar hablando

Una acción para agentes necesita un contrato de entrada más pequeño que el que suele aceptar el endpoint. Los esquemas de OpenAPI definen tipos y estructura, pero un agente también necesita restricciones que le impidan ampliar una tarea mediante argumentos creativos.

Piensa en una operación de creación de despliegues. La API sin filtrar puede admitir muchas opciones para clientes internos: entorno, referencia del artefacto, región, número de réplicas, variables de entorno, interruptores de funcionalidades, etiquetas y un objeto de configuración libre. Entregar todos esos campos a un agente convierte una solicitud sencilla en una superficie de administración sin revisar.

Crea una acción con entradas que correspondan a la tarea. Si la tarea es «despliega la compilación que superó las pruebas en un entorno de vista previa», quizá el agente solo necesite project_id, build_id y un reason breve. El ejecutor puede seleccionar el entorno permitido y rechazar cualquier cosa fuera del alcance de la acción.

Esta forma de solicitud hace concreto el límite:

{
  "project_id": "proj_4821",
  "build_id": "build_9017",
  "reason": "Preview requested after integration tests passed"
}

No añadas target_url, headers arbitrarios, un cuerpo de solicitud sin procesar ni un objeto general options solo porque el endpoint subyacente los admita. Cada vía de escape convierte de nuevo tu acción cuidadosamente nombrada en un cliente genérico.

Usa los campos de OpenAPI que ya ofrecen límites útiles. Define additionalProperties: false cuando un objeto solo deba aceptar campos concretos. Usa enum para un conjunto realmente pequeño de valores permitidos. Define restricciones de longitud y patrones cuando los identificadores tengan un formato establecido. Marca como obligatorios los campos que el ejecutor no pueda inferir con seguridad.

Por ejemplo, este fragmento rechaza campos de configuración no revisados y hace visible el alcance previsto en el esquema:

DeployPreviewRequest:
  type: object
  additionalProperties: false
  required:
    - project_id
    - build_id
    - reason
  properties:
    project_id:
      type: string
      pattern: '^proj_[A-Za-z0-9]+$'
    build_id:
      type: string
      pattern: '^build_[A-Za-z0-9]+$'
    reason:
      type: string
      minLength: 8
      maxLength: 240

additionalProperties: false evita un fallo habitual: el agente aprende de otro ejemplo de API que puede enviar environment_variables, coloca secretos o sobrescrituras inseguras dentro de ese campo y el servidor los acepta silenciosamente. Rechazar el campo ofrece al agente un error útil en lugar de un despliegue inesperado.

Los esquemas no sustituyen la autorización a nivel de objeto. Un project_id válido todavía puede apuntar a un proyecto fuera de la tarea. El ejecutor debe comprobar que el objeto solicitado pertenece a la cuenta, espacio de trabajo, repositorio o entorno permitido. Coloca esa comprobación cerca del ejecutor de la acción, donde no dependa de la explicación del agente.

El texto libre necesita un tratamiento especial. Un campo reason puede ayudar a un revisor, pero nunca debe convertirse en un canal de instrucciones para el ejecutor. Guárdalo como anotación de auditoría. No lo analices en busca de comandos, selectores de recursos o excepciones de permisos.

Los resultados previstos deben ayudar a tomar la siguiente decisión

Un agente necesita un resultado sobre el que pueda razonar, no una respuesta HTTP sin filtrar volcada en el contexto. Devolver todos los encabezados, campos de depuración y objetos anidados aumenta la confusión y puede revelar datos que el agente no necesitaba para completar la tarea.

Define el éxito en términos de negocio antes de elegir los códigos de respuesta. Para una acción de despliegue, un resultado útil identifica el despliegue, su estado y el lugar donde el servidor informará del progreso posterior. Para actualizar un registro, identifica el registro y confirma los campos modificados. Para una eliminación, confirma el objetivo e indica si aún es posible recuperarlo.

Un resultado compacto para una operación asíncrona podría ser:

{
  "status": "accepted",
  "deployment_id": "dep_2388",
  "project_id": "proj_4821",
  "build_id": "build_9017",
  "target": "preview",
  "operation_status": "queued"
}

Esa respuesta expresa algo preciso: el servidor aceptó el trabajo, pero el despliegue todavía no ha terminado. El agente no debería informar de que «se ha desplegado» después de recibirla. Debe usar una acción de estado separada y de solo lectura, o decir al usuario que la operación está en cola.

Aquí es donde muchos documentos OpenAPI confunden a los agentes. Una respuesta 202 Accepted tiene un significado concreto: el servidor aceptó la solicitud para procesarla, pero el procesamiento puede no haber empezado ni terminado. Tratar 202 como un éxito equivalente a un 200 completado genera afirmaciones falsas en los registros y en los mensajes a los usuarios.

Separa el resultado del transporte del resultado de la acción. Un HTTP 200 puede envolver un fallo de dominio como {"state":"rejected","reason":"build is not eligible"}. A la inversa, 409 Conflict puede indicar al agente que el estado deseado ya existe. El contenedor de la acción debería convertir estos casos en un conjunto reducido de estados explícitos, como completed, pending, already_in_desired_state, rejected y unknown.

Evita prometer una uniformidad falsa. Algunas API solo devuelven un identificador de trabajo opaco, y eso está bien si expones una acción de estado que pueda resolverlo. El error está en ocultar la diferencia. Indica exactamente qué establece la primera llamada y qué no establece.

Filtra los detalles de error antes de devolverlos al agente. Un error del servidor puede incluir URL internas, encabezados de autorización, trazas de pila o datos de otro usuario. El agente necesita un motivo sobre el que pueda actuar, como «el build ID no pertenece al project ID», además de un identificador de correlación seguro para que una persona investigue. No necesita la página de excepciones del sistema ascendente.

La aprobación debe producirse en el punto del compromiso

Pide aprobación cuando la llamada pueda crear un compromiso importante y haz que la pantalla de aprobación describa el objeto y el efecto. Pedir una vez permiso para un conjunto impreciso de poderes futuros enseña a las personas a pulsar una advertencia que no pueden evaluar.

La aprobación de sesión y la aprobación de llamada resuelven problemas distintos. La aprobación de sesión dice: «Reconozco este proceso de agente y le permito usar este conjunto de acciones mientras se ejecuta». La aprobación de llamada dice: «Apruebo ahora esta solicitud concreta con consecuencias». No sustituyas una por la otra.

Un agente que puede consultar el estado de una compilación puede ejecutarse durante una hora sin molestar a nadie. Un agente que promociona una compilación debería mostrar el proyecto, el build ID, el canal de lanzamiento y el motivo cuando solicita consentimiento. Un revisor puede juzgar esa solicitud. «Permitir herramienta de despliegue» no le da casi ningún dato para decidir.

No uses un aviso de aprobación como sustituto de la validación de entradas. Si una acción permite al agente especificar un destino arbitrario o un alcance de permisos arbitrario, el revisor tendrá que descifrar una carga grande e inestable bajo presión. Limita primero las entradas. Después, la aprobación confirma una acción acotada.

La frecuencia adecuada depende del efecto. Exige aprobación en cada llamada para acciones que publiquen, modifiquen accesos, inicien un pago externo o afecten a un alcance amplio de producción. El consentimiento de sesión puede servir para un grupo de llamadas de solo lectura o cambios reversibles limitados, pero solo después de que la identidad del proceso y el catálogo de acciones sean visibles para el revisor.

Sallyport aplica esta distinción con autorización de sesión para un proceso de agente detectado por primera vez y aprobación opcional en cada uso de una credencial concreta. Su bloqueo de bóveda también rechaza todas las acciones mientras está bloqueada, de modo que la aprobación no puede convertir un almacén de secretos bloqueado en una excepción accidental.

No hagas que una persona apruebe fallos que el software puede evitar. Si una compilación no puede promocionarse, el ejecutor debe rechazarla antes de solicitar aprobación. Los avisos son para decisiones legítimas, no para pedir a un revisor cansado que detecte un estado mal formado.

Un tiempo de espera crea un estado desconocido, no una instrucción de reintento

Un tiempo de espera de red después de una solicitud que modifica datos es el camino de error que deja al descubierto un diseño descuidado de las acciones para agentes. El agente envió la solicitud y después perdió la respuesta. El servidor puede no haber hecho nada, haber completado el cambio o seguir procesándolo. El agente no puede descubrir la verdad suponiendo la respuesta que prefiere.

Repasa un fallo conocido. Un agente llama a POST /v1/invoices con el cliente, el importe y un tiempo de espera. La conexión se interrumpe después de que el servidor cree la factura, pero antes de que llegue la respuesta. El agente ve un tiempo de espera, reintenta con los mismos datos y el servidor crea una segunda factura. El registro de auditoría dice que el agente siguió su política de reintentos, lo cual es técnicamente cierto y operativamente inútil.

Un token de idempotencia solo resuelve esto cuando el servidor lo implementa de verdad. El cliente genera un token una vez por cada acción prevista, lo envía con la solicitud inicial y usa exactamente el mismo token al reintentar. El servidor debe vincular ese token con la solicitud original y devolver el resultado original, o un conflicto compatible, en lugar de repetir el efecto.

Idempotency-Key: act_01HZX7FQ2Z9K8M6R4T3V1W0Y

El contenedor de la acción debe mantener este token fuera de la improvisación del agente. Genéralo durante la ejecución, persístelo con el intento de acción y reutilízalo solo para ese intento. Un token proporcionado por el agente puede colisionar, reutilizarse en solicitudes no relacionadas o convertirse en otra superficie de inyección de instrucciones.

Si la API carece de semántica de idempotencia documentada, no reintentes automáticamente una operación que modifique datos después de un tiempo de espera. Devuelve unknown con el identificador de la acción y ofrece una acción de consulta de solo lectura que pueda inspeccionar el estado del servidor. Si no existe ninguna consulta, una persona debe investigar antes de repetir la solicitud. Esa respuesta parece incómoda porque lo es. Fingir certeza no la mejora.

OpenAPI puede documentar un parámetro de encabezado llamado Idempotency-Key, pero la documentación por sí sola no garantiza el comportamiento del servidor. Pruébalo de forma deliberada: envía dos veces el mismo token y la misma carga, y después envía el mismo token con una carga modificada. El servidor debería hacer converger el primer par y rechazar o gestionar claramente la solicitud modificada. Si realiza ambos cambios sin avisar, el encabezado es decorativo.

Los demás fallos necesitan sus propias reglas. Trata 401 y 403 como condiciones de parada, no como una señal para buscar otra credencial. Trata 429 como una condición de espera solo cuando la API comunique un retraso de reintento o tu acción tenga una política de espera limitada. Trata los errores de validación como información útil para el agente solo cuando el error indique una corrección permitida.

La autenticación no concede criterio a un agente

Una declaración security de OpenAPI describe cómo un cliente demuestra su identidad ante una API. No expresa si un agente debería invocar la operación, si puede usar una credencial concreta para un objeto concreto ni si una persona debe revisar el efecto.

El Security Requirement Object de la especificación asocia una operación con esquemas de seguridad con nombre. Un esquema bearer puede indicar a un cliente que envíe un encabezado de autorización. La autenticación básica puede indicarle que construya un encabezado de credenciales. Eso es autenticación de transporte. No leas más de lo que dice.

Mantén separadas estas cuatro preguntas:

• ¿Quién o qué llama a esta acción?
• ¿Qué credencial usa el ejecutor con la API ascendente?
• ¿Qué objetos y efectos permite esa credencial?
• ¿Qué intentos de acción aprueba una persona?

Cuando los equipos mezclan estas preguntas, suelen entregar un token al agente y llamar a eso autorización. Después el token aparece en la salida de la herramienta, el historial del shell, los registros de depuración, las instrucciones o un archivo de configuración. Revocarlo se convierte en un proyecto de limpieza en lugar de una sola acción.

La forma más segura mantiene la credencial en el ejecutor. El agente proporciona entradas de acción limitadas. El ejecutor selecciona una credencial válida, la inyecta en la solicitud HTTP, evalúa la respuesta y devuelve el resultado filtrado. El agente nunca necesita acceso al texto plano de una clave de API para solicitar una acción.

Para SSH se aplica la misma regla. Un agente puede necesitar solicitar un comando contra un host concreto, pero un comando genérico junto con una clave privada de confianza amplia ofrece mucha más autoridad de la que requieren la mayoría de las tareas. Restringe la identidad del host, la cuenta, la forma del comando y el tratamiento de la salida según el propósito de la acción.

Sallyport utiliza este modelo de ejecución para llamadas HTTP y comandos SSH: las credenciales permanecen en su bóveda cifrada y el agente recibe el resultado de la acción, no el secreto. El diseño solo ayuda si sigues exponiendo acciones limitadas y eliges aprobaciones acordes con sus efectos.

La descripción de la acción debe decir lo que el esquema no puede

Las descripciones de OpenAPI importan porque los agentes las leen como instrucciones, pero la prosa debe aclarar los límites, no introducir de forma encubierta un segundo contrato de API contradictorio. Coloca los límites aplicables en los esquemas y ejecutores. Usa las descripciones para explicar la intención, las consecuencias y las condiciones que un sistema de tipos no puede expresar.

Nombra las operaciones según el resultado que busca el usuario. getBuildStatus dice más que getBuildById; createPreviewDeployment dice más que postDeployment. El nombre no debe prometer demasiado. Si el servidor pone el trabajo en cola, no llames a la operación deployBuild a menos que el resultado distinga la aceptación de la finalización.

Escribe las descripciones con los detalles que, de otro modo, el agente tendría que adivinar:

operationId: createPreviewDeployment
summary: Queue one tested build for the preview environment
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/DeployPreviewRequest'
responses:
  '202':
    description: Request accepted. Deployment work may still be pending.
  '409':
    description: The build already has a preview deployment or cannot enter preview.

Un resumen no basta para operaciones con consecuencias mayores. Registra el objetivo previsto, la clase de efecto, la exigencia de aprobación, la regla de reintento y los estados del resultado en metadatos de acción junto al documento OpenAPI. Puedes usar extensiones x- si tus herramientas las controlan, pero etiquétalas claramente como convenciones privadas. Los analizadores estándar de OpenAPI ignorarán las extensiones desconocidas, así que el ejecutor debe hacerlas cumplir y no limitarse a mostrarlas.

No dependas de una descripción que diga «usar con precaución». La precaución es una sensación humana, no una regla ejecutable. Sustitúyela por un límite: un proyecto, solo vista previa, sin variables de entorno arbitrarias, aprobación en cada invocación y ningún reintento automático después de un resultado desconocido.

Las descripciones también deben indicar al agente cuándo rechazar la acción. Una operación de promoción puede exigir una ejecución de pruebas completada. Una exportación de datos puede requerir una referencia de caso proporcionada por el cliente. Una eliminación puede requerir una consulta previa que confirme que el objeto es un borrador. Estas condiciones previas reducen avisos innecesarios y facilitan la interpretación de los registros de auditoría.

Prueba la acción con un operador descuidado pero capaz

Una prueba del camino feliz solo demuestra que la API funciona cuando se cumplen todas las suposiciones. Prueba la acción como si un operador rápido y competente tuviera información incompleta, identificadores antiguos y tendencia a repetir una operación después de un error. Eso se parece lo suficiente a la forma en que fallan los agentes autónomos como para resultar útil.

Crea un pequeño entorno de prueba con objetos desechables y una cuenta cuyos permisos coincidan con los del ejecutor previsto. Después ejecuta la acción en casos que pongan a prueba sus límites:

• Envía un campo de entrada desconocido y confirma que el ejecutor lo rechaza.
• Solicita un objeto fuera del proyecto o espacio de trabajo permitido.
• Deniega la aprobación y confirma que no se produce ninguna solicitud ascendente.
• Fuerza un tiempo de espera después de que el servidor reciba una solicitud que modifica datos.
• Devuelve una respuesta con material de depuración sensible y confirma que el filtrado lo elimina.

Inspecciona algo más que el estado final de la API. Revisa el aviso que ve la persona, la solicitud exacta que hizo el ejecutor, el resultado que recibió el agente y el registro de auditoría. Una solicitud correcta puede incumplir el contrato de la acción si el aviso ocultaba el objetivo, el resultado afirmaba demasiado pronto que todo había terminado o el registro no puede distinguir una solicitud denegada de un rechazo del sistema ascendente.

Para una acción que exige aprobación en cada llamada, prueba el orden. El ejecutor debe validar las restricciones estáticas y resolver suficiente contexto seguro para mostrar una solicitud significativa antes de pedir consentimiento. No debe enviar primero la solicitud y pedir aprobación después. También debe evitar una larga cadena de llamadas de lectura ocultas que exponga más datos de los que necesita la acción final.

Prueba de forma deliberada las credenciales revocadas y caducadas. El ejecutor debe fallar de forma segura, devolver una explicación adecuada y evitar llamadas repetidas con la misma credencial inutilizable. Un bucle de reintentos contra una credencial rechazada puede llenar los registros, activar límites de velocidad y dificultar el diagnóstico de un problema de acceso sencillo.

Por último, prueba la cancelación. Si un usuario detiene el agente mientras se ejecuta un trabajo ascendente, el registro debe indicar si la solicitud nunca salió, llegó al servidor o entró en un estado desconocido. Cancelar el proceso local del agente no cancela necesariamente un efecto remoto.

Publica menos acciones y haz que cada una pueda defenderse

Un catálogo pequeño de acciones supera a un cliente de API genérico porque cada acción puede incluir un contrato razonado. Añadir operaciones es fácil. Mantener la veracidad de la semántica de los resultados, los límites de los objetos, los avisos de aprobación y el comportamiento ante fallos es donde está el trabajo.

Empieza con una operación que recupere un registro de estado limitado. Dale un nombre que indique el objeto, restringe los identificadores al alcance previsto y devuelve solo los campos que el agente necesite. Después añade una acción reversible y obliga a escribir sus reglas de reintento y aprobación antes de implementarla.

No conviertas una operación en una acción para agentes solo porque un generador de OpenAPI pueda exponerla en una tarde. Hazlo cuando puedas explicar qué ocurre después de un tiempo de espera, qué aprueba la persona, qué ve el agente y cómo demostrarás más tarde qué solicitud tuvo lugar. Si alguna respuesta depende de que «el agente probablemente haga lo sensato», deja el endpoint fuera del catálogo.