Integración del Widget para Desarrolladores

Aprende cómo integrar el widget de AgentsGT en tu aplicación con personalización completa y funciones avanzadas.

El widget de AgentsGT es una interfaz de chat personalizable que puedes incrustar en cualquier aplicación web. Soporta múltiples modos de interfaz, acciones personalizadas, inyección de contexto y soporte multiidioma.

Construido con:

React 19
CopilotKit
TypeScript
Tailwind CSS

Métodos de Instalación

Método 1: Paquete NPM (Aplicaciones React)

Para aplicaciones React, instala el widget como un paquete npm:

npm install @ddrinnova/agentsgt-widget

Uso en React:

import { App as AgentSGTWidget } from "@ddrinnova/agentsgt-widget";
import "@ddrinnova/agentsgt-widget/dist/agentsgt-widget.css";

function MyApp() {
  return (
    <div>
      <h1>My Application</h1>
      <AgentSGTWidget
        title="My Assistant"
        initialMessage="How can I help you today?"
        runtimeUrl="https://agentsgt.com/api/copilotkit/your-agent-id"
        apiKey="your-api-key"
      />
    </div>
  );
}

Método 2: CDN (Cualquier Sitio Web)

Para cualquier sitio web, usa la versión CDN con un script simple:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>My Website</title>
</head>
<body>
  <!-- Your content -->

  <!-- Widget Container -->
  <div id="agentsgt-container"></div>

  <script>
    const widgetVersion = "0.1.6";
    const basePath = `https://cdn.jsdelivr.net/npm/@ddrinnova/agentsgt-widget@${widgetVersion}`;

    (function(w, d, c, v, o) {
      var l = d.createElement('link'),
          s = d.createElement('script');
      l.rel = 'stylesheet';
      l.href = v + '/dist/agentsgt-widget.css';
      s.src = v + '/dist/widget.umd.js';
      l.onload = function() { d.body.appendChild(s) };
      s.onload = function() {
        w.AgentSGTWidget && w.AgentSGTWidget.loadWidget(c, o)
      };
      d.head.appendChild(l);
    })(window, document, 'agentsgt-container', basePath, {
      name: 'My Assistant',
      initialMessage: 'How can I help?',
      runtimeUrl: 'https://agentsgt.com/api/copilotkit/your-agent-id',
      apiKey: 'your-api-key',
      basePath: basePath
    });
  </script>
</body>
</html>

Opciones de Configuración

Configuración Básica

Opción	Tipo	Requerido	Descripción
`title`	string	No	El título mostrado en el encabezado del widget
`initialMessage`	string	No	El primer mensaje mostrado en el chat
`runtimeUrl`	string	Sí	La URL de runtime de tu agente en AgentsGT
`apiKey`	string	Sí	Tu API key de AgentsGT
`basePath`	string	No	Ruta base para cargar los recursos del widget (solo CDN)

Ejemplo:

{
  title: "Support Assistant",
  initialMessage: "Hi! How can I help you today?",
  runtimeUrl: "https://agentsgt.com/api/copilotkit/asst_abc123",
  apiKey: "pk_xxx:sk_yyy"
}

Modos de Interfaz

El widget soporta tres modos de interfaz diferentes:

Modo	Descripción	Caso de Uso
`popup`	Burbuja de chat flotante (predeterminado)	La mayoría de los sitios web
`sidebar`	Panel lateral fijo	Paneles de control, paneles de administración
`chat`	Interfaz de chat en pantalla completa	Páginas de chat dedicadas

Ejemplo:

{
  // ... other options
  uiMode: "sidebar" // or "popup" or "chat"
}

Una pequeña burbuja de chat que flota en la esquina de la pantalla.

{
  uiMode: "popup", // or omit this option
  title: "Chat with us",
  initialMessage: "Need help?"
}

Un panel lateral fijo que se desliza desde el costado.

{
  uiMode: "sidebar",
  title: "Assistant",
  initialMessage: "How can I assist you?"
}

Modo Chat

Interfaz de chat en pantalla completa que ocupa todo el contenedor.

{
  uiMode: "chat",
  title: "Customer Support",
  initialMessage: "Welcome! Ask me anything."
}

Funciones Avanzadas

Propiedades (Inyección de Contexto)

Las propiedades te permiten inyectar contexto personalizado en el conocimiento del agente. El agente puede acceder a estos datos al responder a los usuarios.

Estructura:

properties: {
  propertyName: {
    value: any,           // The actual data
    description: string   // What this data represents
  }
}

Ejemplo - Contexto del Usuario:

{
  properties: {
    user: {
      value: "John Doe",
      description: "The current user's name"
    },
    userEmail: {
      value: "john@example.com",
      description: "The user's email address"
    },
    accountType: {
      value: "Premium",
      description: "The user's subscription level"
    }
  }
}

Ejemplo - Catálogo de Productos:

{
  properties: {
    products: {
      value: [
        { id: 1, name: "Product A", price: 29.99, stock: 15 },
        { id: 2, name: "Product B", price: 49.99, stock: 8 },
        { id: 3, name: "Product C", price: 19.99, stock: 50 }
      ],
      description: "Available products in the catalog"
    },
    storeLocation: {
      value: "New York, NY",
      description: "Current store location"
    }
  }
}

Ejemplo - Instrucciones Personalizadas:

{
  properties: {
    instructions: {
      value: "You are a helpful assistant for TechStore. Always be polite and offer to help with product recommendations. If asked about shipping, mention we offer free shipping over $50.",
      description: "Additional instructions for the assistant's behavior"
    }
  }
}

¡El agente automáticamente tendrá acceso a estos datos y podrá referenciarlos en sus respuestas!

Acciones (Funciones Personalizadas)

Las acciones permiten al agente ejecutar funciones JavaScript personalizadas en tu aplicación. Esto habilita funciones interactivas como abrir URLs, enviar formularios o llamar a APIs.

Estructura:

actions: [
  {
    name: string,           // Unique action name
    description: string,    // What this action does
    parameters: [           // Array of parameters
      {
        name: string,
        type: "string" | "number" | "boolean" | "object",
        description: string
      }
    ],
    handler: (args) => any, // Function to execute
    render: (opts) => ReactElement | string // Optional: custom rendering
  }
]

Ejemplo - Abrir URL:

{
  actions: [
    {
      name: "openUrl",
      description: "Open a URL in a new browser tab",
      parameters: [
        {
          name: "url",
          type: "string",
          description: "The URL to open"
        }
      ],
      handler: ({ url }) => {
        window.open(url, "_blank");
        return { success: true, message: "Opened URL" };
      }
    }
  ]
}

Ejemplo - Buscar Productos:

{
  actions: [
    {
      name: "searchProducts",
      description: "Search for products in the catalog",
      parameters: [
        {
          name: "query",
          type: "string",
          description: "Search term"
        },
        {
          name: "maxResults",
          type: "number",
          description: "Maximum number of results to return"
        }
      ],
      handler: async ({ query, maxResults }) => {
        // Call your API
        const response = await fetch(`/api/products/search?q=${query}&limit=${maxResults}`);
        const products = await response.json();
        return { success: true, products };
      }
    }
  ]
}

Ejemplo - Enviar Formulario:

{
  actions: [
    {
      name: "submitContactForm",
      description: "Submit a contact form with user information",
      parameters: [
        {
          name: "name",
          type: "string",
          description: "User's full name"
        },
        {
          name: "email",
          type: "string",
          description: "User's email address"
        },
        {
          name: "message",
          type: "string",
          description: "The message content"
        }
      ],
      handler: async ({ name, email, message }) => {
        const response = await fetch('/api/contact', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ name, email, message })
        });

        if (response.ok) {
          return { success: true, message: "Form submitted successfully!" };
        } else {
          throw new Error("Failed to submit form");
        }
      }
    }
  ]
}

Ejemplo - Mostrar Notificación:

{
  actions: [
    {
      name: "showNotification",
      description: "Display a browser notification to the user",
      parameters: [
        {
          name: "title",
          type: "string",
          description: "Notification title"
        },
        {
          name: "body",
          type: "string",
          description: "Notification message"
        }
      ],
      handler: ({ title, body }) => {
        if ('Notification' in window && Notification.permission === 'granted') {
          new Notification(title, { body });
          return { success: true };
        } else {
          return { success: false, message: "Notifications not supported" };
        }
      }
    }
  ]
}

¡El agente determinará inteligentemente cuándo ejecutar estas acciones basándose en los mensajes del usuario!

Componentes Personalizados (Solo React)

Para aplicaciones React, puedes inyectar componentes React personalizados que se renderizarán dentro del widget.

{
  customComponents: [
    {
      name: "customHeader",
      component: MyCustomHeader,
      props: { theme: "dark" }
    }
  ]
}

Renderizado de Tarjetas

Habilita el renderizado de interfaz basado en tarjetas para mostrar datos estructurados visualmente.

{
  enableCardsRender: true,
  cardsJson: {
    context_array: [
      {
        title: "Product A",
        description: "Amazing product",
        image: "https://example.com/image.jpg",
        price: "$29.99"
      },
      // More cards...
    ]
  }
}

Cuando está habilitado, el agente puede mostrar tarjetas en el chat para una mejor presentación visual.

Ejemplo Completo

Aquí hay un ejemplo completo que combina múltiples funciones:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My E-commerce Site</title>
</head>
<body>
  <h1>Welcome to TechStore</h1>

  <div id="agentsgt-container"></div>

  <script>
    // Define context data
    const userContext = {
      user: {
        value: "Jane Smith",
        description: "Current user's name"
      },
      cartItems: {
        value: 3,
        description: "Number of items in shopping cart"
      },
      products: {
        value: [
          { id: 1, name: "Laptop", price: 999, inStock: true },
          { id: 2, name: "Mouse", price: 29, inStock: true },
          { id: 3, name: "Keyboard", price: 79, inStock: false }
        ],
        description: "Available products"
      },
      instructions: {
        value: "You are a helpful shopping assistant. Help users find products and answer questions about orders. Always mention free shipping for orders over $100.",
        description: "Assistant behavior instructions"
      }
    };

    // Define custom actions
    const customActions = [
      {
        name: "addToCart",
        description: "Add a product to the shopping cart",
        parameters: [
          { name: "productId", type: "number", description: "The product ID" },
          { name: "quantity", type: "number", description: "Quantity to add" }
        ],
        handler: async ({ productId, quantity }) => {
          const response = await fetch('/api/cart/add', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ productId, quantity })
          });

          if (response.ok) {
            return { success: true, message: `Added ${quantity} item(s) to cart` };
          } else {
            throw new Error("Failed to add to cart");
          }
        }
      },
      {
        name: "viewProduct",
        description: "Navigate to a product detail page",
        parameters: [
          { name: "productId", type: "number", description: "The product ID" }
        ],
        handler: ({ productId }) => {
          window.location.href = `/products/${productId}`;
        }
      },
      {
        name: "checkShipping",
        description: "Check shipping status for an order",
        parameters: [
          { name: "orderId", type: "string", description: "The order ID" }
        ],
        handler: async ({ orderId }) => {
          const response = await fetch(`/api/orders/${orderId}/shipping`);
          const data = await response.json();
          return {
            success: true,
            status: data.status,
            estimatedDelivery: data.estimatedDelivery
          };
        }
      }
    ];

    // Load the widget
    const widgetVersion = "0.1.6";
    const basePath = `https://cdn.jsdelivr.net/npm/@ddrinnova/agentsgt-widget@${widgetVersion}`;

    (function(w, d, c, v, o) {
      var l = d.createElement('link'),
          s = d.createElement('script');
      l.rel = 'stylesheet';
      l.href = v + '/dist/agentsgt-widget.css';
      s.src = v + '/dist/widget.umd.js';
      l.onload = function() { d.body.appendChild(s) };
      s.onload = function() {
        w.AgentSGTWidget && w.AgentSGTWidget.loadWidget(c, o)
      };
      d.head.appendChild(l);
    })(window, document, 'agentsgt-container', basePath, {
      title: 'Shopping Assistant',
      initialMessage: 'Hi! I can help you find products and track orders.',
      runtimeUrl: 'https://agentsgt.com/api/copilotkit/your-agent-id',
      apiKey: 'your-api-key',
      basePath: basePath,
      uiMode: 'popup',
      properties: userContext,
      actions: customActions
    });
  </script>
</body>
</html>

Soporte Multiidioma

El widget detecta automáticamente la configuración de idioma del agente y ajusta la interfaz en consecuencia.

Idiomas Soportados:

English
Spanish (Español)
French (Français)
German (Deutsch)
Portuguese (Português)
Italian (Italiano)

El idioma se configura automáticamente basándose en la configuración de idioma de tu agente en AgentsGT. ¡No se requiere configuración adicional!

Persistencia de Sesión

El widget guarda automáticamente el historial de conversaciones en el almacenamiento de sesión del navegador. Esto significa:

Las conversaciones persisten durante la navegación entre páginas (misma sesión)
Sin pérdida de datos cuando los usuarios actualizan la página
Limpieza automática cuando la sesión del navegador termina

Los datos de sesión se almacenan localmente y nunca se envían a servidores externos (excepto los mensajes en sí a tu agente).

Obteniendo Tus Credenciales

Runtime URL

Tu URL de runtime está disponible en AgentsGT:

Ve a tu agente en AgentsGT
Haz clic en Integrations
Haz clic en Embed Code
Copia el runtimeUrl del fragmento de código

Se ve así: https://agentsgt.com/api/copilotkit/asst_xxxxx

API Key

Tu API key está disponible en la configuración de tu organización:

Ve a Settings → API Keys en AgentsGT
Crea una nueva API key si no tienes una
Copia la clave completa (formato: pk_xxx:sk_yyy)

Nota de Seguridad: ¡Nunca expongas tu clave secreta (sk_) en código del lado del cliente! Para sitios web públicos, crea una API key separada con permisos limitados.

Mejores Prácticas

1. Mantén las API Keys Seguras

Para sitios web en producción:

Usa variables de entorno para las API keys
Crea API keys separadas para desarrollo y producción
Rota las claves periódicamente
Nunca subas las claves al control de versiones

2. Optimiza los Datos de Contexto

Al usar propiedades:

Solo incluye los datos que el agente necesita
Mantén las estructuras de datos simples
Evita arreglos u objetos enormes
Actualiza el contexto dinámicamente cuando los datos cambien

3. Manejo de Errores en Acciones

Siempre maneja los errores en los handlers de acciones:

{
  name: "myAction",
  handler: async (args) => {
    try {
      const result = await doSomething(args);
      return { success: true, result };
    } catch (error) {
      console.error('Action failed:', error);
      return {
        success: false,
        message: "Sorry, something went wrong."
      };
    }
  }
}

4. Prueba Diferentes Modos de Interfaz

Prueba los tres modos de interfaz para encontrar el que mejor funcione para tu caso de uso:

Popup: Ideal para sitios web en general
Sidebar: Perfecto para paneles de control y aplicaciones SaaS
Chat: Ideal para páginas de soporte o secciones de chat dedicadas

5. Mejora Progresiva

Carga el widget de forma asíncrona para evitar bloquear la carga de la página:

El widget se carga después del contenido de la página
Degradación elegante si JavaScript está deshabilitado
Sin impacto en el tiempo de renderizado inicial de la página

6. Monitorea el Rendimiento

Mantén un ojo en:

Tiempo de carga del widget
Tiempo de ejecución de acciones
Métricas de interacción del usuario
Tasas de error en los handlers de acciones

Solución de Problemas

Verifica:

El elemento contenedor existe (<div id="agentsgt-container"></div>)
La URL de runtime es correcta
La API key es válida
No hay errores de JavaScript en la consola
El CDN es accesible (revisa la pestaña de red)

El Agente No Responde

Verifica:

El agente está activo en AgentsGT
Tienes suficientes créditos
La URL de runtime coincide con el ID de tu agente
La API key tiene los permisos adecuados

Las Acciones No Funcionan

Verifica:

El handler de la acción está definido correctamente
Los tipos de parámetros coinciden
El handler retorna el formato correcto
Revisa la consola por errores
La descripción de la acción es clara para la IA

El Contexto No Está Disponible

Verifica:

Las propiedades están formateadas correctamente
Se proporcionan valor y descripción
Los datos son serializables (sin funciones o referencias circulares)
Intenta registrar el objeto de propiedades en la consola

Soporte para TypeScript

El widget está construido con TypeScript y exporta todos los tipos necesarios:

import { App as AgentSGTWidget } from "@ddrinnova/agentsgt-widget";
import type {
  CopilotPropertyConfig,
  CopilotActionConfig,
  ChatMessage
} from "@ddrinnova/agentsgt-widget";

const properties: Record<string, CopilotPropertyConfig> = {
  user: {
    value: "John",
    description: "User name"
  }
};

const actions: CopilotActionConfig[] = [
  {
    name: "myAction",
    description: "Does something",
    parameters: [
      { name: "param", type: "string", description: "A parameter" }
    ],
    handler: async (args) => {
      // Typed args
      return { success: true };
    }
  }
];

¿Qué Sigue?

Ahora que sabes cómo integrar el widget con funciones avanzadas:

Referencia de la API - Accede a datos de conversaciones programáticamente
Desplegar en WhatsApp - Llega a los usuarios en WhatsApp también
Desplegar en la Web - Guía simple de despliegue web

¿Necesitas ayuda? Contacta a soporte o revisa nuestro repositorio en GitHub para ejemplos y reportes de problemas.

Integración del Widget para Desarrolladores

¿Qué es el Widget de AgentsGT?

Métodos de Instalación

Método 1: Paquete NPM (Aplicaciones React)

Método 2: CDN (Cualquier Sitio Web)

Opciones de Configuración

Configuración Básica

Modos de Interfaz

Modo Sidebar

Modo Chat

Funciones Avanzadas

Propiedades (Inyección de Contexto)

Acciones (Funciones Personalizadas)

Componentes Personalizados (Solo React)

Renderizado de Tarjetas

Ejemplo Completo

Soporte Multiidioma

Persistencia de Sesión

Obteniendo Tus Credenciales

Runtime URL

API Key

Mejores Prácticas

1. Mantén las API Keys Seguras

2. Optimiza los Datos de Contexto

3. Manejo de Errores en Acciones

4. Prueba Diferentes Modos de Interfaz

5. Mejora Progresiva

6. Monitorea el Rendimiento

Solución de Problemas

El Widget No Carga

El Agente No Responde

Las Acciones No Funcionan

El Contexto No Está Disponible

Soporte para TypeScript

¿Qué Sigue?

¿Qué es el Widget de AgentsGT?​

Métodos de Instalación​

Método 1: Paquete NPM (Aplicaciones React)​

Método 2: CDN (Cualquier Sitio Web)​

Opciones de Configuración​

Configuración Básica​

Modos de Interfaz​

Modo Popup (Predeterminado)​

Modo Sidebar​

Modo Chat​

Funciones Avanzadas​

Propiedades (Inyección de Contexto)​

Acciones (Funciones Personalizadas)​

Componentes Personalizados (Solo React)​

Renderizado de Tarjetas​

Ejemplo Completo​

Soporte Multiidioma​

Persistencia de Sesión​

Obteniendo Tus Credenciales​

Runtime URL​

API Key​

Mejores Prácticas​

1. Mantén las API Keys Seguras​

2. Optimiza los Datos de Contexto​

3. Manejo de Errores en Acciones​

4. Prueba Diferentes Modos de Interfaz​

5. Mejora Progresiva​

6. Monitorea el Rendimiento​

Solución de Problemas​

El Widget No Carga​

El Agente No Responde​

Las Acciones No Funcionan​

El Contexto No Está Disponible​

Soporte para TypeScript​

¿Qué Sigue?​

¿Qué es el Widget de AgentsGT?

Métodos de Instalación

Método 1: Paquete NPM (Aplicaciones React)

Método 2: CDN (Cualquier Sitio Web)

Opciones de Configuración

Configuración Básica

Modos de Interfaz

Modo Popup (Predeterminado)

Modo Sidebar

Modo Chat

Funciones Avanzadas

Propiedades (Inyección de Contexto)

Acciones (Funciones Personalizadas)

Componentes Personalizados (Solo React)

Renderizado de Tarjetas

Ejemplo Completo

Soporte Multiidioma

Persistencia de Sesión

Obteniendo Tus Credenciales

Runtime URL

API Key

Mejores Prácticas

1. Mantén las API Keys Seguras

2. Optimiza los Datos de Contexto

3. Manejo de Errores en Acciones

4. Prueba Diferentes Modos de Interfaz

5. Mejora Progresiva

6. Monitorea el Rendimiento

Solución de Problemas

El Widget No Carga

El Agente No Responde

Las Acciones No Funcionan

El Contexto No Está Disponible

Soporte para TypeScript

¿Qué Sigue?