Minimización de respuestas de API para proteger el contexto de los agentes de IA

Los agentes de IA no necesitan una copia de cada objeto que consultan. Necesitan información suficiente para tomar la siguiente decisión, ejecutar la acción e informar de lo ocurrido. Cuando una API devuelve a un agente un registro completo de cliente, factura, ticket, configuración de repositorio u objeto de incidente, aunque solo necesite un ID y un estado, la API ya ha ampliado el problema de exposición de datos.

Es fácil pasar esto por alto porque la solicitud puede ser de solo lectura, estar autenticada y enviarse mediante TLS. Nada de eso cambia lo que ocurre después. La respuesta puede entrar en una transcripción del agente, un registro de herramientas, una solicitud al modelo, una caché local, un informe de errores o una cola de revisión humana. Si el agente puede leerla, debes asumir que el contexto del agente ya la contiene.

La solución práctica es minimizar las respuestas de API: define la respuesta útil más pequeña para cada tarea del agente, facilita que se solicite esa estructura y convierte los datos amplios en una vía excepcional bajo supervisión humana. No se trata de hacer más bonito el JSON. Se trata de reducir la cantidad de lugares donde pueden aparecer datos personales, financieros y operativos después de una llamada automatizada rutinaria.

Una lectura autenticada todavía puede divulgar demasiado

El acceso de lectura limita las escrituras. No limita la copia, los resúmenes, las citas ni el envío accidental de datos a otra herramienta. A menudo, los equipos llaman a un agente «de solo lectura» como si eso resolviera el riesgo. Solo resuelve una categoría de riesgo.

Piensa en un agente encargado de identificar facturas vencidas y abrir una tarea de seguimiento. Necesita el ID de la factura, el ID de la cuenta, la fecha de vencimiento, el importe, la divisa y el estado de cobro. Un endpoint de facturas convencional también puede devolver direcciones de facturación y envío, identificadores fiscales, referencias del procesador de pagos, descripciones de partidas, una nota interna de un usuario de finanzas y el historial completo de pagos. Cada campo adicional crea otro dato que el agente puede repetir aunque no lo necesite.

Los datos operativos tienen el mismo problema. Una tarea que comprueba si un despliegue terminó puede necesitar el nombre del servicio, el identificador de compilación, el estado y la categoría del fallo. Rara vez necesita una exportación completa del entorno con nombres de host, direcciones internas, salida de comandos, comentarios del incidente o configuración no relacionada.

Es importante distinguir dos conceptos que suelen confundirse: la autorización responde si un llamador puede acceder a un recurso; la minimización responde cuánto recibe de ese recurso para este trabajo concreto. Un token con permiso para leer invoice:123 puede estar correctamente autorizado y aun así recibir una representación insegura de esa factura.

El RFC 9110 de la IETF describe las representaciones como información destinada a reflejar el estado actual o deseado de un recurso. No exige una única representación máxima por recurso. Ese margen resulta útil para el diseño. Un recurso puede tener una representación resumida, una operativa y otra financiera, siempre que la API defina con claridad cada contrato.

No dependas de una instrucción del prompt como «ignora los datos personales». Los prompts influyen en el comportamiento; la estructura de la respuesta controla la exposición. Si un endpoint envía una dirección particular, el agente ya la ha recibido antes de decidir si debe ignorarla.

Empieza por el trabajo que el agente debe completar

Un contrato de respuesta seguro parte de la decisión que el agente debe tomar, no de un modelo de base de datos existente. Describe la tarea en una frase y después enumera los datos que cambian la acción. Todo lo demás debe justificar su presencia.

Por ejemplo, un agente que reintenta trabajos de compilación fallidos puede necesitar esta respuesta:

{
  "job_id": "job_4821",
  "state": "failed",
  "retryable": true,
  "failure_class": "transient_dependency",
  "attempts_remaining": 1
}

No necesita el registro completo de compilación para decidir que el reintento está permitido. Si después una persona necesita diagnósticos, ofrece un endpoint separado, con una audiencia más limitada y un motivo explícito para consultarlo. Un endpoint de registros también debería admitir rangos acotados, porque los registros completos contienen tokens, entradas de clientes, rutas y fragmentos de configuración con más frecuencia de la que nadie admite.

Crea una pequeña matriz de tareas antes de cambiar los endpoints. Esto obliga a mantener conversaciones que de otro modo quedarían en términos vagos:

Un campo solo pertenece a la respuesta si cambia la rama que toma el agente, aparece en la solicitud de acción o debe aparecer en su informe para el usuario. «Podría ser útil después» no es una buena razón. Así es como los endpoints de listas terminan teniendo cincuenta campos y nadie sabe quién depende de ellos.

El ejercicio también revela campos que deberían calcularse en lugar de divulgarse. Un agente no necesita un registro de nómina para saber si la aprobación de un gasto requiere a un gerente. Devuelve approval_required: true. Tampoco necesita todas las autorizaciones para saber si un despliegue puede continuar. Devuelve deployment_permitted: false y un código de motivo estable.

Esto no es seguridad por ocultación. Es un contrato de API deliberado que proporciona a los llamadores el resultado que necesitan sin entregarles el registro subyacente.

Los objetos predeterminados deben ser resúmenes, no filas de base de datos

El diseño más fiable ofrece por defecto un resumen seguro en las llamadas normales de lista y consulta. Haz que las representaciones detalladas sean explícitas, tengan una autorización separada y sean poco habituales. Exigir que cada llamador recuerde una opción de consulta restrictiva terminará fallando, especialmente cuando una biblioteca añada un método cómodo que la omita.

Un resumen de cliente podría tener este aspecto:

{
  "id": "cus_7f31",
  "display_name": "Northwind Parts",
  "account_state": "active",
  "open_invoice_count": 2,
  "support_tier": "standard"
}

No devuelvas email, phone, la dirección postal, el identificador fiscal, los metadatos del instrumento de pago ni notas de texto libre solo porque una fila de cliente los contenga. Algunos de esos campos pueden ser necesarios para una aplicación de facturación. No pertenecen a un contrato de resumen utilizado por un agente de operaciones.

Hay dos patrones que funcionan. Un endpoint de resumen separado, como GET /customers/{id}/summary, es directo y fácil de auditar. Un parámetro de proyección, como GET /customers/{id}?view=summary, puede funcionar si utiliza un conjunto fijo y documentado de vistas. Ambos son mejores que un endpoint que lo devuelve todo y pide a cada cliente que ignore lo que no necesita.

Evita un interruptor genérico expand=* o include=all para las credenciales de agentes. Se convierte en el camino más fácil durante la depuración y después permanece en producción porque eliminarlo parece arriesgado. Si hace falta una representación detallada, ponle el nombre de la tarea: view=collections, view=deployment_status o view=case_triage. Los nombres de tareas obligan a revisar el diseño. «Todo» evita esa revisión.

Una objeción habitual es que las vistas separadas duplican código. Sí, duplican parte del código de mapeo. Ese coste es pequeño frente a investigar por qué una transcripción de herramienta contiene un número fiscal o una nota interna de incidente. La capa de mapeo también es el lugar donde documentas la responsabilidad y pruebas la promesa de que una vista para agentes excluye las columnas sensibles.

La selección de campos debe usar una lista de permitidos, no un truco del analizador

Un parámetro fields puede reducir bien las respuestas, pero solo si el servidor lo trata como una lista estricta de permitidos. Un analizador flexible convierte una función cómoda en una interfaz de extracción de datos.

Esta solicitud es razonable:

GET /v1/invoices?state=overdue\u0026fields=id,account_id,due_date,amount,currency,collection_state\u0026limit=25

El servidor solo debe devolver los campos permitidos para ese endpoint y esas credenciales. Si un llamador solicita billing_address o payment_reference, rechaza la solicitud con un error claro. No añadas campos sensibles en silencio ni aceptes rutas anidadas arbitrarias como customer.*.

Un contrato de respuesta podría definir el comportamiento con precisión:

{
  "error": {
    "code": "unsupported_field",
    "message": "Field 'payment_reference' is not available in the agent invoice view",
    "allowed_fields": [
      "id",
      "account_id",
      "due_date",
      "amount",
      "currency",
      "collection_state"
    ]
  }
}

El propio error también necesita disciplina. Nunca incluyas el valor del campo rechazado, datos cercanos del registro, una traza de pila, texto de consulta sin procesar de otro servicio ni un error de base de datos. Los cuerpos de error suelen convertirse en una segunda API accidental, especialmente cuando los ingenieros los hacen demasiado detallados para acelerar la resolución de un incidente.

GraphQL merece el mismo escrutinio. Se suele asumir que los clientes solo pueden solicitar lo que nombran, lo cual ayuda, pero un esquema todavía puede exponer campos sensibles, las relaciones anidadas pueden multiplicar los registros y los alias pueden hacer difícil razonar sobre una sola consulta. Establece límites de profundidad y complejidad, desactiva o restringe la introspección cuando sea adecuado para el entorno y autoriza los campos, no solo los objetos de nivel superior. Más importante aún, crea un esquema para agentes o consultas persistentes para las pocas tareas aprobadas. Un esquema amplio acompañado de una instrucción amable no es una interfaz limitada.

El OWASP API Security Top 10 señala la autorización rota a nivel de propiedades de objetos. Su preocupación suele plantearse como un llamador que recupera una propiedad a la que nunca debería acceder. El uso por parte de agentes añade otro modo de fallo: el llamador puede tener acceso técnico, pero la tarea no necesita la propiedad y no debería distribuirla al contexto del modelo. Mantén ambas comprobaciones. Pregunta «¿puede esta credencial leerlo?» y después «¿por qué necesita esta tarea ese dato ahora?».

La paginación controla el volumen, pero los filtros controlan la relevancia

Una respuesta con diez registros no es automáticamente una respuesta pequeña. Si cada registro contiene un objeto anidado grande o un campo de texto largo, la paginación solo divide la filtración en páginas ordenadas.

Usa filtros que expresen el trabajo del agente. Un agente de cobros debería consultar las facturas vencidas en un estado y un intervalo de fechas determinados. No debería listar todas las facturas y decidir localmente cuáles importan. Un agente de despliegues debería solicitar un servicio y una versión concretos, no consultar todos los entornos y buscar después en el resultado.

La paginación mediante cursores también necesita una estructura de respuesta cuidadosa. El cursor debe ser opaco y no debe incluir una dirección de correo, un nombre de cuenta, valores de filtros sin cifrar ni una clave de base de datos interna que revele el orden. Los clientes pondrán los cursores en registros y tickets. Trátalos como datos que circulan.

Mantén límites de página conservadores para las credenciales de agentes. Un límite pequeño hace más que reducir el uso de tokens. Proporciona un punto de pausa en el que el agente puede revisar un resumen, elegir un registro relevante y hacer una llamada de seguimiento específica. Esa secuencia es más segura que cargar todo el historial de una cuenta porque una tarea comenzó con las palabras «investiga a este cliente».

No confundas un endpoint de búsqueda con permiso para devolver todos los detalles coincidentes. La búsqueda normalmente debería devolver una tarjeta de resultado: ID estable, etiqueta, estado y quizá el motivo de coincidencia. El llamador puede recuperar una vista detallada permitida después de seleccionar un registro. Este patrón de dos llamadas parece menos cómodo que un objeto de resultados gigante, pero hace visible y revisable la transferencia de información sensible.

El texto libre y los registros anidados necesitan su propio límite

Los campos estructurados son más fáciles de clasificar que el texto escrito por personas. Los campos de texto libre absorben nombres, números de teléfono, credenciales pegadas por error, acusaciones, datos de salud, asesoramiento jurídico y opiniones internas. La description de un ticket parece inofensiva al revisar el esquema, hasta que alguien lee los tickets reales de una semana.

Trata los comentarios, las notas, las descripciones, los archivos adjuntos, los registros y los cuerpos de mensajes como sensibles por defecto en los flujos de trabajo autónomos. Devuelve en su lugar una categoría, una clasificación breve generada por el servidor o un recuento cuando eso baste para elegir una acción. Por ejemplo, un agente puede necesitar has_customer_reply: true y latest_message_at, no el mensaje en sí.

No pidas al modelo que redacte texto arbitrario después de recuperarlo. Este enfoque es popular porque parece conservar un único endpoint amplio. Falla de dos maneras. Primero, el contenido sin procesar ya ha entrado en el contexto del agente antes de la redacción. Segundo, la redacción generada por el modelo es probabilística, así que pueden sobrevivir un nombre parcial, un número de cuenta o una cita.

Si una tarea realmente necesita texto, impón límites estrictos a la solicitud. Recupera un mensaje por ID en lugar de un hilo completo. Solicita un límite de caracteres conocido que haga cumplir el servidor. Elimina el contenido de los archivos adjuntos salvo que un usuario haya aprobado esa recuperación concreta. Indica qué recibirá el cliente cuando se trunque el contenido, por ejemplo content_truncated: true, para que el agente no invente los detalles que faltan.

Los datos anidados crean una versión más silenciosa del mismo fallo. Una respuesta que incluye customer, contacts, invoices, payments y events puede parecer un único objeto en el código de la aplicación. En términos de exposición, es un conjunto de bases de datos independientes. Exige endpoints separados o ampliaciones explícitas y autorizadas para cada relación. Después prueba la consulta habitual más arriesgada, no solo el caso ideal que devuelve un registro escaso.

La gestión de errores y la observabilidad pueden recrear la filtración

Los equipos suelen limitar la respuesta correcta y después copiar la carga original en registros de depuración, atributos de trazas, colas de reintento e informes de excepciones. Los datos han cambiado de lugar, pero su exposición no se ha reducido.

Inspecciona todo el recorrido de la llamada. Como mínimo, revisa el adaptador de herramientas del agente, el modo de depuración del cliente HTTP, el grabador de solicitudes, la configuración de trazas distribuidas, el servicio de informes de errores, la cola de trabajos, el almacenamiento local de transcripciones y el flujo de trabajo de soporte. Los lugares que aseguran registrar «solo metadatos» merecen una prueba directa, no confianza.

Ejecuta un registro canario en un entorno que no sea de producción. Asígnale valores ficticios distintivos en campos que nunca deben llegar al contexto del agente, como CANARY_BILLING_ADDRESS_927 y CANARY_INTERNAL_NOTE_927. Ejecuta la tarea real del agente y después busca esas cadenas en todos los almacenes de registros y trazas permitidos. Repite la prueba con una solicitud fallida, un tiempo de espera agotado y una respuesta malformada. Las pruebas del camino correcto no detectan la mayoría de las capturas accidentales de cargas.

Un diario útil de llamadas registra la acción sin duplicar el contenido:

{
  "time": "2025-03-08T14:03:12Z",
  "caller": "release-agent",
  "operation": "GET /v1/jobs/{id}/retry-status",
  "resource_id": "job_4821",
  "response_view": "retry_status",
  "field_set": ["job_id", "state", "retryable", "failure_class"],
  "result_count": 1,
  "outcome": "200"
}

Registra identificadores solo cuando tus propias reglas de retención y acceso lo permitan. En sistemas de mayor riesgo, guarda una referencia con clave o un ID de correlación de corta duración. Un hash también puede filtrar información si el valor original procede de un dominio pequeño y fácil de adivinar, así que no llames al hashing «redacción» sin tener en cuenta lo que un atacante puede enumerar.

Limpia los mensajes de error salientes en el límite del servidor. Un controlador de base de datos puede exponer un fragmento de SQL fallido. Un servicio ascendente puede enviar un registro completo dentro de un envoltorio de error. Tu API debe convertir esos fallos en códigos públicos estables, conservar los diagnósticos detallados en un almacén restringido y no incluir por defecto el cuerpo de la respuesta en los errores dirigidos a agentes.

Separa la capacidad de la divulgación en la puerta de enlace del agente

Una puerta de enlace de acciones debe conservar la credencial y ejecutar la solicitud, pero no debe considerar que toda respuesta disponible para esa credencial sea adecuada para el contexto del agente. El aislamiento de secretos y la minimización de respuestas resuelven partes distintas de la misma llamada.

Sallyport mantiene los secretos de API y SSH en su bóveda cifrada y devuelve los resultados de las acciones al agente sin exponerle el secreto. Eso protege la credencial, pero el propietario de la API todavía debe decidir si el resultado contiene un registro de cuenta innecesario, una salida de comandos o un detalle operativo.

Siempre que sea posible, asigna a cada tarea del agente una plantilla de solicitud con nombre. La plantilla fija el método, el host, la estructura de la ruta, los campos de consulta permitidos, el límite de página y la vista de respuesta aceptada. Una plantilla de estado de lanzamiento puede permitir un único ID de servicio y devolver un objeto de estado breve. No debería aceptar una URL arbitraria y una expresión fields arbitraria solo porque ambas sean fáciles de pasar.

Aquí es donde causa problemas pensar en un proxy amplio. Un reenviador HTTP genérico puede ser útil durante el desarrollo, pero no puede expresar la diferencia entre «comprueba este despliegue» y «descarga todos los registros de artefactos». Pon la intención en la acción invocable. Cuando una tarea nueva necesite más datos, exige un cambio en la API o una plantilla nueva. Esa fricción es precisamente el objetivo: alguien debe explicar por qué esos datos adicionales tienen que entrar en el contexto.

La aprobación humana sigue teniendo un papel para las excepciones. Si un agente necesita el contenido de un mensaje de soporte para resolver un caso, una persona puede aprobar esa llamada concreta después de ver el destino y el alcance. La aprobación no debe convertirse en el sustituto habitual de las respuestas limitadas. Las personas aprueban rápidamente tarjetas conocidas, sobre todo durante un incidente, y las aprobaciones repetidas hacen que dejen de leer.

Prueba la ausencia de campos como parte del contrato

La mayoría de las pruebas de API comprueban que existan los campos esperados. Las API destinadas a agentes también necesitan pruebas que confirmen que los campos prohibidos no existen, incluso cuando el código toma una ruta alternativa.

Mantén una prueba de lista de bloqueados junto a cada vista de respuesta. Usa nombres de campos realistas, incluidas relaciones anidadas y texto libre. La prueba debe fallar si la serialización añade después uno de ellos mediante un valor predeterminado del ORM, un DTO compartido o una relación cargada de forma anticipada.

forbidden = {
    "email",
    "phone",
    "billing_address",
    "tax_id",
    "payment_reference",
    "internal_note",
    "attachments",
}

body = get_invoice_agent_view("inv_1042")
assert forbidden.isdisjoint(body.keys())
assert "customer" not in body
assert "events" not in body

Esa prueba sencilla solo detecta campos de nivel superior. Añade pruebas de serialización que recorran todo el árbol JSON y prueba por separado los endpoints de listas, búsquedas, errores y exportaciones. La filtración más grave suele proceder de una respuesta de colección que reutiliza un serializador de detalles completo porque así se ahorraron unas líneas de código.

Las pruebas de contrato también deben comprobar los límites de tamaño de la respuesta. Un límite estricto de bytes no encajará con todos los objetos, pero un techo razonable te avisará cuando alguien añada un campo de texto sin límite o una relación. Combínalo con un fixture que contenga notas largas y muchos registros secundarios; de lo contrario, la prueba dará una falsa sensación de seguridad.

Revisa los cambios con tres preguntas directas: ¿qué tarea del agente necesita este campo? ¿Qué vista de respuesta lo incluye? ¿Qué prueba demuestra que permanece ausente en cualquier otro lugar? Si el autor no puede responder, no integres el campo en un endpoint al que se pueda llamar ampliamente.

Haz que la recuperación excepcional de detalles sea visible y temporal

Algunos trabajos realmente necesitan detalles sensibles. La revisión de fraude, la recuperación de una cuenta, una investigación de seguridad y un caso de soporte difícil no pueden funcionar únicamente con resúmenes. La respuesta no es fingir lo contrario. Es hacer que la recuperación de esos detalles sea explícita, breve y limitada al registro exacto.

Usa un endpoint o una acción separados que reciban un ID de registro estable y un propósito declarado. Devuelve la porción mínima necesaria, como un único campo de pago disputado o un mensaje de cliente seleccionado. No concedas acceso a una exportación completa de la cuenta porque el mismo caso contenga un cargo disputado.

Para recuperaciones de mayor riesgo, exige que una persona apruebe la llamada concreta y registra el llamador, el propósito, la vista, la referencia del registro y el resultado. Mantén el registro de auditoría separado del cuerpo de respuesta sensible. Necesitas saber que se produjo una recuperación sin crear otra copia casual de la información.

Una API madura hace que el camino seguro sea el más fácil. Las vistas resumidas deben tener nombres claros, buena documentación y campos estables. Los endpoints de detalles amplios deben sentirse deliberados porque conllevan más responsabilidad. Si tu agente necesita repetidamente un campo sensible, no normalices la excepción. Revisa el diseño de la tarea y pregunta si una decisión en el servidor o un valor derivado y redactado resolverían el problema.

La primera auditoría útil suele ser un endpoint de listas, no el endpoint que todo el mundo teme. Captura una tarea real del agente, marca cada campo que utilizó y compara esa lista con la respuesta que recibió. La parte que no utilizó es tu próximo cambio de API.