Agente de IA
Guía completa sobre la configuración del agente de IA en Plazbot
Configuración del Agente de IA
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.
Github
Puedes descargar nuestro repositorio de ejemplo para crear tus agentes.
Inicialización
Creación del Agente
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.
Estructura del Archivo agent.config.json
Campos principales del agente
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) |
Instrucciones (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
Persona del Agente (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. |
Reglas y Fallbacks
Fallbacks
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. |
Reglas
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 |
Códigos de Idioma
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 |
Enviar mensaje al Agente de IA
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. |
Tipos de Archivos Soportados en 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
.
Get Agents
Devuelve todos los agentes dentro del espacio de trabajo.
Get Agent By Id
Obtiene detalles de un agente específico por ID.
Delete Agent
Elimina un agente y elimina automáticamente su referencia de cualquier portal asociado.
📎 Consideraciones Finales
- El agente puede ser creado, actualizado o eliminado usando el SDK.
- Para agregar archivos o servicios, use los métodos
addFile()
por separado. - Toda la lógica de respuesta está diseñada para mantener el contexto, estilo y tono definidos.