¿Deben las operaciones masivas de una API mostrar primero sus objetivos?

Un agente de IA nunca debe convertir una solicitud imprecisa como «archiva las cuentas inactivas» en una llamada de escritura sin límites. Antes de cambiar muchos registros, debe mostrar el conjunto exacto de objetivos, conservar la selección que mostró y exigir una confirmación que solo se aplique a esa selección.

Esto parece una complicación innecesaria hasta que un filtro incorrecto coincide con un cliente real, un tenant de pruebas o una cuenta con una excepción que nadie incluyó en el ticket. Una persona puede cometer el mismo error, pero un agente puede enviar la solicitud a velocidad de máquina y seguir después del primer resultado incorrecto. El control importante no es una advertencia amable antes de la solicitud. Es un límite que se pueda revisar entre decidir quién se verá afectado y cambiar sus datos.

Un recuento no describe el alcance de una operación

Un recuento indica cuántos registros afectará una operación. No indica cuáles. «482 suscripciones» puede sonar razonable aunque incluya un tenant empresarial, cuentas suspendidas que deben conservarse por motivos legales o registros de una región que la solicitud no mencionó.

Exige un manifiesto de objetivos. En una operación pequeña, puede enumerar todos los identificadores junto con suficiente contexto para que una persona detecte errores. En una operación grande, muestra la lista completa en una interfaz de revisión exportable, además de agrupaciones útiles por estado, tenant, región o propietario. No obligues a la persona a deducir la pertenencia basándose solo en una cadena de filtro.

Una vista previa útil responde cinco preguntas concretas:

• ¿Qué recurso y entorno de la API recibirán la escritura?
• ¿Qué selector produjo este conjunto?
• ¿Qué registros forman parte del conjunto, identificados mediante ID estables y campos comprensibles?
• ¿Qué modificación recibirá cada registro?
• ¿Qué registros quedaron excluidos por una regla explícita?

El último punto detecta un fallo incómodo: una solicitud puede ser técnicamente correcta y aun así incumplir la intención porque una excepción oculta nunca entró en el selector. Si la persona indica «todas las facturas impagadas excepto las impugnadas», la vista previa debe mostrar claramente la exclusión de las facturas impugnadas. El silencio deja a quien revisa intentando adivinar si el agente entendió la excepción o simplemente la olvidó.

No confundas una muestra con un manifiesto. Mostrar los primeros 20 registros de una actualización de 10.000 demuestra muy poco. Las muestras ayudan a detectar problemas evidentes, pero la selección almacenada debe incluir todos los registros que puedan cambiarse.

La vista previa y la confirmación deben vincularse a la misma selección

Una vista previa solo tiene sentido cuando la confirmación puede demostrar que actúa sobre el conjunto revisado. Si un agente muestra una búsqueda a las 14:00 y vuelve a ejecutarla a las 14:05 antes de escribir, puede afectar a una población diferente. Pueden entrar registros nuevos en el filtro, cambiar el estado de registros existentes o reordenarse las filas por la paginación.

El diseño de API más seguro crea una instantánea de selección en el servidor. El endpoint de vista previa devuelve un ID de selección, su caducidad, el recuento de miembros y una revisión o resumen. El endpoint de confirmación acepta ese ID y lo rechaza si la instantánea caducó o cambió.

POST /v1/subscriptions/selections
Content-Type: application/json

{
  "filter": {
    "status": "past_due",
    "region": "eu",
    "exclude_tags": ["disputed", "legal_hold"]
  },
  "fields": ["id", "customer_name", "status", "amount_due", "tags"]
}

Una respuesta adecuada podría tener esta forma:

{
  "selection_id": "sel_7f2c",
  "expires_at": "2025-03-08T15:00:00Z",
  "count": 482,
  "digest": "sha256:4c76...",
  "records": [
    {"id":"sub_104","customer_name":"Northwind Parts","status":"past_due","amount_due":3100,"tags":[]},
    {"id":"sub_219","customer_name":"Orchard Studio","status":"past_due","amount_due":450,"tags":[]}
  ]
}

El array records puede llegar mediante un cursor, pero el ID de selección debe referirse a la pertenencia completa y congelada, no solo a la página actual. La interfaz de revisión puede recorrer el resultado por páginas sin cambiar el objeto que se está revisando.

Después de la aprobación, el agente envía la selección guardada en lugar del filtro original:

POST /v1/subscriptions/bulk-actions
Content-Type: application/json
Idempotency-Key: 9b03c6f0-7dfa-4f22-b0e5-4b52ca4f1a51

{
  "selection_id": "sel_7f2c",
  "expected_digest": "sha256:4c76...",
  "action": {"type": "pause_collection", "reason": "approved credit hold review"}
}

El servidor debe rechazar un resumen que no coincida y devolver un conflicto. Una solicitud correcta debe devolver un ID de acción y ubicaciones de resultados por registro, no solo { "ok": true }. Un mensaje general de éxito oculta la finalización parcial, que es el modo normal de fallo en los trabajos masivos.

Si la API del proveedor no puede crear instantáneas, el agente aún puede vincular la operación guardando una lista ordenada de ID, calculando un hash de una representación canónica y enviando esa lista al endpoint de escritura. Esto tiene límites: restricciones de URL y cuerpo, registros obsoletos y APIs que solo aceptan un filtro. En esos casos, no finjas que el control es equivalente. Vuelve a mostrar la vista previa justo antes de cada lote acotado y detente si cambia la pertenencia.

La paginación estable determina si la revisión sirve de algo

La paginación por desplazamiento es una mala base para aprobar cambios sobre datos que siguen modificándose. Supón que el agente enumera la primera página, ve los registros del 1 al 100 y después otro proceso archiva 20 registros cerca del principio. Cuando el agente pide el desplazamiento 100, puede saltarse registros que se desplazaron hacia arriba. Las inserciones también pueden provocar duplicados. El recuento revisado puede mantenerse lo bastante parecido como para parecer normal, aunque cambien registros concretos.

Usa un cursor emitido por el servicio y pregunta al proveedor de la API si ese cursor lee desde una instantánea. Un cursor que solo codifica una posición de ordenación también puede desviarse si cambia el campo ordenado. Ordenar por un campo mutable como updated_at es especialmente problemático cuando la propia acción propuesta actualiza esa marca de tiempo.

Cuando controles la API, expón estas propiedades de forma explícita:

• Un identificador de instantánea o una marca de agua máxima inmutable.
• Una ordenación determinista basada en un identificador inmutable.
• Una caducidad que obligue a crear una vista previa nueva en lugar de devolver datos recientes en silencio.
• Un campo de respuesta que indique si quien llama está leyendo una instantánea coherente.

RFC 9110 clasifica métodos como POST, PUT, PATCH y DELETE como inseguros porque pueden cambiar el estado del servidor. Esa clasificación no es un diseño de flujo de trabajo, pero respalda una regla práctica: no trates un endpoint de listado seguido de un método inseguro como una única operación atómica solo porque el código coloca ambas llamadas juntas.

Para una API externa que no ofrezca cursores estables ni instantáneas de selección, reduce el alcance hasta que alguien pueda revisar cada solicitud. Es tentador solucionar la limitación con una caché del lado del agente y un bucle largo. Ese recurso suele crear una segunda base de datos sin límite transaccional ni respuesta autoritativa cuando un registro cambia a mitad de la ejecución.

La aprobación debe describir la modificación, no solo los registros

Quien revisa debe aprobar tanto la pertenencia como el efecto. «Aplicar cambios a 482 registros» no significa nada si la interfaz no indica si se van a eliminar, desactivar, reasignar, cobrar, publicar o modificar campos. Incluye el valor anterior y el valor propuesto de cada campo que cambiará, junto con un resumen breve cuando todos reciban la misma actualización.

Distingue entre escrituras absolutas y condicionales. Una escritura absoluta dice status = archived sin importar qué haya ocurrido desde la vista previa. Una escritura condicional dice «archivar solo si el estado sigue siendo inactivo y la versión sigue siendo 17». Las escrituras condicionales suelen ser más seguras porque fallan de forma cerrada cuando otra persona cambió el registro.

Usa una versión, un ETag o la última revisión conocida en cada modificación cuando la API lo permita. Esto no sustituye al manifiesto de objetivos. Resuelve otro problema: un registro revisado puede dejar de ser apto cuando empieza la ejecución.

Un registro de aprobación compacto podría representarse así:

{
  "request_id": "req_91a8",
  "selection_id": "sel_7f2c",
  "selection_digest": "sha256:4c76...",
  "target_count": 482,
  "action": {
    "type": "pause_collection",
    "precondition": {"status": "past_due"}
  },
  "approved_by": "operator account identifier",
  "approved_at": "2025-03-08T14:16:02Z"
}

No permitas que un agente reutilice esta aprobación para otra acción contra el mismo conjunto. Pausar el cobro, emitir créditos y eliminar registros tienen consecuencias distintas aunque la lista de objetivos sea idéntica. Vincula la aprobación a una carga canónica de la acción y al resumen de selección.

Los límites de tiempo importan. Una aprobación que siga siendo válida hasta que el agente decida usarla convierte un momento de revisión humana en un permiso permanente. Da a las aprobaciones una caducidad breve y adecuada para la operación, invalídalas cuando cambie la selección y exige una decisión nueva si el agente modifica de forma sustancial la acción.

La finalización parcial necesita un registro y una regla de detención

Toda operación masiva acaba encontrándose con un límite de velocidad, un tiempo de espera, un fallo de validación o una interrupción de red. La respuesta peligrosa es reintentar todo el trabajo sin saber qué registros ya cambiaron. Eso crea cobros duplicados, notificaciones repetidas o un registro de auditoría engañoso.

Asigna un ID de operación y una clave de idempotencia a la acción solicitada. Registra el resultado de cada objetivo: correcto, fallido, omitido porque cambió una precondición o desconocido porque el servicio no devolvió un resultado duradero. «Desconocido» no equivale a fallido. Trátalo como un estado que requiere investigación antes de reintentar.

Define una regla de detención antes de ejecutar. Una regla razonable podría detenerse ante un error estructural, como un fallo de autorización o una respuesta con un esquema inesperado, y permitir que los fallos de validación aislados se reúnan para revisarlos. Evita una opción genérica de «continuar tras un error». Convierte un cambio no reconocido del contrato de la API en una larga lista de registros dañados.

Considera un fallo habitual. Un agente muestra la vista previa de 800 cuentas de usuario para cambiarles el rol y después inicia un bucle del lado del cliente. Las primeras 300 solicitudes tienen éxito. Una implementación cambia el endpoint de modo que un campo ausente pasa a tener por defecto el rol de administrador en lugar del rol de lector previsto. La siguiente respuesta parece correcta. Si el bucle continúa, el error se extiende. Si el agente registra la forma de cada respuesta y se detiene cuando el contrato difiere de la acción aprobada, el alcance termina en la primera respuesta anómala.

Para el trabajo destructivo, diseña la compensación antes de ejecutar. Una solicitud de compensación necesita el valor anterior capturado para cada registro, no una promesa vaga de que alguien podrá deshacerlo. Aun así, no llames inofensiva a una reversión. Una edición legítima posterior puede hacer incorrecta una reversión ciega, y los efectos externos, como correos o exportaciones, quizá no puedan deshacerse.

El acceso de lectura puede exponer tanto como una escritura incorrecta

Los equipos suelen aplicar una confirmación cuidadosa a las eliminaciones y ninguna a la selección. Eso ignora que un agente puede recuperar una lista completa de clientes, direcciones personales, estados de pago o notas internas para crear su vista previa. La vista previa debe mostrar datos suficientes para que una persona reconozca los registros, no todos los campos que ofrece la API subyacente.

Solicita un conjunto de campos deliberadamente limitado. Por lo general bastan el ID estable, el nombre visible, el estado, la propiedad y los valores relevantes para el cambio propuesto. Mantén fuera de la respuesta de selección los secretos, tokens, notas de texto libre y datos personales no relacionados. Así la revisión genera menos ruido y se reduce lo que el agente puede repetir en mensajes posteriores.

El mismo principio se aplica a los filtros. Un agente no debe ampliar una consulta porque no tiene permiso para inspeccionar un campo. Si no puede demostrar que un registro pertenece a la selección, debe mostrar la ambigüedad y esperar a que una persona la resuelva. Adivinar no es criterio operativo.

Trata el entorno como parte del manifiesto. Producción, staging y un sandbox pueden exponer nombres de recursos idénticos. Coloca el host de destino o el identificador de cuenta junto al recuento de objetivos y el resumen de la acción. Hay ingenieros que han aprobado una lista de registros perfectamente razonable contra el entorno equivocado porque la vista previa hacía parecer que el entorno era un detalle secundario.

Los agentes necesitan autoridad sobre la llamada, no custodiar las credenciales

Un agente que tiene un token de API amplio puede realizar la llamada masiva antes de que alguien vea el conjunto de objetivos. Puedes añadir mensajes y registros alrededor de ese diseño, pero la credencial sigue dando al proceso una vía de escape. Mantén la credencial en un ejecutor de acciones que pueda rechazar o aprobar la solicitud antes de que llegue a la API externa.

Sallyport adopta este enfoque para las acciones HTTP y SSH compatibles: el agente solicita la acción mediante su conexión MCP, mientras la aplicación conserva la credencial y ejecuta la acción. Su autorización por sesión y la aprobación opcional de la clave en cada llamada encajan con un flujo en el que el agente puede preparar una solicitud masiva, pero no debe obtener material secreto reutilizable.

Esa aprobación no cubre todo el diseño de seguridad masiva. Una tarjeta de aprobación para una llamada HTTP no puede indicar a quien revisa si un filtro devolverá 10 registros o 10.000, a menos que el agente haya generado y conservado primero el manifiesto de objetivos. Usa la pasarela para controlar la autoridad y haz que el flujo de la aplicación vincule la vista previa, la selección, la aprobación y la confirmación.

El registro de auditoría también necesita dos niveles de detalle. Un registro debe mostrar la ejecución del agente que solicitó el trabajo y quién lo aprobó. Otro debe mostrar cada llamada externa, incluido el resumen de selección, el ID de operación, el endpoint y el estado del resultado. Si ocurre un incidente, los investigadores deben poder responder tanto «¿qué proceso lo solicitó?» como «¿qué registros cambiaron?».

Un flujo masivo debe cerrarse cuando la intención se vuelve ambigua

Diseña el flujo del agente para que no pueda pasar directamente de una solicitud en lenguaje natural a una modificación. La siguiente secuencia es deliberadamente aburrida porque lo aburrido resulta más fácil de investigar.

1. El agente convierte la solicitud en un selector, una modificación propuesta, un entorno y exclusiones. Pide aclaraciones si alguno de esos elementos sigue siendo ambiguo.
2. Crea una selección estable y recupera los campos de revisión de todos sus miembros. Registra el ID de selección, el resumen, la consulta, la hora y si se completaron todas las páginas.
3. Presenta el manifiesto y el efecto propuesto. Una persona aprueba exactamente ese par o lo rechaza.
4. Envía una solicitud de confirmación con la referencia de selección, el resumen esperado, la carga de la acción, la clave de idempotencia y las versiones de los registros cuando estén disponibles.
5. Informa por separado de los resultados completados, fallidos, omitidos y desconocidos. Nunca convierte un resultado parcial en un mensaje alegre que diga que el trabajo terminó.

No apruebes un comando sin procesar como «ejecuta el script de limpieza» si el comando puede calcular sus objetivos más tarde. Esta práctica es popular porque resulta rápida y familiar, especialmente para equipos que ya confían en sus scripts. Falla porque la aprobación cubre el texto del código, no el conjunto de datos real. Un cambio pequeño en los datos entre la confirmación y la ejecución puede hacer que el comando aprobado realice trabajo no aprobado.

Para trabajos recurrentes, define de antemano selectores limitados y un recuento máximo. Exige una revisión cuando la selección supere ese límite o incluya una categoría desconocida. Un recuento máximo es una barrera de seguridad, no una autorización. El manifiesto sigue siendo la prueba de a quién afectó realmente el trabajo.

La primera tarea de implementación es sencilla: haz que tu endpoint masivo devuelva un identificador de selección y un resumen, y después rechaza las solicitudes de confirmación que no repitan ambos valores. Una vez que exista ese contrato, los agentes, paneles y scripts tendrán un límite firme que podrán respetar.