Cómo implementé loops agénticos en MercaConnect: Teoría del Capítulo 1 al Código Real

1. El Problema de Producto: Automatizar la Inteligencia de Mercado

En el comercio electrónico, los fundadores y gerentes de producto de marcas en crecimiento dedican horas semanales a revisar manualmente las tiendas en línea de sus competidores: analizan qué ganchos de venta utilizan, cómo estructuran sus ofertas y cuáles son sus precios vigentes.

Al planear el desarrollo de MercaConnect, nos propusimos automatizar este proceso. Sin embargo, nos enfrentamos a un reto de ingeniería fundamental:

Las herramientas de web scraping tradicionales se rompen fácilmente ante mínimos cambios de HTML.
Inyectar código HTML completo y crudo de forma directa a un Modelo de Lenguaje (LLM) es extremadamente ineficiente, costoso en tokens y genera alucinaciones debido al ruido visual de la estructura web.

Para solucionar esto, decidí aplicar el concepto principal del Capítulo 1: Introducción a los agentes de IA—el loop de Percepción, Razonamiento y Acción—para construir un sistema de extracción autónomo de mercado.

2. Arquitectura & Flujo en Producción

El flujo de control no sigue un prompt plano de tipo “pregunta y respuesta”. En su lugar, el backend de MercaConnect orquesta un loop de control que toma decisiones lógicas iterativas en base a lo que percibe de la web competidora:

graph TD
    A[URL Competidor] --> B[Percepción: Endpoint FastAPI + Jina Reader]
    B --> C[Razonamiento: Evaluar Propuesta, Categorías y Precios]
    C --> D{¿Datos de Precios Completos?}
    D -- No --> E[Acción: Tool Calling - Búsqueda Web de Sub-páginas]
    E --> B
    D -- Sí --> F[Generar Payload JSON Estructurado para el Dashboard]

La arquitectura se divide en tres componentes claros:

Módulo de Percepción: Un endpoint de FastAPI que toma la URL del competidor, invoca a Jina Reader para convertir la página web en markdown limpio de forma asíncrona, eliminando scripts, estilos e imágenes innecesarias.
Módulo de Razonamiento: El LLM analiza el markdown limpio, mapeando la propuesta de valor y las categorías de productos. Si nota que los precios no están explícitos en la página de inicio, decide dinámicamente llamar a una herramienta para buscar sub-páginas internas de catálogos o precios.
Módulo de Acción (Tool Calling): Ejecución de consultas web dirigidas para complementar el contexto antes de formatear la salida en un esquema JSON estrictamente validado.

3. Lógica del Código & Backend

A continuación, te comparto la firma técnica y la implementación simplificada en TypeScript del núcleo del agente que corre en nuestro entorno de desarrollo e integración de MercaConnect:

// src/services/agents/competitorAgent.ts
import { OpenAI } from "openai";
import { jinaReaderTool, searchPricingCatalogTool } from "./tools";

interface AgentState {
  targetUrl: string;
  markdownContent?: string;
  pricingData?: Record<string, any>;
  hasPricing: boolean;
  attempts: number;
}

export async function runCompetitorIntelligence(url: string): Promise<string> {
  const openai = new OpenAI();
  let state: AgentState = { targetUrl: url, hasPricing: false, attempts: 0 };

  // Paso 1: Percepción inicial (Scraping limpio de Jina Reader)
  state.markdownContent = await jinaReaderTool(url);

  // Paso 2: Loop de Razonamiento y Acción recursivo
  while (!state.hasPricing && state.attempts < 3) {
    const response = await openai.chat.completions.create({
      model: "gpt-4o-2024-08-06", // Modelo con soporte de Salidas Estructuradas
      messages: [
        { 
          role: "system", 
          content: `Eres un agente experto en inteligencia competitiva en e-commerce. 
          Tu objetivo es analizar la web del competidor y extraer: propuesta de valor, estructura de precios y ganchos de conversión.
          Si el contenido actual no muestra explícitamente los precios o catálogo de productos, DEBES llamar a la herramienta searchPricingCatalogTool para explorar sub-páginas.`
        },
        { 
          role: "user", 
          content: `URL Principal: ${state.targetUrl}. Contenido extraído:\n\n${state.markdownContent}` 
        }
      ],
      tools: [searchPricingCatalogTool],
      tool_choice: "auto"
    });

    const choice = response.choices[0].message;

    // Verificar si el agente decidió usar una herramienta para profundizar
    if (choice.tool_calls && choice.tool_calls.length > 0) {
      const toolCall = choice.tool_calls[0];
      if (toolCall.function.name === "searchPricingCatalogTool") {
        const args = JSON.parse(toolCall.function.arguments);
        const subPageContent = await searchPricingCatalogTool(state.targetUrl, args.subPath);
        state.markdownContent += `\n\n[Contexto Adicional - Ruta ${args.subPath}]:\n${subPageContent}`;
      }
      state.attempts++;
    } else {
      state.pricingData = JSON.parse(choice.content || "{}");
      state.hasPricing = true;
    }
  }

  return JSON.stringify(state.pricingData, null, 2);
}

El Detalle que Salva el Rendimiento: Salidas Estructuradas de OpenAI

Al utilizar el parámetro response_format con esquema Zod en backend, garantizamos que MercaConnect reciba siempre un JSON perfecto con las claves propuesta_valor, precios_observados y debilidades_competidor. Cero dolores de cabeza intentando limpiar cadenas de texto aleatorias en producción.

4. Lecciones en las Trincheras

Haber llevado este loop de la teoría a MercaConnect me dejó tres grandes aprendizajes como AI Engineer:

Limpiar la entrada es el 80% de la batalla: Jina Reader no es un scraping opcional; es el filtro crítico de reducción de tokens. Al pasar de HTML crudo (120k tokens) a Markdown limpio de Jina (8k tokens), reducimos el costo por llamada en un 93% y la latencia bajó de 22 segundos a tan solo 4.5 segundos.
Los loops necesitan límites duros: Un agente autónomo puede ciclarse indefinidamente buscando sub-páginas si no estableces un contador estricto de intentos (attempts < 3). En producción, la previsibilidad es reina.
Los prompts no reemplazan la arquitectura: En lugar de sobrecargar al LLM con un mega-prompt que intente hacerlo todo, fue mucho más efectivo dividir el pipeline en pasos aislados y controlables: FastAPI maneja la red, Jina el parsing y el LLM exclusivamente la lógica relacional.

[!IMPORTANT] ¿Quieres ver el código del Pipeline y las configuraciones de FastAPI? He empaquetado el repositorio completo de este agente (incluyendo los mocks de testing y las llamadas optimizadas a Jina Reader). Suscríbete al Engineering Dispatch en el formulario inferior y te lo enviaré directo a tu correo.