Skip to main content

Configuracion del Agente de IA

Este documento describe la estructura y configuracion del Agente de IA en Plazbot. Un agente puede estar vinculado a un portal web, widget o canal de mensajeria como WhatsApp o cualquier software que tengas.

GitHub - Ejemplos

Repositorio con ejemplos funcionales para crear tus agentes.

Inicializacion

Puedes usar la clase unificada Plazbot o importar Agent de forma individual:

Creacion del Agente

El agente es la unidad base del SDK. Puedes crear agentes con caracteristicas especificas y desplegarlos en diferentes canales: Portal de IA, Widget, WhatsApp o cualquier herramienta empresarial.

Actualizar Agente

Para trabajar con los agentes, existe un archivo JSON que funciona como el configurador inicial. No es necesario completar todos los campos, configura solo lo que necesites.
Proporcionamos archivos de configuracion basico y avanzado en el Repositorio de GitHub.

Estructura del Archivo agent.config.json

Canales (channels)

Los canales definen dónde y cómo tu agente puede comunicarse con los usuarios.
CampoTipoRequeridoDescripción
channelstring✅ SíTipo de canal: whatsapp, telegram, messenger, etc.
keystring✅ SíIdentificador del canal (número de teléfono para WhatsApp).

Ejemplo de Canales

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 20. 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)
enableSi el agente esta habilitado o no. (boolean)
versionVersion del agente (auto-incrementado). Formato: v2.0, v2.1, etc.
useToolCallingSi usa el orquestador de Tool Calling (true) o el clasico (false). Default: true.
responseModeModo de respuesta: direct (inmediato) o batched (espera mensajes consecutivos). Default: direct.
batchWaitSecondsSegundos de espera para acumular mensajes consecutivos (solo si responseMode=batched). Rango: 2-10. Default: 3.
customAIConfigHabilita configuracion personalizada de proveedores de IA. (boolean)
aiProvidersArray de proveedores de IA configurados. Ver seccion “Modelo IA”.

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

Configuración de Modelo IA

Plazbot te permite configurar proveedores de IA personalizados para cada agente. Por defecto, los agentes usan el token de OpenAI configurado en tu workspace, pero puedes habilitar configuración personalizada para usar diferentes proveedores (OpenAI, Claude, Gemini) con sus propios tokens y parámetros.

Habilitar Configuración Personalizada

Campos de aiProviders

CampoTipoRequeridoDescripción
providerstring✅ SíProveedor de IA: openai, claude, o gemini
modelstring✅ SíModelo específico a usar. Ver modelos disponibles abajo.
apiTokenstring✅ SíToken de API del proveedor.
temperaturenumber❌ NoControla creatividad (0-2). Default: 0.7
maxTokensnumber❌ NoLongitud máxima de respuesta. Recomendado: 4096
isDefaultboolean❌ NoDefine cuál proveedor usar por defecto.

Modelos Disponibles por Proveedor

OpenAI:
  • gpt-5.1
  • gpt-5.1-codex
  • gpt-5
  • gpt-4o (recomendado)
  • gpt-4o-mini
  • gpt-4-turbo
  • o1-preview
  • o1-mini
Claude (Anthropic):
  • claude-3-5-sonnet-20241022 (recomendado)
  • claude-3-5-sonnet-20240620
  • claude-3-opus-20240229
  • claude-3-sonnet-20240229
  • claude-3-haiku-20240307
Gemini (Google):
  • gemini-2.0-flash-exp (recomendado)
  • gemini-1.5-pro
  • gemini-1.5-flash
  • gemini-1.5-flash-8b

Parámetros de Temperature

ValorDescripciónUso Recomendado
0 - 0.3Respuestas muy predecibles y consistentesSoporte técnico, datos precisos
0.5 - 0.7Balance entre creatividad y precisiónUso general (recomendado)
1.0 - 1.5Respuestas más creativas y variadasMarketing, contenido creativo
1.5 - 2.0Muy creativo e impredecibleEscritura creativa, brainstorming

Parámetros de MaxTokens

ValorDescripciónUso Recomendado
1024Respuestas cortasRespuestas breves, preguntas simples
2048Respuestas medianasExplicaciones moderadas
4096Respuestas largas (recomendado)Uso general
8192Respuestas muy largasAnálisis detallados
16384Respuestas extensasDocumentos completos
Importante: Si activas customAIConfig: true, debes agregar al menos un proveedor en el array aiProviders. Si el array está vacío, el sistema usará la configuración por defecto del workspace.
Tip: Puedes configurar múltiples proveedores y el agente usará el que tenga isDefault: true. Esto es útil para A/B testing o para tener proveedores de respaldo.

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

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:
CampoTipoDescripcion
answerstringRespuesta del agente en texto. Si multipleAnswers = true, se devuelve como array en answers.
sourcesarrayFuentes del knowledge base usadas para generar la respuesta (si aplica).
actionsExecutedarrayAcciones que se ejecutaron durante la respuesta (si aplica).

Streaming SSE (Server-Sent Events)

Los endpoints /on-message y /on-message-portal soportan streaming SSE. Cuando envias stream: true, la respuesta se emite como text/event-stream con chunks progresivos en vez de esperar la respuesta completa.
Requisito: El agente debe tener useToolCalling: true para que el streaming funcione. Si useToolCalling es false, el endpoint retorna JSON normal aunque envies stream: true.
Portal y Widget: Los agentes asociados a Portales de IA y Widgets siempre deben tener useToolCalling: true activado para una experiencia optima con streaming.

Request con Stream

Formato de Chunks SSE

Cada linea sigue el formato data: {json}\n\n. Los tipos de chunks son:
TipoDescripcionCampos
textToken parcial de textocontent: texto parcial
tool_callEl agente ejecuta una herramienta (API, accion)tool_name: nombre de la herramienta
tool_resultResultado de la herramienta ejecutadatool_name, tool_result
doneStream finalizadoinput_tokens, output_tokens, estimated_cost
errorError durante el procesamientoerror: mensaje de error

Ejemplo de Chunks

Consumir el Stream (JavaScript/TypeScript)

Proveedores Soportados

ProveedorStreamingNotas
OpenAISoportadoTokens emitidos uno a uno
Claude (Anthropic)SoportadoChunks mas grandes que OpenAI
Gemini (Google)SoportadoTokens emitidos progresivamente

Retrocompatibilidad

El parametro stream es opcional con default false. Los clientes existentes que no envien stream continuan recibiendo la respuesta JSON completa sin ningun cambio.

Listar Agentes

Devuelve todos los agentes dentro del workspace.

Obtener Agente por ID

Copiar Agente

Crea una copia exacta del agente.

Obtener Agente por Canal

Busca un agente por su canal y clave asociada.

Eliminar Agente

Elimina un agente y remueve su referencia de cualquier portal asociado.

Configuracion Rapida (Quick Config)

Actualiza secciones especificas del agente sin enviar toda la configuracion:

Debug Logs

Obtener los logs de debug del agente para diagnosticar problemas:

Utilidades de IA

Mejora un prompt usando inteligencia artificial:

Manejo de Errores

Usa multipleAnswers: true en onMessage cuando necesites respuestas estructuradas para integraciones complejas.

Necesitas Ayuda?

Contacta a nuestro equipo en support@plazbot.com o revisa los ejemplos en el repositorio de GitHub.