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

import { Agent } from 'plazbot';

const bot = new Agent({
  workspaceId: "[YOUR_WORKSPACE_ID]",
  apiKey: "[YOUR_API_KEY]",
  zone: "LA" // Use "EU" for Europe
});

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.

const agent = await bot.addAgent(config);
    const agentId = agent.agentId;
const agentUpdated = await bot.updateAgent(`agentId`, config);

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

{
  "name": "Sales Clinic",
  "description": "Virtual Agent IA assistant of the Dental Clinic Smiles",
  "prompt": "",
  "zone": "LA",
  "buffer": 50,
  "color": "blue",
  "question": "How can I help you today?",
  "timezone": "America/Lima",
  "enable": true,
  "tags": [
    "health",
    "dentistry",
    "ia",
    "plazbot"
  ],
  "examples": [
    { "value": "How to be a partner??", "color": "green" },
    { "value": "Benefits of being members?", "color": "blue" }
  ],
  "instructions": {
    "tone": "professional",
    "style": "short answers",
    "personality": "friendly",
    "objective": "help with clarity",
    "language": "es-419",
    "emojis": false,
    "preferredFormat": "plain text",
    "maxWords": 80,
    "avoidTopics": [
      "laboratory costs",
      "external claims"
    ],
    "respondOnlyIfKnows": true,
    "maintainToneBetweenMessages": true,
    "greeting": "Hello, I am Maximo"
  },
  "person": {
    "name": "Maximo",
    "role": "Virtual customer service assistant",
    "speaksInFirstPerson": true,
    "isHuman": false
  },
  "fallbacks": {
    "noAnswer": "Sorry, I don't have information on that topic.",
    "serviceError": "There was a problem processing your request. Please try again later.",
    "doNotUnderstand": "Could you please repeat it in another way?"
  },
  "rules": {
    "doNotMentionPrices": false,
    "doNotDiagnose": true,
    "doNotRespondOutsideHours": "Our hours are Monday to Saturday, from 8am to 6pm."
  },
   "services": [
    {
      "intent": "schedule_date",
      "reference": "Service for recording patients' medical appointments at the clinic",
      "enabled": true,
      "method": "POST",
      "requiredFields": [ 
        { 
          "name": "name_contact", 
          "description": "Name of the person who wants to schedule the meeting.",
          "promptHint": "¿Could you tell me your full name, please??",
          "type": "string"
        },
        { 
          "name": "email",
          "description": "Email of the person who wants to schedule the meeting.",
          "promptHint": "¿What is your email address for the appointment?",
          "type": "string"
          
        },
        { 
          "name": "date",
          "description": "Preferred date and time for the meeting.",
          "promptHint": "¿What day and time would be good for you for the meeting??",
          "type": "date"
        }
      ],
      "endpoint": "https://api.clinic.com/v1/date/schedule",
      "headers": {
        "Authorization": "Bearer {{apiKey}}",
        "Content-Type": "application/json"
      },
      "bodyTemplate": {
        "nombre": "{{nombre}}",
        "email": "{{email}}", 
        "fecha": "{{fecha}}"
      },
      "responseMapping": {
        "mensaje": "$.reponse.mensaje",
        "date": "$.response.date"
      },
      "responseMessage": "Tu cita ha sido registrada exitosamente para el {{date}}"
    }
  ]
}

Campos principales del agente

CampoDescripción
nameNombre del agente. Visible en el panel. Requerido
promptInstrucciones base para el comportamiento del agente. Requerido
bufferCantidad de mensajes que se mantienen como contexto. Rango: 3 a 10. Requerido
colorColor de presentación. Valores: blue, orange, gray, green, white.
questionPregunta principal que se muestra en el portal.
descriptionDescripción general del agente.
zoneZona donde opera el agente: LA (Latinoamérica) o EU (Europa). Requerido
timezoneZona horaria. Ejemplo: America/Lima. TimeZone Formats
tagsEtiquetas internas para clasificar agentes.
examplesPreguntas sugeridas. Hasta 5.
showInChatSi el agente se muestra en el widget/chat. (boolean)

Instrucciones (instructions)

CampoTipoDescripción
tonestringTono de comunicación: professional, friendly, etc.
stylestringEstilo de respuestas: short answers, detailed.
personalitystringPersonalidad del agente.
objectivestringObjetivo principal del agente.
languagestringIdioma en que debe responder. Ver tabla de idiomas.
emojisbooleanSi puede usar emojis.
preferredFormatstringplain text o markdown.
maxWordsnumberMáximo de palabras por respuesta.
avoidTopicsarrayLista de temas prohibidos.
respondOnlyIfKnowsbooleanSi debe evitar responder sin información confiable.
maintainToneBetweenMessagesbooleanMantiene el mismo tono entre mensajes.
greetingstringMensaje 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)

CampoTipoDescripción
namestringNombre que usará el agente.
rolestringRol representado.
speaksInFirstPersonbooleanHabla en primera persona.
isHumanbooleanSimula ser una persona real.

Reglas y Fallbacks

Fallbacks

CampoTipoDescripción
noAnswerstringMensaje si no tiene respuesta.
serviceErrorstringMensaje de error de servicio.
doNotUnderstandstringMensaje si no entiende la consulta.

Reglas

CampoTipoDescripción
doNotMentionPricesbooleanNo hablar de precios.
doNotDiagnosebooleanNo hacer diagnósticos médicos.
doNotRespondOutsideHoursstringMensaje fuera del horario definido. Trabaja junto con el campo de Timezone

Códigos de Idioma

ValorDescripción
esEspañol general
es-419Español latinoamericano neutral
es-ESEspañol de España
enInglés general
en-USInglés estadounidense
en-GBInglés británico
frFrancés general
fr-FRFrancés de Francia
pt-BRPortugués brasileño
deAlemán

Enviar mensaje al Agente de IA

const response = await bot.onMessage({
  agentId: "agentId",
  question: "Can you give me a summary of the new Meta WhatsApp prices?",
  sessionId: "2aff0c11-434f-4d7c-a325-697128bb8a20",
  file: "https://.../archivo.pdf", // 
  multipleAnswers: true // Optional
});

console.log("💬 IA Response:", respuesta);
CampoTipoRequeridoDescripción
agentIdstring✅ SíIdentificador único del agente. Se utiliza para recuperar su configuración y conocimiento.
questionstring✅ SíPregunta o mensaje del usuario que la IA debe responder.
sessionIdstring✅ SíIdentificador de sesión único para mantener el contexto y el historial (buffer) de la conversación.
filestring❌ NoURL pública opcional de una imagen o archivo PDF. El contenido será extraído y usado si es relevante para la respuesta.
multipleAnswersboolean❌ NoSi 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 ArchivoSoportadoNotas
.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❌ NoNo se admite para procesamiento OCR
.txt, .json, etc.❌ NoNo relevantes para extracción OCR

Respuesta esperada:

{
  "success": true,
  "answers": [
    "Beneficio 1: Acceso exclusivo...",
    "Beneficio 2: Soporte personalizado...",
    "Beneficio 3: Capacitación mensual..."
  ],
  "fileName": ["Contrato_socio_plazbot.pdf"]
}

📌 Nota: Si multipleAnswers = false, la respuesta se devolverá en un único string en la propiedad answer.

Get Agents

Devuelve todos los agentes dentro del espacio de trabajo.

const agents = await bot.getAgents();
    console.log("🧠 Agents:", agents);

Get Agent By Id

Obtiene detalles de un agente específico por ID.

const agentById = await bot.getAgentById({ id: agentId });
    console.log("📌 Agent by ID:", agentById);

Delete Agent

Elimina un agente y elimina automáticamente su referencia de cualquier portal asociado.

// Delete Agent
    await bot.deleteAgent({
      id: agentId
    });

📎 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.