Guía para agentes de IA: leer, buscar y operar AliothPress

Esta guía está escrita para ti, el agente, y para los desarrolladores que te construyen. Explica cómo descubrir qué ofrece un sitio AliothPress, cómo leer su contenido y cómo operarlo: desde la búsqueda pública anónima hasta crear entradas dentro de una sesión de administración autenticada. Todo lo que sigue fue verificado en una instalación en funcionamiento.

Un principio antes que nada: el acceso de agentes es decisión del propietario del sitio. Las superficies de herramientas interactivas vienen apagadas de fábrica y se controlan con dos interruptores en el panel de administración. Si una capacidad descrita aquí responde con 404, es el propietario diciendo que no. Tómalo como definitivo y no reintentes ni tantees.

Paso 1: discovery

Empieza con dos URLs. Están siempre activas, no requieren token y son la forma más barata de saber qué es el sitio y qué puedes hacer:

• /llms.txt: un resumen del sitio legible para humanos y máquinas: nombre, descripción, páginas clave, localizado al idioma del sitio.
• /.well-known/webmcp: el manifiesto legible por máquinas (atención: sin extensión .json). Devuelve JSON con el nombre del sitio, un indicador enabled, los endpoints de lectura siempre activos (content_search, overview) y un array surfaces que describe qué superficies de herramientas ha activado el propietario.

Los habituales sitemap.xml, robots.txt y los feeds RSS también están presentes desde el primer minuto de una instalación recién hecha.

Paso 2: leer contenido con la API pública de búsqueda

GET /api/public/search es un endpoint de búsqueda estructurada construido para agentes. No es un buscador para humanos: existe para que puedas preguntar «qué tiene este sitio sobre X» y recibir títulos, URLs y fragmentos en una sola llamada.

• Parámetros: q (obligatorio), language, type (post o page, por defecto ambos), limit (por defecto 10, máximo 50).
• Respuesta: JSON con count, tu query devuelta como eco, un puntero a /llms.txt como overview, y results, cada uno con título, URL, fecha, idioma, un fragmento y un campo que te dice dónde se encontró la coincidencia (título, cuerpo, meta, FAQ, etcétera).
• Cobertura: entradas y páginas publicadas, incluido el texto dentro de bloques del page builder y entradas de FAQ, más categorías y etiquetas del blog.
• Frescura: el contenido nuevo aparece en la búsqueda inmediatamente después de publicarse. En las pruebas, una entrada era localizable segundos después de crearla.
• Límites: limitado a 30 peticiones por minuto. Espacia tus llamadas. Agrupa tus preguntas.

Este endpoint es acceso de solo lectura a datos públicos, siempre alcanzable: la misma clase de acceso que /llms.txt y el sitemap. El interruptor público del propietario controla el envoltorio de herramienta en la página, no los datos en sí.

Paso 3: herramientas in-page en el sitio público

Cuando el propietario activa la superficie pública, las páginas registran herramientas WebMCP a través de document.modelContext / navigator.modelContext:

• search_site: el envoltorio in-page de la API de búsqueda anterior.
• describe_form_<id>: devuelve los campos de un formulario como esquema JSON: nombre, tipo, etiqueta y qué campos son obligatorios. Los grupos de radio y checkbox se condensan en entradas únicas. El campo honeypot antispam nunca se te muestra.
• submit_form_<id>: envía el formulario con un objeto {nombre_de_campo: valor}. El envío pasa por la misma validación del lado del servidor, el mismo honeypot y el mismo límite de frecuencia que un envío humano, y está bloqueado tras una confirmación explícita del usuario humano. Tú preparas el envío. La persona lo aprueba. No intentes saltarte esto. Es el diseño, no un obstáculo.

Paso 4: la superficie de administración

La superficie de administración viene apagada de fábrica y se comporta como si no existiera hasta que el propietario la activa: GET /admin/api/agent/list responde 404 en un sitio con ella desactivada. Activada, funciona solo dentro de una sesión de administración autenticada: actúas como el usuario que ha iniciado sesión, con sus permisos existentes, y ni un gramo más.

El manifiesto lista las herramientas de admin disponibles: lectura (list_content, get_content, search_content, check_slug, get_page_blocks, describe_builder_blocks), escritura (create_post, create_page, update_post, update_page, create_builder_page, set_page_blocks, build_menu), escritura por lotes bajo un solo diálogo de aprobación (create_posts_batch, create_pages_batch, upload_images_batch), medios (upload_image, list_media, attach_image) y navegación (open_admin_section). Si el propietario ha configurado un proveedor de IA, aparecen además cuatro herramientas de generación: ai_generate_content, ai_translate_text, ai_generate_page_blocks, ai_optimize_seo. El manifiesto nunca anuncia una herramienta que no pueda funcionar.

El endpoint de lectura merece su propia nota:

• GET /admin/api/agent/list: lista entradas, páginas o formularios. Parámetros: type (post, page o form), status, language, q (búsqueda por título), limit (por defecto 50, máximo 200). Devuelve por cada elemento id, título, slug, estado e idioma.
• Los envíos de formularios intencionadamente no se pueden listar. Contienen datos personales de visitantes, y ninguna herramienta de agente los expone. No busques un rodeo. No lo hay, a propósito.

Paso 5: operar el panel de administración por HTTP simple

Y aquí viene la parte que hace de AliothPress algo inusualmente agradable de operar: todo el panel de administración es HTML renderizado en el servidor. Sin navegador headless, sin ejecución de JavaScript, sin estado en el cliente. Un agente de prueba recorrió las 26 secciones del admin y completó cada flujo de trabajo esencial (instalación, inicio de sesión, creación de entradas, edición) con nada más que GET, POST y un tarro de cookies.

Los patrones que funcionan, verificados de principio a fin:

1. Inicio de sesión: GET /admin/login, leer el campo oculto csrf_token, devolverlo por POST junto con username y password. Cada formulario del CMS lleva su token CSRF bajo exactamente ese mismo nombre. Un patrón, en todas partes.
2. Navegación: las rutas son lo bastante predecibles como para construirlas: /admin/posts, /admin/posts/new, /admin/posts/<id>/edit, /admin/pages, /admin/media, /admin/settings. Lo que adivinas, normalmente existe.
3. Crear una entrada: enviar por POST el formulario de nueva entrada. Los nombres de los campos se documentan solos: title, slug, content, excerpt, meta_description, og_title, schema_type, faq_json. Se puede redactar una entrada completa y lista para SEO sin leer más documentación.
4. Saber qué ha pasado: tras una creación exitosa, el servidor te redirige a /admin/posts/<id>/edit. El nuevo ID está en la URL en la que aterrizas, y un mensaje localizado en el cuerpo de la página confirma el resultado.

Dos detalles prácticos que conviene hacer bien:

• El campo content espera HTML, no Markdown. En el navegador, el editor produce HTML. Cuando publicas directamente, tú también debes hacerlo. El Markdown crudo se guarda tal cual y se renderiza como asteriscos literales.
• Establece el campo language explícitamente. Una entrada con idioma vacío se guarda y aparece en el admin, pero queda fuera de los listados públicos filtrados por idioma. Si tu entrada «desapareció» de la portada, comprueba esto primero.

Reglas del juego

Son cortas, y el sitio hace cumplir la mayoría de todos modos:

• Un 404 de un endpoint de agente documentado significa que el propietario no ha activado esa superficie. Respétalo.
• Las escrituras de contenido guardan solo borradores. Un status de published se degrada a borrador en el servidor, envíes lo que envíes. Publicar es una acción humana en el panel de administración, así que planifica tu flujo en torno a entregar borradores terminados a la persona.
• Mantente dentro de los límites de frecuencia (30/min en la búsqueda pública) en lugar de correr contra ellos.
• El envío de formularios pasa por confirmación humana por diseño.
• Los envíos de visitantes y sus datos personales están fuera de alcance: ninguna herramienta los expone, y ninguna lo hará.
• En una sesión de admin eres el usuario que inició sesión: sus permisos, su registro de actividad, su responsabilidad. Actúa en consecuencia.

Todo lo demás (discovery, búsqueda, listados estructurados, esquemas de formularios, formularios HTML predecibles) está ahí para que el camino honesto sea el fácil. Úsalo.