Una habilidad no debe heredar todo el panel
WordPress 7.1 amplía la Abilities API con un ciclo de ejecución más flexible, validación personalizada y descubrimiento compartido. Eso facilita que herramientas externas conozcan capacidades del sitio. También vuelve más importante definir cada capacidad con precisión.
Un agente que necesita localizar documentación no requiere editar entradas, instalar plugins ni administrar usuarios. Si se le entrega una cuenta administrativa y una función genérica, el contrato real es mucho más amplio que la tarea. La alternativa es una habilidad de sólo lectura con entradas acotadas, respuesta estructurada y autorización comprobada en el servidor.
Este tutorial describe el contrato y el arnés local. No propone conectar producción ni usar credenciales reales.
Define un objetivo que termine en datos, no en efectos
El objetivo será buscar contenido publicado por una cadena y devolver una lista limitada con identificador, título, URL y fecha de modificación. La habilidad no devuelve contenido privado, borradores ni campos internos. Tampoco acepta instrucciones para editar.
La entrada mínima contiene consulta, límite y cursor opcional. La consulta debe tener una longitud máxima; el límite debe quedar dentro de un rango pequeño; el cursor debe validarse y expirar. La salida declara versión del contrato, resultados y siguiente cursor.
Una herramienta segura rechaza campos desconocidos. Si llega un parámetro como status=draft o include_private=true, la respuesta debe ser un error de validación, no una interpretación creativa.
Contrato propuesto
Entrada: query como texto normalizado, limit como entero acotado y cursor opaco opcional. Salida: items con id, title, url y modified_gmt; next_cursor opcional; request_id para auditoría.
El servidor aplica tres reglas después de validar el esquema. Primero, la consulta sólo opera sobre contenido público del tipo permitido. Segundo, los campos se proyectan en una lista fija. Tercero, el orden es estable para que la paginación no duplique ni pierda resultados.
No aceptes SQL, rutas REST arbitrarias ni nombres de funciones. La flexibilidad debe estar en la búsqueda, no en la posibilidad de cambiar el sistema que se consulta. Este contrato puede probarse con fixtures locales antes de envolverlo como herramienta para un agente.
Registra la capacidad con permiso explícito
La Abilities API permite declarar nombre, descripción, esquemas y callbacks. El callback de permiso debe ejecutarse para cada invocación y responder según la identidad efectiva. No confíes en que la herramienta sólo aparecerá en una interfaz autorizada.
Para una búsqueda pública puedes permitir una identidad técnica de lectura con alcance específico. Si la habilidad expone información no pública, separa otra capacidad y exige autorización distinta. Mantén el callback de ejecución libre de efectos: no actualiza contadores editoriales, no crea registros de negocio y no dispara webhooks. La auditoría técnica debe escribirse por una ruta independiente y sanitizada.
Prueba el callback con identidad válida, identidad ausente y alcance incorrecto. Los tres caminos forman parte del producto, no sólo el caso exitoso.
Una ability no se convierte sola en herramienta del navegador
El soporte de WebMCP en Playground permite experimentar con acciones expuestas al navegador, pero registrar una ability no basta. Un plugin debe envolverla como herramienta y mapear entrada, autorización, ejecución y salida. Esa separación es útil: puedes revisar el contrato antes de publicarlo en una superficie agéntica.
Mantén el wrapper pequeño. No dupliques lógica de permisos en JavaScript si la decisión canónica vive en PHP. El wrapper valida forma, invoca la ability y traduce errores estructurados. Cualquier acción de escritura permanece fuera del catálogo.
En Playground, verifica que el agente descubre sólo la herramienta esperada. Inspecciona el manifiesto efectivo; no deduzcas seguridad a partir del código fuente si otra extensión registra herramientas adicionales.
Amenazas que debes probar
Prueba inyección en la consulta, límites extremos, cursor manipulado, campos adicionales, solicitudes repetidas, contenido con instrucciones maliciosas y ausencia de identidad. Añade tiempo máximo y límite de resultados para evitar que una consulta legítima agote recursos.
La descripción de una herramienta también es entrada para el modelo. Debe decir qué hace y qué no hace sin invitar a reinterpretaciones. Aun así, la seguridad vive en el servidor: autenticación, autorización, esquema, proyección fija, rate limit y auditoría.
Registra request_id, identidad, herramienta, duración, cantidad devuelta y resultado. No guardes la consulta completa si puede contener datos sensibles; aplica reducción o hash cuando baste para investigar abuso.
Prueba local antes de conectar un agente
Crea un Playground con diez entradas públicas, dos borradores y un usuario técnico de lectura. Ejecuta casos de búsqueda normal, cero resultados, paginación, identidad inválida, intento de borrador y exceso de límite. Comprueba tanto la respuesta como el estado final de la base.
Después conecta el agente y repite los mismos casos. La evaluación no es si redacta una respuesta elegante, sino si elige la herramienta correcta, conserva los argumentos dentro del esquema y comunica los rechazos sin intentar otra ruta más amplia.
Añade una prueba de concurrencia con dos consultas simultáneas y otra de cancelación. La primera revela cursores o cachés compartidos de forma incorrecta. La segunda comprueba que una solicitud abandonada no continúe consumiendo recursos ni deje una operación pendiente. Registra tiempos máximos y estado final, no sólo la respuesta visible.
Destruye el entorno y repite desde cero. Un resultado que sólo funciona después de una configuración manual no es todavía reproducible.
Lista antes de exponer la habilidad
1. El nombre describe una operación de lectura concreta.
2. Entradas y salidas tienen esquema cerrado.
3. El callback de permiso corre en cada invocación.
4. La consulta sólo ve tipos y estados permitidos.
5. La respuesta proyecta campos fijos.
6. Escritura, borrado y administración no aparecen en el catálogo.
7. Hay límites de tamaño, tiempo y frecuencia.
8. La auditoría no guarda secretos ni contenido innecesario.
9. Los casos negativos pasan en un entorno desechable.
10. La activación en producción conserva una autorización separada.
El resultado es menos espectacular que entregar el panel completo, pero mucho más útil: una capacidad pequeña que se puede entender, probar y revocar.
