Agentic SEO

Este sistema avanzado ha sido diseñado para automatizar y simplificar el proceso de auditoría SEO técnica de sitios web, proporcionando a los usuarios informes detallados sobre los problemas que afectan a su visibilidad en los motores de búsqueda. Aprovechando una arquitectura moderna y el poder de la inteligencia artificial, el sistema ofrece una solución integral desde el rastreo inicial hasta la generación de un informe accionable.

Arquitectura del Sistema

El sistema se basa en una arquitectura de tres capas bien definida, que garantiza escalabilidad, modularidad y una clara separación de responsabilidades:

• Frontend: Interfaz de usuario (UI) construida con React.

• Backend: API RESTful desarrollada con FastAPI.

• Agentes de IA: Módulos inteligentes impulsados por el SDK de Agentes de OpenAI, encargados del rastreo, análisis y generación de informes.

• Base de Datos: SQLite para el almacenamiento persistente de los datos rastreados y analizados.

Componentes Clave

Frontend (React)

El frontend es la cara visible del sistema y el punto de interacción principal para el usuario.

Tecnología

Desarrollado con React, lo que permite una interfaz de usuario dinámica, reactiva y eficiente.

Funcionalidad:

• Permite al usuario introducir la URL del sitio web a auditar y el número máximo de páginas a rastrear.

• Gestiona la entrada de la clave API de OpenAI del usuario de forma segura (almacenándola localmente).

• Muestra el estado del proceso (rastreando, generando informe).

• Presenta el informe SEO técnico generado en un formato legible y navegable.

• Ofrece la opción de limpiar los datos de rastreo anteriores.

• Interacción con el Backend: Se comunica con el backend de FastAPI a través de solicitudes HTTP (POST para iniciar rastreo y generar informe, DELETE para limpiar la base de datos).

Backend (FastAPI)

El backend actúa como el cerebro del sistema, orquestando las operaciones y sirviendo como intermediario entre el frontend y los agentes de IA.

Tecnología

Construido con FastAPI, un framework web moderno y de alto rendimiento para construir APIs en Python.

Funcionalidad

• Endpoints API: Expone los puntos de entrada para las operaciones del sistema (/crawl/, /generate-report/, /clear-database/).

• Orquestación del Rastreo: El endpoint /crawl/ recibe la URL y el límite de páginas del frontend. Es crucial que este endpoint bloquee su respuesta hasta que el proceso de rastreo haya finalizado por completo. Esto se logra ejecutando la lógica de rastreo (run_crawl_process_sync) en un hilo separado mediante asyncio.to_thread(), asegurando que FastAPI espere su finalización antes de enviar la confirmación al frontend.

• Gestión de la Clave API: Recibe la clave API de OpenAI del frontend y la establece como variable de entorno (OPENAI_API_KEY) para que los agentes de IA puedan autenticarse.

• Orquestación del Informe: El endpoint /generate-report/ inicia un proceso separado para ejecutar el agente analizador, esperando su resultado antes de devolver el informe al frontend.

• Gestión de la Base de Datos: Interactúa directamente con la base de datos SQLite para almacenar y recuperar los datos rastreados. El endpoint /clear-database/ se encarga de eliminar todos los registros de rastreo.

• Concurrencia: Utiliza asyncio.to_thread para manejar operaciones bloqueantes (como las solicitudes HTTP del rastreador o la ejecución de agentes de IA) sin bloquear el bucle de eventos principal de FastAPI, manteniendo la API responsiva.

Sistema de Agentes (OpenAI Agents SDK)

El corazón inteligente del sistema reside en los agentes de IA, que automatizan las tareas complejas de SEO.

Tecnología

Implementado utilizando el SDK de Agentes de OpenAI, que facilita la creación y gestión de agentes conversacionales y autónomos.

Agentes Principales

Agente Rastreador (Crawler Agent - implícito en crawler.py):

• Función: Se encarga de navegar por el sitio web, obtener el contenido HTML de las páginas y extraer enlaces internos.

• Proceso: Utiliza requests para las solicitudes HTTP y BeautifulSoup para el parseo del HTML.

• Salida: Proporciona el HTML original, el HTML prettificado y los enlaces encontrados para cada URL.

Agente Analizador (SEO Analyzer Agent - en analyzer.py):

• Función: Recibe los datos HTML rastreados y realiza un análisis técnico detallado de SEO. Identifica problemas como títulos faltantes, meta descripciones, etiquetas robots, problemas de canonicalización, estructura de encabezados (H1, H2), enlaces internos/externos, uso de imágenes (alt text, lazy loading), y aspectos de JavaScript y datos estructurados.

• Proceso: Utiliza las capacidades de IA del SDK de Agentes de OpenAI para interpretar los datos y generar hallazgos y recomendaciones.

• Salida: Produce un informe estructurado con hallazgos clave, causas potenciales, impacto SEO y recomendaciones prácticas.

Agente Estratega (SEO Strategist Agent - en strategist.py):

• Función: Toma el informe técnico generado por el Agente Analizador y lo transforma en un plan de acción estratégico y priorizado.

• Proceso: Utiliza el SDK de Agentes de OpenAI para traducir los hallazgos técnicos en pasos claros y accionables para un usuario no técnico, estimando el impacto y el esfuerzo de implementación.

• Salida: Genera un plan de acción SEO detallado y fácil de seguir.

Base de Datos (SQLite)

• Tecnología: Se utiliza SQLite, una base de datos ligera y basada en archivos, ideal para este tipo de aplicación.

• Funcionalidad: Almacena de forma persistente el HTML original, el HTML prettificado y los resultados del análisis SEO de cada página rastreada. Esto permite que el sistema de agentes acceda a los datos para generar informes y que los datos se conserven entre ejecuciones si es necesario (aunque se limpian después del informe).

Flujo de Trabajo del Sistema

• Inicio del Rastreo: El usuario introduce una URL y el número de páginas en el frontend (React) y hace clic en "Iniciar Rastreo".

• Solicitud al Backend: El frontend envía una solicitud POST a /crawl/ en el backend (FastAPI), incluyendo la URL, el límite de páginas y la clave API de OpenAI.

• Rastreo Bloqueante: El endpoint /crawl/ en FastAPI inicia la función run_crawl_process_sync en un hilo separado (asyncio.to_thread). Este hilo se encarga de:

• Rastrear las páginas del sitio web, respetando el límite especificado.

• Para cada página, obtener el HTML y pasarlo al analyze_html_content (que puede usar un agente de IA internamente para el análisis).

• Guardar los resultados del análisis en la base de datos SQLite.

• El bucle de rastreo continúa hasta que se haya alcanzado el número max_pages de páginas exitosamente analizadas y guardadas.

• Confirmación de Rastreo: Una vez que run_crawl_process_sync ha terminado (es decir, el rastreo completo y el guardado de datos han concluido), el endpoint /crawl/ en FastAPI envía una respuesta 200 OK al frontend.

• Generación del Informe: Al recibir la confirmación del rastreo, el frontend llama al endpoint /generate-report/ en FastAPI.

• Ejecución del Agente Analizador: El backend inicia un proceso separado para ejecutar el _generate_report_in_process (que a su vez llama a generate_technical_seo_report y utiliza el Agente Analizador). Este agente lee los datos de análisis de la base de datos, los procesa y genera el informe SEO técnico.

• Visualización del Informe: El informe generado es devuelto al frontend y se muestra al usuario en un modal.

• Limpieza de la Base de Datos: Después de generar y mostrar el informe, el frontend envía una solicitud DELETE a /clear-database/ para limpiar la base de datos, asegurando que los datos de la auditoría actual no interfieran con futuras auditorías.

Beneficios del Sistema

• Automatización Completa: Automatiza el proceso de auditoría SEO técnica, reduciendo el esfuerzo manual.

• Informes Detallados: Genera informes comprensivos con hallazgos y recomendaciones claras.

• Accionabilidad: Transforma datos técnicos complejos en planes de acción fáciles de seguir.

• Tecnología de Vanguardia: Utiliza FastAPI para un backend de alto rendimiento y el SDK de Agentes de OpenAI para capacidades de IA avanzadas.

• Experiencia de Usuario Intuitiva: El frontend de React proporciona una interfaz limpia y fácil de usar.

Este sistema representa una herramienta potente para cualquier profesional o propietario de sitio web que busque identificar y solucionar problemas de SEO técnico de manera eficiente.