Herramientas de Página: Deja que tu Agente de IA Actúe en tu Sitio Web

La mayoría de los chats web solo pueden conversar. El agente de okidoki además puede actuar sobre tu página — desplazar al visitante a la sección correcta, abrir un modal, agregar un artículo al carrito, enviar un formulario o consultar datos en vivo de tu app — porque puedes registrar herramientas de página (client-side tools) directamente desde el JavaScript de tu sitio. Esta guía muestra a los desarrolladores web cómo definir esas herramientas con OkidokiWidget.registerTools(), usando la misma API que impulsa la propia landing de okidoki.chat.

¿Qué son las herramientas de página?

Una herramienta de página es una función JavaScript que expones a la IA. Le das un name, una description en lenguaje natural sobre cuándo usarla, un esquema de input y un handler que se ejecuta en el navegador del visitante. Durante la conversación, el agente decide cuándo la herramienta es relevante, la llama con argumentos estructurados, recibe lo que devuelve tu handler y continúa la conversación con ese resultado en contexto.

Como el handler corre en el navegador, tiene acceso completo a tu página: el DOM, el estado de tu framework, tu carrito, tu router y cualquier API que tu front-end ya pueda alcanzar. La IA nunca toca tu código directamente — solo llama a las herramientas que tú eliges registrar.

La forma de una herramienta

Registra una o más herramientas con OkidokiWidget.registerTools([...]). Cada herramienta es un objeto:

OkidokiWidget.registerTools([
  {
    name: 'add_to_cart',
    description: 'Agrega un producto al carrito. Úsala cuando el comprador acepta comprar o pide agregar un artículo.',
    input: {
      productId: 'El ID del producto a agregar',
      quantity: 'Cuántas unidades (opcional, por defecto 1)'
    },
    handler: async (args) => {
      const result = await myStore.addToCart(args.productId, args.quantity || 1);
      return { success: true, cartCount: result.totalItems };
    }
  }
]);

Algunas cosas que conviene saber:

• El agente ve tu herramienta con el prefijo client_ — así add_to_cart se expone al modelo como client_add_to_cart. Tú la sigues registrando y quitando por su nombre original.
• Lo que devuelve tu handler se envía de vuelta a la IA. Devuelve un objeto pequeño y estructurado (como { success: true, ... }) para que el agente explique qué pasó. Si tu handler no devuelve nada, okidoki reporta un simple "Done".
• El esquema input puede ser simple o detallado. La forma corta asigna a cada campo una descripción; la forma detallada (más abajo) te deja fijar un tipo y restringir los valores.

Ejemplo 1: llevar al visitante a una sección

Este es el patrón exacto que okidoki.chat usa en su propia landing. Cuando un visitante pregunta "¿dónde están los precios?", el agente lo desplaza hasta ahí en lugar de pegar un enlace:

OkidokiWidget.registerTools([
  {
    name: 'navigate_to_section',
    description: 'Desplaza al usuario a una sección de la página. Úsala cuando pida ver funciones, precios, cómo funciona o testimonios.',
    input: {
      section: {
        type: 'string',
        description: 'Una de: features, how-it-works, pricing, testimonials',
        enum: ['features', 'how-it-works', 'pricing', 'testimonials']
      }
    },
    handler: async (args) => {
      const el = document.getElementById(args.section);
      if (!el) return { success: false, error: 'Sección no encontrada: ' + args.section };
      el.scrollIntoView({ behavior: 'smooth', block: 'start' });
      return { success: true, message: 'Navegado a ' + args.section };
    }
  }
]);

Fíjate en el enum dentro del campo: restringe los valores que el modelo puede pasar, para que el agente solo navegue a secciones que realmente existen.

Ejemplo 2: abrir un modal (o el flujo de agendamiento)

Abrir interfaz es solo otro handler — dispara tu propio modal desde la IA:

OkidokiWidget.registerTools([
  {
    name: 'open_size_guide',
    description: 'Abre el modal de guía de tallas cuando el comprador duda qué talla elegir.',
    handler: async () => {
      myUI.openModal('size-guide');
      return { success: true };
    }
  }
]);

Para el agendamiento en particular, okidoki trae un método integrado — no necesitas una herramienta propia. Llámalo desde un botón o desde dentro de una herramienta tuya:

// Abre el modal de agendamiento
OkidokiWidget.scheduleMeeting();

// ...o preselecciona un tipo de evento por nombre
OkidokiWidget.scheduleMeeting('Discovery Call');

Ejemplo 3: capturar un lead o enviar un formulario

Puedes dejar que el agente envíe tu propio formulario mediante una herramienta, o usar el método integrado sendEmail() de okidoki para reenviar los datos capturados al correo conectado a tu app:

// Integrado: reenvía un lead al correo conectado a tu app.
// Requiere un campo de contacto (email o teléfono) y un mensaje de 3+ palabras;
// limitado a 5 envíos por hora por visitante.
OkidokiWidget.sendEmail({
  name: 'Jane Doe',
  email: 'jane@example.com',
  message: 'Me interesa el plan enterprise para un equipo de 40 personas.'
});

¿Prefieres tu propio backend? Registra una herramienta que haga POST a tu API y devuelva el resultado al agente, para que confirme el envío en lenguaje natural.

Ejemplo 4: consultar datos de tu empresa o usuario de forma programática

Las herramientas son bidireccionales: un handler puede leer datos y devolvérselos al agente para que sus respuestas se basen en tu app en vivo. Así logras que el agente "conozca" al usuario actual, su plan o detalles específicos de la empresa sin escribir nada a mano:

OkidokiWidget.registerTools([
  {
    name: 'get_current_user',
    description: 'Consulta al usuario con sesión iniciada para personalizar respuestas (nombre, plan, fecha de renovación).',
    handler: async () => {
      const user = await myApp.getSession();
      if (!user) return { signedIn: false };
      return {
        signedIn: true,
        name: user.name,
        plan: user.plan,
        renewsOn: user.renewsOn
      };
    }
  }
]);

Ahora, cuando un visitante pregunta "¿cuándo se renueva mi plan?", el agente llama a get_current_user, lee la respuesta desde tu app y contesta con la fecha real. La misma idea cubre los datos de la empresa: expón una herramienta get_store_hours o get_inventory_status que devuelva valores desde tus sistemas.

Tip: para contenido que ya vive en tu sitio web o en documentos que subiste, okidoki también puede buscar en tu base de conocimiento directamente con la API ask(). Usa una herramienta propia cuando el dato vive en el estado o el backend de tu app.

Controlar cómo se ejecutan las herramientas

Cada herramienta acepta ajustes de ejecución opcionales:

Opción	Qué hace
timeout	Milisegundos antes de cancelar la herramienta. Por defecto 60000 (60s), máximo 600000 (10 min) para trabajos largos.
lockGroup	Las herramientas que comparten un nombre de grupo nunca se ejecutan a la vez — úsalo para serializar handlers que escriben sobre el mismo estado.
parallel	Ponlo en true para herramientas de solo lectura que es seguro ejecutar junto a cualquier otra.

Para handlers lentos, cuéntale al visitante qué está pasando con setToolNotification():

OkidokiWidget.registerTools([
  {
    name: 'generate_report',
    timeout: 300000,
    lockGroup: 'reports',
    handler: async (args) => {
      OkidokiWidget.setToolNotification('Generando tu reporte...');
      const url = await myApp.buildReport(args);
      OkidokiWidget.setToolNotification(null);
      return { success: true, url: url };
    }
  }
]);

Registrar y limpiar

Registra las herramientas una vez que el widget esté listo, y quítalas cuando la vista desaparezca. En HTML plano:

<script src="https://okidoki.chat/embed/okidoki.js" data-app-id="TU_APP_ID"></script>
<script>
  function register() {
    if (!window.OkidokiWidget || !window.OkidokiWidget.registerTools) {
      return setTimeout(register, 500); // espera a que cargue el widget
    }
    window.OkidokiWidget.registerTools([ /* tus herramientas */ ]);
  }
  register();
</script>

En React, registra dentro de useEffect y devuelve una limpieza que las quite — exactamente como lo hace okidoki.chat en su propio sitio:

useEffect(() => {
  const w = window.OkidokiWidget;
  if (!w) return;
  w.registerTools([{ name: 'navigate_to_section', /* ... */ }]);
  return () => w.unregisterTools(['navigate_to_section']);
}, []);

Llamar a unregisterTools() sin argumentos elimina todas las herramientas que registraste. No hay un paquete npm aparte que instalar — la API de herramientas vive en el objeto global window.OkidokiWidget que crea el script de embed.

Buenas prácticas

• Escribe las descripciones para la IA, no para humanos. Deja claro cuándo usar la herramienta; el modelo lee esto para decidir.
• Valida los argumentos dentro del handler y devuelve un error estructurado ({ success: false, error: '...' }) en lugar de lanzar una excepción.
• Mantén las herramientas idempotentes cuando puedas, y usa lockGroup para cualquier cosa que modifique estado compartido.
• Devuelve objetos pequeños que el agente pueda convertir en una frase — no bloques enormes.
• Funcionan donde funcione el agente — las mismas herramientas corren en chat de texto, voz y video.

Hacia dónde seguir

La referencia completa de métodos y snippets listos para copiar están en la página para desarrolladores de okidoki, y hay una versión legible por máquinas para asistentes de programación con IA en llms-full.txt. Para una visión conceptual, mira qué es el AI Page Copilot.