Consigna y alcance
Convierte una API de gestión de proyectos diseñada para desarrolladores humanos en una que los agentes de IA puedan invocar de manera confiable. Explica las descripciones de operaciones, entradas, salidas, paginación, errores, confirmación de escritura, límites de tasa y seguridad. La consigna hace referencia al Internet-Draft de junio de 2026 del IETF "Agent-Friendly HTTP API Profile". Es de carácter informativo (Informational) y sigue en desarrollo; no define ningún protocolo, identidad o mecanismo de autorización nuevo.
Qué evalúa el entrevistador
- Tratar la descripción legible por máquina como un contrato y no como documentación posterior al desarrollo.
- Reducir decisiones erróneas mediante nombres estables, esquemas estrictos, respuestas acotadas y paginación por cursor.
- Convertir errores, reintentos, idempotencia, vistas previas y operaciones de deshacer en señales accionables.
- Separar la usabilidad de la API de la identidad del agente, la autorización y la seguridad frente a inyecciones de prompts.
Preguntas a clarificar antes de responder
- ¿Los agentes descubrirán la API a través de OpenAPI, una capa de herramientas MCP o un catálogo personalizado?
- ¿Qué operaciones son de solo lectura y cuáles notifican, cobran o mutan el estado?
- ¿Las respuestas necesitan selección de campos, paginación por cursor y un tamaño de página máximo?
- ¿Los clientes pueden proporcionar una clave de idempotencia y recuperar el resultado original tras un tiempo de espera agotado?
- ¿Qué campos devueltos contienen contenido de usuario no confiable que deba aislarse de los campos de control?
Marco de respuesta de 30 segundos
Trata la descripción de la API y el comportamiento HTTP como un único contrato de entrada. Mantén los nombres de operaciones estables y que revelen la intención, rechaza propiedades de entrada desconocidas, devuelve respuestas pequeñas con selección de campos y pagina las colecciones con cursores. Los errores llevan códigos estables, reintentabilidad y próximas acciones; las escrituras admiten claves de idempotencia, vista previa, confirmación y deshacer. El servidor aplica límites, autorización y auditoría; no puede delegar decisiones de seguridad en el agente. El documento de la IETF es una lista de verificación preliminar, no un protocolo de autenticación.
Análisis detallado paso a paso
1. Separar las capas de API y de herramientas
OpenAPI y las descripciones legibles por máquina similares pertenecen a la capa de API; MCP y otros protocolos de invocación de herramientas pertenecen a la capa de herramientas. Construye primero un contrato de API estable y verificable para que múltiples capas de herramientas puedan reutilizarlo. No hagas que el prompt o el nombre de herramienta de un agente sea el único límite de seguridad.
2. Diseñar operaciones distinguibles
Los ID de operación deben ser estables, breves y revelar la intención. En una superficie de herramientas amplia, los nombres que colocan la entidad primero, como task_create y task_update, pueden ser más fáciles de distinguir que un prefijo compartido create_. Las descripciones deben indicar cuándo usar y cuándo no usar una operación, sus efectos secundarios y qué operación de búsqueda permite obtener un identificador faltante.
3. Restringir entradas y salidas
Los esquemas de entrada deben definir campos obligatorios, enumeraciones cerradas, longitudes y límites de arrays, además de rechazar propiedades desconocidas. Las respuestas deben ser pequeñas por defecto y admitir selección de campos o verbosidad. No dependas de que el cliente solicite menos datos; el servidor sigue controlando el costo y el uso de contexto.
{
"name": "task_create",
"description": "Create a task; notifies the assignee.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"required": ["project_id", "title", "idempotency_key"],
"properties": {
"project_id": {"type": "string"},
"title": {"type": "string", "maxLength": 200},
"priority": {"type": "string", "enum": ["low", "medium", "high"]},
"idempotency_key": {"type": "string", "maxLength": 128}
}
}
}4. Hacer que las lecturas y la paginación sean recuperables
Devuelve un cursor opaco en lugar de pedirle a un agente que calcule desplazamientos. Vincula el cursor a la consulta, expíralo y devuelve next_cursor con una próxima acción lista para usar. El ordenamiento estable, las solicitudes condicionales y la selección de campos reducen la transferencia duplicada y el uso de contexto.
5. Hacer que los errores sean accionables por máquinas
Devuelve códigos estables, detalles estructurados y un flag retryable; incluye un enlace a la siguiente operación cuando sea útil. Una respuesta 429 debe proporcionar un retraso de reintento, los errores de validación deben identificar los campos y los trabajos de larga duración deben proporcionar una URL de estado. El lenguaje natural ayuda a las personas, pero no puede ser la única semántica de control.
{
"type": "https://api.example/problems/rate-limit",
"title": "Too many requests",
"status": 429,
"code": "RATE_LIMITED",
"retryable": true,
"retry_after_seconds": 30
}6. Proteger las escrituras
Las escrituras aceptan una clave de idempotencia con una ventana de tiempo y un alcance documentados. Un reintento tras un tiempo de espera devuelve el resultado original en lugar de crear un duplicado. Las escrituras de alto riesgo ofrecen ejecución de prueba (dry-run), confirmación o deshacer, y especifican notificaciones, cargos y otros efectos secundarios. El servidor sigue realizando las comprobaciones de autorización, cuota y auditoría.
7. Establecer límites de seguridad y observabilidad
Marca el texto de usuarios o de terceros como datos y mantenlo separado de los campos de control confiables para reducir la inyección indirecta de prompts. Limita el tamaño de respuesta, el tamaño de página, el sondeo y los espacios de nombres de herramientas; exige el principio de menor privilegio y confirmación humana para operaciones de alto riesgo. Registra un ID de correlación, actor, delegación, resultado y reintentos sin registrar contenido sensible.
8. Validar e iterar
Usa conjuntos de tareas fijas para medir la precisión en la selección de operaciones, errores de parámetros, escrituras duplicadas, errores recuperables, tamaño promedio de respuesta, uso de contexto, éxito tras 429 y cobertura de confirmación. Aplica versionado a descripciones, esquemas, errores y respuestas. Convierte las recomendaciones del borrador en una lista de verificación interna en lugar de prometer compatibilidad con estándares.
Ejemplo de respuesta de alta calidad
Trataría la descripción de la API como el contrato principal y diseñaría el comportamiento HTTP en torno a ella. Los ID de operación son estables y expresan entidad e intención; las descripciones detallan condiciones de uso, casos prohibidos y efectos secundarios. Los esquemas de entrada rechazan campos desconocidos y acotan enumeraciones, longitudes, arrays y páginas. Las colecciones usan cursores opacos y ordenamiento estable, mientras que las respuestas son pequeñas y permiten selección de campos.
Los errores llevan un código estable, reintentabilidad, retry_after y una próxima acción. Las escrituras requieren claves de idempotencia y devuelven el resultado original tras un tiempo de espera; las escrituras de alto riesgo admiten vista previa, confirmación o deshacer. El servidor aplica autorización, límites de tasa, tamaño y auditoría, en lugar de confiar en que el agente seguirá la prosa. El contenido de usuario está aislado de los campos de control, y los proveedores de herramientas usan espacios de nombres separados con IDs de correlación.
Por último, evaluaría un conjunto de tareas para detectar decisiones incorrectas, errores de parámetros, escrituras duplicadas, tamaño de respuesta, éxito de reintentos y cobertura de confirmación. El documento de la IETF es un borrador informativo (Informational) de junio de 2026 sin protocolo de autenticación ni autorización, por lo que lo usaría como una lista de verificación de diseño con versionado interno y reversión.
Errores comunes
- Llamar al perfil un nuevo protocolo de identidad o autorización.
- Optimizar prompts mientras se dejan OpenAPI, esquemas, errores y efectos secundarios insuficientemente especificados.
- Pedirle al agente que limite el tamaño de respuesta o que calcule desplazamientos de paginación.
- Omitir idempotencia, vista previa, confirmación o deshacer en escrituras que pueden reintentarse.
- Colocar texto de usuario devuelto en campos de instrucciones confiables e ignorar la inyección indirecta de prompts.
Preguntas de seguimiento y respuestas
¿Por qué no simplemente escribir documentación más detallada?
Un agente elige a partir de descripciones legibles por máquina y respuestas en cada paso. Los campos estables, enumeraciones, flags de error y cursores son más fáciles de ejecutar que los consejos dispersos en texto en prosa; la documentación sigue siendo útil para las personas y la migración.
¿Qué capa es dueña de la seguridad, la API o MCP?
La API debe aplicar autenticación, autorización, límites de tasa y auditoría. Una capa de herramientas puede limitar la exposición, los espacios de nombres y la confirmación, pero no puede reemplazar el control de acceso del lado del servidor.
¿Cómo decides qué escrituras necesitan confirmación?
Clasifica según la irreversibilidad, monto, divulgación de datos, notificación externa y alcance de privilegios. Las operaciones de alto riesgo exponen ejecución de prueba o un token de confirmación; las actualizaciones idempotentes de bajo riesgo pueden ejecutarse automáticamente, pero el servidor siempre las valida.
¿Qué pasa si las descripciones se contaminan con contenido de terceros?
Coloca el texto de terceros en campos de datos explícitos y evita que modifique las definiciones de herramientas o los permisos. Aísla los espacios de nombres de proveedores, fija huellas digitales, audita versiones y vuelve a verificar la autorización en el servidor.