> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puente.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Crea agentes IA conversacionales con prompt personalizado y publícalos como widget embebible en cualquier sitio web.

**Agents** te permite crear agentes de IA conversacionales con un prompt personalizado, probarlos en tiempo real y publicarlos como un widget de chat embebible en cualquier sitio web.

## Interfaz

La pantalla está dividida en dos columnas redimensionables:

<Frame>
  <img src="https://mintcdn.com/puenteos/MFY1kiPfI9fyixWy/images/Screenshot-2026-06-03-at-3.51.45-PM.png?fit=max&auto=format&n=MFY1kiPfI9fyixWy&q=85&s=96819ec51ba6ad325cdef40d2152f787" alt="Screenshot 2026 06 03 At 3 51 45 PM" width="1552" height="849" data-path="images/Screenshot-2026-06-03-at-3.51.45-PM.png" />
</Frame>

* **Izquierda** — Chat para probar el agente con la configuración actual (no necesitas guardar primero).
* **Derecha** — Donde defines identidad, instrucciones y modelo.

<Tip>
  Arrastra el divisor entre columnas para ajustar el espacio (mínimo 200px, máximo 600px).
</Tip>

***

## Crear un agente

<Steps>
  <Step title="Abre Agents">
    Desde el panel de Componentes de un proyecto → **+ Nuevo** → **Agent**.
  </Step>

  <Step title="Nombra el agente">
    En el campo de la parte superior. Es obligatorio para guardar.
  </Step>

  <Step title="Agrega una descripción (opcional)">
    Una nota breve sobre para qué sirve el agente.
  </Step>

  <Step title="Define las instrucciones">
    Elige modo **Inteligente** o **Manual** (ver siguiente sección).
  </Step>

  <Step title="Selecciona el modelo">
    Default recomendado para la mayoría de casos.
  </Step>

  <Step title="Click en Crear agente">
    El agente queda guardado y listo para publicar como widget.
  </Step>
</Steps>

<Warning>
  El nombre del agente es obligatorio. Si intentas guardar sin él, el campo se resaltará en rojo.
</Warning>

***

## Instrucciones — Modo Inteligente

Divide el prompt en **6 campos estructurados** para evitar prompts monolíticos difíciles de mantener:

| Campo                             | Para qué sirve                              | Ejemplo                                                 |
| --------------------------------- | ------------------------------------------- | ------------------------------------------------------- |
| **Rol del Agente**                | Quién es el agente, perfil y estilo         | "Eres un asistente de ventas experto en SaaS"           |
| **Tarea u Objetivo**              | Qué debe lograr en cada interacción         | "Tu tarea es calificar leads y agendar demos"           |
| **Contexto y Entorno**            | Info de fondo: empresa, producto, audiencia | "Trabajas para Puente OS, plataforma de automatización" |
| **Guías y Buenas Prácticas**      | Tono, estilo, estructura                    | "Sé conciso. Usa listas cuando sea apropiado"           |
| **Restricciones y Prohibiciones** | Lo que NO debe hacer                        | "No inventes precios. No hagas promesas sin confirmar"  |
| **Formato de Salida**             | Cómo estructurar respuestas                 | "Siempre termina con una pregunta de seguimiento"       |

### Editar un campo

Click en el icono de lápiz a la derecha del campo. Se despliega un textarea. Click en el icono de colapsar para cerrarlo.

<Note>
  Cada campo muestra una preview truncada del contenido cuando está colapsado.
</Note>

***

## Instrucciones — Modo Manual

Textarea libre donde escribes el prompt completo. Útil cuando ya tienes un prompt afinado que quieres pegar directo.

### Transiciones entre modos

| Dirección                | Qué pasa                                                                                                             |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| **Inteligente → Manual** | Los 6 campos se compilan en un prompt con etiquetas `[ROLE]`, `[TASK]`, etc. y se cargan en el textarea              |
| **Manual → Inteligente** | El sistema intenta parsear las etiquetas `[TAG]` y distribuirlas. Si no hay etiquetas, todo va al campo **Contexto** |

<Tip>
  Cambiar de modo no borra tu trabajo. Siempre hay una conversión automática.
</Tip>

***

## Chat de prueba

La columna izquierda incluye un chat que envía mensajes al modelo con el prompt actual — **incluso si no guardaste**.

### Cómo usarlo

<Steps>
  <Step title="Escribe tu mensaje">
    En el campo de texto inferior.
  </Step>

  <Step title="Envía">
    Presiona `Enter` o el botón de enviar.
  </Step>

  <Step title="Itera">
    Modifica el prompt en la columna derecha y prueba inmediatamente sin guardar.
  </Step>
</Steps>

### Controles

* **Botón de reiniciar** en el header del chat: borra toda la conversación y empieza de cero
* El historial se incluye en cada petición, manteniendo contexto

<Tip>
  El chat de prueba usa el prompt **actual** del editor. El widget publicado usa el prompt **guardado**. Guarda antes de publicar para que ambos coincidan.
</Tip>

***

## Seleccionar el modelo

En la sección **Modelo** de la columna derecha eliges qué modelo de IA usa el agente:

| Modelo                           | Cuándo usarlo                                     |
| -------------------------------- | ------------------------------------------------- |
| **Llama 3.3 Nemotron Super 49B** | Alta capacidad, recomendado para tareas complejas |
| **GPT OSS 120B**                 | Modelo grande de OpenAI                           |
| **Gemini 3 Flash**               | Rápido y eficiente para respuestas ágiles         |

<Note>
  Default recomendado para la mayoría de casos. Escribe a soporte si necesitas un modelo específico que no aparece en el selector.
</Note>

***

## Publicar como widget

Una vez guardado el agente, puedes publicarlo como **widget de chat embebible** en cualquier sitio web (Webflow, Framer, WordPress, custom HTML, etc.).

### Abrir la configuración del widget

Click en **Configurar Widget** en el footer de la columna de configuración.

Se abre un modal con dos paneles: **Configuración** (izquierda) y **Preview** (derecha). La preview se actualiza en tiempo real con cada cambio.

***

### Secciones de configuración

<AccordionGroup>
  <Accordion title="Webhook">
    URL del agente en el backend, pre-llenada automáticamente. No necesitas editarla. Formato: `https://backend.../chat/{public_id}`.
  </Accordion>

  <Accordion title="Marca">
    Personaliza visualmente el widget:

    * **Título** — texto en la cabecera del chat
    * **URL del Logo** — imagen de tu marca
    * **Ancho / Alto del Logo** — en CSS (`120px`, `35px`)
    * **Texto de Bienvenida** — título de la pantalla inicial
    * **Tiempo de Respuesta** — subtítulo (ej. "Respondemos siempre")
    * **Placeholder del Input** — texto guía del campo de mensaje
    * **Texto de botones** — Enviar, Cargando, Error, Nueva Conversación
  </Accordion>

  <Accordion title="Mensajes">
    * **Mensaje Inicial** — lo que el agente envía al abrir el chat por primera vez
    * **Mensaje Proactivo** — burbuja flotante antes de abrir el chat, posicionable arriba o al lado del botón
  </Accordion>

  <Accordion title="Estilo">
    * **Posición del Widget** — derecha o izquierda
    * **Distancia desde el fondo** — en CSS (ej. `20px`)
    * **Colores** — primario, secundario, fondo, fuente (selector visual + hex)
  </Accordion>

  <Accordion title="Markdown">
    Activa renderizado de Markdown en las respuestas del agente: **negrita**, listas, `código`, etc.
  </Accordion>

  <Accordion title="Botones del Menú">
    Botones de acceso rápido en el chat. Cada uno puede ser:

    * **URL** — abre un enlace externo
    * **Chat** — envía un mensaje predefinido al agente

    Agrega con **+ Agregar Botón**, elimina con el botón de eliminar.
  </Accordion>
</AccordionGroup>

***

### Obtener el código

<Steps>
  <Step title="Ajusta la configuración">
    Hasta que la preview lateral se vea como quieres.
  </Step>

  <Step title="Copia el snippet">
    Click en **Copiar Código**.
  </Step>

  <Step title="Guarda la configuración">
    Click en **Guardar** para conservar los ajustes del widget.
  </Step>

  <Step title="Pega antes del </body>">
    En tu sitio web. El widget aparece como burbuja flotante.
  </Step>
</Steps>

### Estructura del snippet

```html theme={null}
<script>
window.ChatWidgetConfig = {
  "webhook": { "url": "https://backend.../chat/{public_id}", ... },
  "branding": { "name": "Puente OS", ... },
  "style": { "primaryColor": "#0d0d0d", ... },
  "menu": { "buttons": [...] },
  "markdown": { "enabled": true }
};
</script>
<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dompurify@2.4.0/dist/purify.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/octaviofv/chat_widget_puente/script_puente.js"></script>
```

<Tip>
  Pega este código **antes del cierre del `</body>`** en tu sitio web.
</Tip>

***

## Editar un agente existente

Abrir un agente carga automáticamente su configuración. El botón de guardado cambia a **Guardar cambios** y solo se actualizan los campos que modificaste (título, descripción, prompt).

***

## Estados del botón Guardar

| Estado    | Texto                              | Color           |
| --------- | ---------------------------------- | --------------- |
| Normal    | "Crear agente" / "Guardar cambios" | Negro           |
| Guardando | "Guardando…"                       | Gris oscuro     |
| Éxito     | "Guardado"                         | Verde (2.5 seg) |

Si ocurre un error, se muestra el mensaje en rojo junto al botón.

<Note>
  Si la URL de la página incluye `?project=N`, el agente recién creado se asocia automáticamente a ese proyecto.
</Note>

***

## Créditos

Los **créditos** se consumen al **crear** un agente y cada vez que un usuario interactúa con el **widget publicado**. Las pruebas en el chat interno y las ediciones del agente **no consumen créditos**, así que puedes iterar las instrucciones libremente.

***

## Casos de uso comunes

<CardGroup cols={2}>
  <Card title="Soporte automatizado" icon="headset">
    Embebe el widget en tu sitio para responder preguntas frecuentes 24/7.
  </Card>

  <Card title="Calificador de leads" icon="filter">
    Configura el agente para hacer preguntas que califiquen leads antes de agendar.
  </Card>

  <Card title="Asistente interno" icon="building">
    Publica el widget en herramientas internas para que el equipo consulte procesos.
  </Card>

  <Card title="Onboarding de usuarios" icon="graduation-cap">
    Guía paso a paso a los usuarios nuevos en tu producto.
  </Card>
</CardGroup>

***

## Preguntas frecuentes

<AccordionGroup>
  <Accordion title="¿Qué modelos puedo usar?">
    El selector incluye Llama 3.3 Nemotron Super 49B, GPT OSS 120B y Gemini 3 Flash, según tu plan. Escribe a soporte si necesitas un modelo específico.
  </Accordion>

  <Accordion title="¿Puedo conectar el agente a una Database del workspace?">
    En esta versión el agente responde solo con el contexto del prompt. Para que use datos en vivo, configura un workflow que llame al agente con el contexto correcto y embebe el chat conectado a ese workflow.
  </Accordion>

  <Accordion title="¿El widget usa mi última edición?">
    El widget publicado usa el prompt **guardado** en el backend, no el del editor. Guarda siempre antes de publicar para que reflejen lo mismo.
  </Accordion>

  <Accordion title="¿Cuánto tiempo se guarda el historial de chat?">
    El historial se mantiene durante la sesión del navegador del usuario. No se persiste entre sesiones a menos que configures el storage manualmente.
  </Accordion>

  <Accordion title="¿Funciona el widget en mobile?">
    Sí. El widget es responsive por default. En pantallas pequeñas se abre en pantalla completa.
  </Accordion>

  <Accordion title="¿Puedo customizar más el widget?">
    Todos los textos, colores y mensajes son configurables desde el modal. Para customizaciones más profundas (CSS custom, eventos JS), escribe a soporte.
  </Accordion>
</AccordionGroup>