# Pruebas de acceso de un agente a una API antes de un lanzamiento en producción Un agente se gana el acceso a una API de producción cuando se comporta correctamente si la solicitud se rechaza, está mal formada, tarda demasiado o es peligrosa. No se lo gana al producir una única respuesta correcta en un entorno aislado. Una demostración amable oculta los fallos que importan: una aprobación dirigida al proceso equivocado, un token copiado en la transcripción del agente, un bucle de reintentos que golpea el límite de frecuencia o un registro que no puede explicar quién aprobó una llamada destructiva. Prueba todo el recorrido de la acción contra un destino que no sea de producción antes de entregar al agente una capacidad de producción. Ese recorrido incluye la solicitud del agente, la autorización, la inyección de credenciales, la respuesta de la API remota, la interpretación que hace el agente del fallo y un registro de cada llamada que sobreviva a la sesión. Si falta una parte, has probado un cliente de API, no un actor autónomo. ## Un endpoint de pruebas debe estar separado de las formas que realmente importan Un endpoint de pruebas útil tiene credenciales y datos separados, además de un límite de daños que puedas explicar en una sola frase. Llamar a un host de producción con un parámetro que supuestamente activa el modo de prueba no cumple ese criterio si el mismo token todavía puede leer registros de clientes o gastar dinero. Usa el sandbox de un proveedor cuando te ofrezca una cuenta aislada y credenciales de prueba. Usa un tenant exclusivo cuando el servicio no tenga sandbox. Si no existe ninguna de las dos opciones, coloca un servicio pequeño bajo tu control detrás de otro host y aliméntalo con datos desechables. El objetivo no es una etiqueta como staging. El objetivo es que una solicitud equivocada no pueda afectar a usuarios, saldos ni secretos de producción. Haz que el endpoint demuestre que no es de producción. Devuelve un campo de entorno evidente en cada respuesta exitosa y haz que las rutas destructivas solo escriban en un libro mayor de pruebas. Una respuesta como esta evita que un operador confunda una prueba correcta con un cambio en producción: ```json { "environment": "test", "request_id": "req_7f1a", "status": "accepted", "resource_id": "demo-order-184" } ``` Mantén los datos de prueba lo bastante realistas para ejercitar la paginación, los campos ausentes, los permisos y los conflictos. Un único registro perfecto enseña malos hábitos al agente. Crea algunos registros que pueda leer, uno que pueda actualizar y otro al que nunca deba acceder. No necesitas un conjunto enorme de datos de prueba. Necesitas suficiente variedad para detectar código que da por hecho que todas las respuestas están completas y limpias. No reutilices un token bearer de producción en un entorno de pruebas por comodidad. He visto equipos llamarlo un atajo temporal y dejarlo después porque cada tarea siguiente parecía más urgente. Una identidad de prueba debe tener nombre, responsable, fecha de caducidad y permisos que correspondan a los casos concretos. Si nadie puede explicar qué prueba necesita un permiso, elimínalo. ## La primera ejecución debe probar el límite de autorización, no la API Antes de validar el comportamiento de negocio, demuestra que un proceso de agente no reconocido no puede actuar en silencio. Inicia un proceso nuevo y haz que intente una lectura inocua contra el endpoint de pruebas. El resultado esperado es un evento de autorización antes de que salga la solicitud a la API. Esto detecta una diferencia que los equipos suelen confundir: la aprobación del usuario no equivale a la aprobación del proceso. Un operador puede confiar en su propia terminal y desconfiar de un plugin, un script copiado o un agente iniciado por otra aplicación. La interfaz de aprobación debe indicar qué autoridad ejecutable solicita actuar. Un botón que diga «Permitir» sin ese contexto pide a la gente que dé su visto bueno a un proceso desconocido. Para esta prueba, registra cuatro observaciones: - El proceso nuevo recibe una solicitud de aprobación antes de la llamada externa. - La aprobación identifica el proceso de una forma que el operador puede reconocer. - La aprobación dura solo durante la ejecución prevista, no para todos los procesos futuros. - Al terminar el proceso, desaparece la autorización de la sesión. Rechaza la solicitud una vez antes de aprobarla. El rechazo debe dejar al agente una señal de fallo utilizable, no un éxito inventado. Las instrucciones correctas para un agente indican qué hacer tras una negativa: detener la operación, informar de que la aprobación fue denegada y no buscar otra ruta hacia el mismo endpoint. Después reinicia el agente y repite la lectura inocua. Si el segundo proceso hereda el permiso del primero, averigua por qué. La autorización almacenada en caché puede parecer eficiente en una demostración y convertirse en una concesión silenciosa de permisos cuando un agente se reinicia después de una actualización o cuando otro lanzador ejecuta el mismo comando. La aprobación de sesión de Sallyport está activada de forma predeterminada y muestra la autoridad de firma de código del proceso en la primera llamada de un proceso de agente nuevo. Ese es el momento adecuado para probar el criterio humano, antes de que una solicitud con credenciales llegue al servicio externo. ## La inyección de credenciales debe demostrar que el agente nunca tuvo el secreto La inyección de credenciales solo funciona cuando el agente puede solicitar una acción sin poder recuperar la credencial utilizada. Ocultar un token en la salida de la consola no es protección. Si el token entró en una variable de entorno, una respuesta de herramienta, un prompt, el historial del shell o un archivo local, estuvo disponible para el agente aunque nadie llegara a mostrarlo. Configura una credencial de prueba que el servicio remoto pueda identificar sin revelar su valor. Muchas API ofrecen una etiqueta de token, un identificador de cliente o un campo de auditoría. Si la tuya no lo ofrece, crea una ruta de prueba que devuelva la identidad de la credencial que vio, no la credencial misma. El resultado debe demostrar qué identidad de prueba autenticó la llamada. Para una API con token bearer, la solicitud a nivel de red suele tener esta forma: ```http GET /v1/test/projects/demo HTTP/1.1 Host: api.test.example Authorization: Bearer [injected outside the agent] Accept: application/json ``` El texto entre corchetes es documentación, no un valor que el agente deba completar. El agente debe proporcionar el método, el destino y los argumentos de solicitud permitidos. El gestor de credenciales añade el encabezado de autorización solo después de la decisión de aprobación. La autenticación básica y los esquemas de encabezados personalizados necesitan la misma prueba, porque fallan en lugares distintos cuando la configuración es incorrecta. Inspecciona la transcripción del agente, el historial de solicitudes de herramientas, el entorno del shell expuesto al agente y los archivos creados durante la ejecución. Busca tanto el material literal del token como filtraciones indirectas, por ejemplo un objeto de solicitud con un encabezado de autorización. Ocultar los datos después no arregla un diseño que entregó el secreto al proceso. Después rota la credencial de prueba y ejecuta la misma solicitud. Una segunda ejecución exitosa demuestra que el recorrido de la acción lee la credencial almacenada actual, en lugar de un valor antiguo incluido en la configuración del agente. Una ejecución fallida también puede ser útil si el error indica un fallo de autenticación sin imprimir el secreto rechazado. No pruebes con un token que pueda hacer más de lo que exige el escenario. Las credenciales de solo lectura bastan para demostrar la inyección. Añade después un permiso de escritura limitado y reversible para las pruebas de modificación. La persona que revise la prueba nunca debería necesitar acceso al token sin ocultar para decidir si se superó. ## La fricción de aprobación debe corresponder al daño de la llamada La aprobación de sesión y la aprobación para cada uso resuelven problemas distintos. La aprobación de sesión establece que una ejecución concreta del agente puede usar una capacidad limitada. La aprobación para cada uso obliga a una persona a revisar cada solicitud hecha con una credencial sensible. Tratarlas como sustitutas produce una avalancha de avisos inútiles o una vía sin supervisión hacia errores costosos. Usa una credencial de bajo riesgo para probar el límite de la sesión. Exige aprobación por uso para una credencial que pueda crear, borrar, transferir, publicar o modificar accesos. Pide al agente que haga dos llamadas de prueba distintas con esa credencial. Debes ver dos decisiones, y la segunda solicitud no debe aprovechar la aprobación concedida para la primera. La prueba debe incluir un rechazo. Aprueba la primera acción y rechaza la segunda. Confirma estos hechos en el informe del agente y en el registro de acciones: 1. La primera acción llegó al servicio de pruebas y devolvió su identificador de solicitud. 2. La acción rechazada nunca llegó al servicio de pruebas. 3. El agente no afirmó que hubiera realizado el cambio. 4. La sesión siguió disponible para operaciones que no necesitaban la credencial rechazada. Ese cuarto punto detecta un fallo especialmente desagradable. Algunas integraciones tratan una solicitud sensible rechazada como motivo para terminar todas las operaciones posteriores. Otras ignoran el rechazo y reintentan hasta que alguien aprueba por accidente. Ambos comportamientos dificultan el control humano más de lo necesario. La fatiga por aprobaciones es un fallo de diseño, pero eliminar la aprobación no suele ser la solución. Redúcela agrupando el trabajo en una sesión breve, reduciendo el número de llamadas sensibles o dando al agente una operación masiva más segura. No resuelvas los avisos excesivos concediendo un token permanente y amplio a un proceso cuyo plan puede cambiar a mitad de la tarea. ## Los códigos de estado HTTP deben guiar el comportamiento del agente Un agente necesita un comportamiento explícito para cada clase de fallo, porque el éxito HTTP y el éxito de la tarea no son lo mismo. RFC 9110 define el significado de los códigos de estado HTTP. Entre otras cosas, una respuesta 401 indica que faltan credenciales de autenticación o que no son válidas, mientras que una respuesta 403 significa que el servidor entendió la solicitud, pero se niega a cumplirla. Trata esas respuestas de forma distinta. Normalmente, reintentar cualquiera de las dos con la misma solicitud solo añade ruido. Crea una tabla de fallos antes del lanzamiento y ejercita cada fila contra el endpoint de pruebas. Mantén las acciones requeridas lo bastante acotadas para que una persona pueda comprobar si el agente las siguió. | Respuesta de prueba | Acción del agente | Qué debe mostrar el registro | | --- | --- | --- | | 401, fallo de autenticación | Detenerse e informar de un problema de credenciales | Destino, estado, referencia de credencial, ningún secreto | | 403, fallo de autorización | Detenerse e informar de permisos insuficientes | Destino, método, estado, operación intentada | | 404, recurso inexistente | Preguntar si el identificador del recurso es incorrecto | Identificador proporcionado y estado | | 409, conflicto | Leer el estado actual antes de proponer otra escritura | Identificador del recurso, estado, ningún reintento ciego | | 429, límite de frecuencia | Esperar según las indicaciones del servidor o detenerse | Estado y tiempo de reintento, si se proporciona | | 500 o 503 | Reintentar solo dentro de un límite definido y después informar | Número de intentos, estado, resultado final | Una respuesta 400 merece más atención de la que suele recibir. A menudo revela una discrepancia entre el esquema de la herramienta del agente y el contrato real de la API remota. Haz que el servidor de pruebas devuelva errores de validación por campo y comprueba que el agente informe del argumento incorrecto sin inventar un valor de sustitución. Un agente que adivina campos puede convertir un error de validación inocuo en una solicitud contra la cuenta equivocada. Prueba el fallo de transporte por separado de un HTTP 503. Desconecta el servicio de pruebas o dirige una solicitud controlada a una dirección inalcanzable. El agente debe distinguir entre no recibir respuesta y recibir una respuesta del servidor. Esa diferencia importa cuando la operación pudo llegar al servicio, pero la respuesta se perdió. Reintentar una operación de creación después de un tiempo de espera ambiguo puede generar duplicados. Usa identificadores de idempotencia cuando la API los admita. Si no los admite, haz que el agente compruebe si ya existe un resultado antes de repetir una llamada que pueda modificar datos. Decir «reintenta tres veces» no es un plan de recuperación cuando cada intento puede cobrar una tarjeta, crear un usuario o enviar un mensaje. ## Un lanzamiento fallido suele empezar con un bucle de reintentos aparentemente inocuo Un fallo habitual comienza cuando se pide a un agente que cree un recurso de prueba y después lo verifique. La solicitud de creación tiene éxito en el servicio, pero una interrupción de red oculta la respuesta. El agente ve un error, repite la llamada de creación y recibe un segundo resultado exitoso. Después busca un recurso por un nombre supuesto e informa de que todo ha funcionado. El operador se queda con cambios duplicados y sin una explicación clara de qué solicitud causó cada uno. Puedes reproducirlo sin poner en riesgo producción. Haz que una ruta de prueba acepte una solicitud de creación, guarde el objeto de prueba y cierre deliberadamente la conexión antes de devolver la respuesta. Ejecuta el agente con un identificador de solicitud fijo. El comportamiento seguro esperado es consultar el servicio de pruebas por ese identificador antes de repetir la creación. Si el agente no puede hacerlo, debe detenerse e informar de un resultado ambiguo. Un contrato mínimo para el servicio de pruebas puede hacer concreta la comprobación: ```json POST /v1/test/jobs { "request_id": "rollout-042", "name": "reconcile-demo" } GET /v1/test/jobs?request_id=rollout-042 { "items": [ {"id": "job_128", "request_id": "rollout-042", "state": "queued"} ] } ``` Aquí también aparecen los prompts que piden al agente que siga intentándolo hasta que funcione. Esa instrucción parece razonable para quien observa a un operador humano. Es insegura para un actor que puede hacer llamadas más rápido de lo que nadie alcanza a notar. Sustitúyela por una regla de reintentos limitada, una comprobación de duplicados y una condición que exija revisión humana. OWASP API Security Top 10 señala el consumo ilimitado de recursos y la autorización defectuosa a nivel de objeto. Ambos problemas aparecen en los lanzamientos de agentes como errores de comportamiento corrientes: un bucle que ignora un límite y un agente que sustituye un identificador de objeto cercano cuando falla el solicitado. La prueba necesita un objeto prohibido y una ruta limitada por frecuencia, porque un conjunto de datos de prueba basado solo en el camino feliz nunca revelará ninguno de esos hábitos. ## Los registros deben explicar la decisión y el efecto externo Un registro de llamadas debe permitir reconstruir lo ocurrido sin reconstruir todo el razonamiento privado del agente. Guarda los hechos que establecen la autoridad y el efecto: qué sesión actuó, qué proceso solicitó la acción, qué destino y método utilizó, qué referencia de credencial se aplicó, si una persona lo aprobó, cuándo ocurrió y qué resultado devolvió. No incluyas cuerpos de solicitud sin filtrar en todos los registros por defecto. Algunos datos contienen información de clientes, tokens de terceros o contenido que el agente recibió instrucciones de procesar. Guarda un resumen seguro o campos seleccionados cuando eso cubra la necesidad de investigación. El identificador de solicitud del servicio remoto resulta especialmente útil porque conecta tu registro local con la propia pista de auditoría del servicio. Separa el registro de ejecución del registro de llamadas. El primero responde si un proceso concreto del agente tenía permiso para operar y si alguien lo revocó después. El segundo responde qué ocurrió en cada acción externa. Mezclarlos en una transcripción de chat elimina la estructura que necesitas cuando una ejecución hace muchas solicitudes. Sallyport proyecta los diarios de sesión y actividad desde un único registro de auditoría cifrado y encadenado mediante hash. Su comando `sp audit verify` puede comprobar esa cadena sin conexión sobre el texto cifrado y sin una clave de bóveda, lo que facilita probar la integridad de los registros por separado del acceso a los secretos. Ejecuta la verificación después de una prueba normal. Luego copia el archivo de auditoría cifrado a una ubicación de prueba y modifica algunos bytes en la copia. El comando debe informar de un fallo para la copia alterada, mientras que el original debe seguir verificándose. Hazlo únicamente con una copia desechable. El ejercicio enseña al equipo de revisión qué aspecto tiene un informe válido antes de necesitarlo durante una investigación de producción. La evidencia de manipulación no significa que todos los operadores puedan leer todos los detalles, ni sustituye los registros de la API remota. Responde a una pregunta más concreta: ¿se mantuvo intacta la secuencia local de registros? Conserva los identificadores de solicitud y las marcas de tiempo del endpoint de pruebas para que un investigador pueda comparar ambos lados. ## La revocación debe detener la siguiente llamada, no limitarse a cerrar una ventana Prueba la revocación mientras el agente siga ejecutándose. Aprueba una sesión, haz una solicitud inocua, revoca la sesión y pide al mismo proceso que haga otra solicitud inocua. La segunda solicitud debe fallar antes de llegar al endpoint que no es de producción. Si tiene éxito porque sobrevive una conexión existente o una credencial almacenada en caché, es un impedimento para producción. Después prueba la puerta de la bóveda por separado. Bloquea el almacén de credenciales e intenta de nuevo la solicitud. Una bóveda bloqueada debe denegar todas las acciones, incluida una solicitud que el operador aprobó antes para esa sesión. Es un control más fuerte que revocar una sola ejecución porque detiene todas las rutas de acción que dependen de la bóveda. Observa el endpoint durante ambas pruebas. No aceptes como prueba un mensaje del agente que diga que el acceso fue denegado. El registro de solicitudes del servidor debe demostrar que no llegó ninguna segunda solicitud. Esta sencilla comprobación cruzada detecta integraciones que informan de un fallo de aprobación después de haber enviado ya la solicitud HTTP. Si tu agente también puede trabajar con SSH además de hacer llamadas HTTP, repite la prueba contra un host desechable. Usa una cuenta sin privilegios y un comando con un resultado inequívoco, como crear un archivo en un directorio temporal. La revocación debe impedir un nuevo comando SSH igual que impide una solicitud de API. Una pasarela que trate ambos canales de forma distinta crea un punto ciego en el que los operadores creen que el control sigue existiendo. ## La promoción necesita un paquete de evidencias, no la confianza de una demostración Pasa a producción solo cuando una persona pueda revisar un registro compacto de pruebas y responder si el agente se mantuvo dentro de la autoridad prevista. El paquete debe contener la identidad y los permisos de prueba, el límite del endpoint, el comportamiento de aprobación esperado, resultados representativos de éxito y fallo, el resultado de la verificación de registros y el resultado observado de la revocación. No promociones todos los permisos de prueba junto con el agente. Crea por separado una credencial de producción y empieza con el conjunto mínimo de operaciones que permita la primera tarea real. Designa a un operador que pueda aprobar o revocar ejecuciones y deja por escrito qué estados de respuesta obligan al agente a detenerse. Si el equipo no puede nombrar a esa persona, ha delegado el control operativo en el azar. Ejecuta la primera tarea de producción con las aprobaciones activadas y revisa sus registros inmediatamente después. Compara el número real de solicitudes, los destinos y los resultados con la ejecución de prueba. Si el agente contacta con un endpoint no previsto, solicita una credencial más amplia o reintenta de otra manera con datos de producción, detén el lanzamiento y devuelve ese comportamiento al endpoint de pruebas. El primer lanzamiento correcto en producción debe ser deliberadamente aburrido. El agente hace pocas llamadas previstas, una persona puede detenerlo, la credencial nunca entra en su contexto y cada efecto externo tiene un registro que coincide con el identificador de solicitud del servicio. Esa es prueba suficiente para ampliar el alcance con cuidado. Una demostración pulida no lo es.