Guía completa sobre la configuración del agente de IA en Plazbot
Este documento describe la estructura y configuración del archivo agent.config.json
, utilizado para definir completamente un Agente de IA en Plazbot. Un agente puede estar vinculado a un portal web, widget o canal de mensajería como WhatsApp o cualquier software que tenga.
Puedes descargar nuestro repositorio de ejemplo para crear tus agentes.
El agente es la parte más importante del SDK. Aquí podrás crear agentes de IA con características específicas e implementarlos en diferentes canales, como el Portal de IA, un widget o WhatsApp. También puedes usar nuestro agente en cualquiera de tus herramientas empresariales internas, si lo deseas.
Para trabajar con los agentes, existe un archivo JSON que funciona como el configurador inicial del agente y tiene la siguiente estructura. No es necesario completar todo el archivo, pero puedes configurar tu agente como prefieras.
Puedes entrenar al agente como necesites, ya sea a través de nuestro configurador o si quieres configurarlo todo en una sola línea de comandos; no es necesario usar todos los campos del archivo de configuración.
✅ También proporcionamos un archivo básico para que lo uses en el Repositorio de Github.
agent.config.json
services
)Los servicios permiten que el agente recolecte información del usuario paso a paso y luego llame a APIs externas. Son ideales para procesos como reservas, registros, consultas que requieren datos específicos.
Campo | Tipo | Requerido | Descripción |
---|---|---|---|
intent | string | ✅ Sí | Identificador único del servicio. |
reference | string | ✅ Sí | Descripción para que la IA entienda cuándo usar este servicio. |
enabled | boolean | ✅ Sí | Si el servicio está activo. |
method | string | ✅ Sí | Método HTTP (GET , POST , PUT , DELETE ). |
requiredFields | array | ✅ Sí | Campos que el agente debe recolectar del usuario. |
endpoint | string | ✅ Sí | URL de la API externa a llamar. |
headers | object | ❌ No | Headers HTTP (Authorization, Content-Type, etc.). |
bodyTemplate | object | ❌ No | Estructura del body usando las variables recolectadas. |
responseMapping | object | ❌ No | Mapeo de la respuesta usando JSONPath. |
responseMessage | string | ❌ No | Mensaje base de respuesta exitosa. |
responseConditions | array | ❌ No | Respuestas condicionales según el resultado de la API. |
action | string | ❌ No | Acción a ejecutar después del servicio. |
Para más información detallada sobre servicios, consulta la documentación completa de Services.
actions
)Las acciones permiten que el agente ejecute tareas específicas en respuesta a intenciones del usuario. Son especialmente útiles para automatizar procesos como asignar etiquetas, cambiar estados de contactos o integrar con sistemas externos.
Campo | Tipo | Requerido | Descripción |
---|---|---|---|
intent | string | ✅ Sí | Identificador único de la acción. |
reference | string | ✅ Sí | Descripción detallada para que la IA entienda cuándo usar esta acción. |
tags | array | ❌ No | Etiquetas para clasificar la acción. |
enabled | boolean | ✅ Sí | Si la acción está activa. |
responseMessage | string | ❌ No | Mensaje de respuesta fijo (solo si responseIA = false ). |
responseIA | boolean | ❌ No | Si debe continuar con IA después de ejecutar (true ) o usar solo responseMessage (false ). |
responseJson | boolean | ❌ No | Si responder en formato JSON estructurado (true ) o texto plano (false ). |
action | array | ✅ Sí | Lista de acciones a ejecutar. |
Tipo | Descripción | Valor Esperado |
---|---|---|
action.tag | Asigna una etiqueta al contacto | Nombre de la etiqueta |
action.stage | Cambia la fase del contacto | Nombre de la fase |
action.asign | Asigna un agente humano | Email del agente |
action.segmentation | Asigna una segmentación | Nombre de la segmentación |
action.agentShutDown | Apaga el agente de IA | "true" |
responseIA = true (Recomendado para la mayoría de casos):
responseIA = false + responseJson = false:
responseIA = false + responseJson = true:
Para más información detallada sobre acciones, consulta la documentación completa de Actions.
channels
)Los canales definen dónde y cómo tu agente puede comunicarse con los usuarios.
Campo | Tipo | Requerido | Descripción |
---|---|---|---|
channel | string | ✅ Sí | Tipo de canal: whatsapp , telegram , messenger , etc. |
key | string | ✅ Sí | Identificador del canal (número de teléfono para WhatsApp). |
Campo | Descripción |
---|---|
name | Nombre del agente. Visible en el panel. Requerido |
prompt | Instrucciones base para el comportamiento del agente. Requerido |
buffer | Cantidad de mensajes que se mantienen como contexto. Rango: 3 a 10. Requerido |
color | Color de presentación. Valores: blue , orange , gray , green , white . |
question | Pregunta principal que se muestra en el portal. |
description | Descripción general del agente. |
zone | Zona donde opera el agente: LA (Latinoamérica) o EU (Europa). Requerido |
timezone | Zona horaria. Ejemplo: America/Lima . TimeZone Formats |
tags | Etiquetas internas para clasificar agentes. |
examples | Preguntas sugeridas. Hasta 5. |
showInChat | Si el agente se muestra en el widget/chat. (boolean) |
instructions
)Campo | Tipo | Descripción |
---|---|---|
tone | string | Tono de comunicación: professional , friendly , etc. |
style | string | Estilo de respuestas: short answers , detailed . |
personality | string | Personalidad del agente. |
objective | string | Objetivo principal del agente. |
language | string | Idioma en que debe responder. Ver tabla de idiomas. |
emojis | boolean | Si puede usar emojis. |
preferredFormat | string | plain text o markdown . |
maxWords | number | Máximo de palabras por respuesta. |
avoidTopics | array | Lista de temas prohibidos. |
respondOnlyIfKnows | boolean | Si debe evitar responder sin información confiable. |
maintainToneBetweenMessages | boolean | Mantiene el mismo tono entre mensajes. |
greeting | string | Mensaje de bienvenida. |
Opciones Objetive “help with clarity” Enfocado en brindar respuestas claras “sell more” Promociona productos o servicios “support users” Ayuda a resolver problemas “guide actions” Brinda pasos concretos o instrucciones
Opciones Personalidad “friendly” Agradable y empático “serious” Reservado y directo “funny” Con toques de humor sutil “robotic” Más neutral, tipo IA técnica
Opciones preferredFormat “plain text” Texto simple “markdown” Permite negritas, listas, enlaces “html” Usado si se integrará en un entorno web
Opciones Style “short answers” Respuestas breves y directas “detailed” Respuestas explicativas, útiles para asistencia técnica “bullet points” Instrucciones u opciones en lista (ideal para pasos o listas) “conversational” Estilo fluido y natural, más humano
Opciones Tono “professional” Tono formal, educado, propio para empresas “friendly” Tono amigable, cercano, ideal para atención al cliente “casual” Informal, con lenguaje relajado y natural “neutral” Objetivo, sin inclinación emocional
person
)Campo | Tipo | Descripción |
---|---|---|
name | string | Nombre que usará el agente. |
role | string | Rol representado. |
speaksInFirstPerson | boolean | Habla en primera persona. |
isHuman | boolean | Simula ser una persona real. |
Campo | Tipo | Descripción |
---|---|---|
noAnswer | string | Mensaje si no tiene respuesta. |
serviceError | string | Mensaje de error de servicio. |
doNotUnderstand | string | Mensaje si no entiende la consulta. |
Campo | Tipo | Descripción |
---|---|---|
doNotMentionPrices | boolean | No hablar de precios. |
doNotDiagnose | boolean | No hacer diagnósticos médicos. |
doNotRespondOutsideHours | string | Mensaje fuera del horario definido. Trabaja junto con el campo de Timezone |
Valor | Descripción |
---|---|
es | Español general |
es-419 | Español latinoamericano neutral |
es-ES | Español de España |
en | Inglés general |
en-US | Inglés estadounidense |
en-GB | Inglés británico |
fr | Francés general |
fr-FR | Francés de Francia |
pt-BR | Portugués brasileño |
de | Alemán |
Campo | Tipo | Requerido | Descripción |
---|---|---|---|
agentId | string | ✅ Sí | Identificador único del agente. Se utiliza para recuperar su configuración y conocimiento. |
question | string | ✅ Sí | Pregunta o mensaje del usuario que la IA debe responder. |
sessionId | string | ✅ Sí | Identificador de sesión único para mantener el contexto y el historial (buffer) de la conversación. |
file | string | ❌ No | URL pública opcional de una imagen o archivo PDF. El contenido será extraído y usado si es relevante para la respuesta. |
multipleAnswers | boolean | ❌ No | Si se establece en true , la respuesta será devuelta en múltiples bloques (array) en lugar de un único texto. Ideal para respuestas estructuradas. |
onMessage
(OCR)Tipo de Archivo | Soportado | Notas |
---|---|---|
.jpg , .png , .bmp , .gif , .tiff | ✅ Sí | Formatos estándar de imagen |
.pdf | ✅ Sí | Solo si el PDF contiene texto incrustado o es una imagen escaneada |
.docx , .xlsx | ❌ No | No se admite para procesamiento OCR |
.txt , .json , etc. | ❌ No | No relevantes para extracción OCR |
Respuesta esperada:
📌 Nota: Si
multipleAnswers = false
, la respuesta se devolverá en un único string en la propiedadanswer
.
Devuelve todos los agentes dentro del espacio de trabajo.
Obtiene detalles de un agente específico por ID.
Elimina un agente y elimina automáticamente su referencia de cualquier portal asociado.
addFile()
por separado.Extensión | Tipo | Tamaño Máximo | OCR/Extracción |
---|---|---|---|
.pdf | Documentos | 10 MB | ✅ Sí |
.docx | Word | 5 MB | ✅ Sí |
.txt | Texto plano | 2 MB | ✅ Sí |
.jpg , .png | Imágenes | 5 MB | ✅ Sí |
.csv | Datos estructurados | 10 MB | ✅ Sí |
.xlsx | Excel | 10 MB | ✅ Sí |
Los archivos se procesan automáticamente para extraer su contenido y hacer que esté disponible para el agente durante las conversaciones.
El SDK proporciona manejo de errores detallado para todas las operaciones:
💡 Tip Pro: Usa el campo multipleAnswers: true
cuando necesites respuestas estructuradas para integraciones complejas o cuando quieras procesar cada parte de la respuesta por separado.
npm install plazbot
agent.config.json
onMessage
Si tienes preguntas sobre el SDK o necesitas asistencia con la implementación, contacta a nuestro equipo de soporte o revisa los ejemplos en el repositorio de GitHub.