Introduccion
El sistema de variables del Agente de IA permite inyectar informacion dinamica en el prompt, servicios y acciones del agente. Las variables se resuelven automaticamente antes de cada interaccion con el modelo de IA, permitiendo personalizar el comportamiento del agente segun el contexto de la conversacion.
Las variables usan la sintaxis {{scope.codigo}} donde scope indica el origen de la variable y codigo es el identificador unico.
Scopes de Variables
El sistema maneja 3 scopes (alcances) de variables, cada uno con un proposito diferente:
1. Variables del Sistema (system)
Variables predefinidas que se actualizan automaticamente durante la conversacion. No se pueden modificar manualmente.
| Variable | Codigo | Descripcion | Ejemplo |
|---|
| Ultimo mensaje | {{system.lastmessage}} | Ultimo mensaje enviado por el usuario | "Hola, necesito agendar una cita" |
| Hora del mensaje | {{system.lastmessagetime}} | Fecha y hora del ultimo mensaje | 2026-04-13 18:53:28 |
| Session ID | {{system.sessionId}} | ID unico de la sesion actual | 51932114990 |
| Agent ID | {{system.agentId}} | ID del agente que procesa la conversacion | age_abc123 |
| Ultima respuesta IA | {{system.lastmessageIA}} | Ultima respuesta generada por el agente | "Te ayudo a agendar tu cita" |
| Archivo temporal | {{system.urlTempFile}} | URL del archivo adjunto enviado por el usuario | https://temp.plazbot.com/file123 |
| Fecha actual | {{system.currentDate}} | Fecha actual en la zona horaria del workspace | 2026-04-13 |
| Hora actual | {{system.currentTime}} | Hora actual en la zona horaria del workspace | 14:30:00 |
contactData.variables[]).
| Variable | Codigo | Descripcion |
|---|
| Nombre completo | {{contact.fullname}} | Nombre del contacto |
| Email | {{contact.email}} | Correo electronico |
| Telefono | {{contact.phone}} | Numero de telefono |
| Plataforma | {{contact.platform}} | Canal de origen (whatsapp, telegram, etc.) |
| Variable personalizada | {{contact.ctc_CODIGO}} | Busca en las variables del contacto por codigo |
Las variables del contacto con prefijo ctc_ buscan en el array de variables personalizadas del contacto. Por ejemplo, {{contact.ctc_product_id}} busca la variable con codigo ctc_product_id en el contacto actual.
3. Variables Personalizadas (custom)
Variables definidas por el usuario en la pestana Variables del agente. Cada variable tiene un valor por defecto que se usa si no se envia un valor en el request on-message.
| Variable | Codigo | Descripcion |
|---|
| Definida por usuario | {{custom.CODIGO}} | Valor personalizado segun configuracion |
empresa y valor por defecto "Mi Empresa", puedes usarla como {{custom.empresa}} en el prompt o servicios.
Donde Usar Variables
Las variables se pueden utilizar en 3 contextos del agente:
En el Prompt
Las variables se resuelven en el texto del prompt antes de enviarlo al modelo de IA. Esto permite personalizar las instrucciones del agente dinamicamente.
Eres un asistente de {{custom.empresa}}.
El cliente que te escribe se llama {{contact.fullname}}.
Tu objetivo es {{custom.objetivo}}.
La fecha de hoy es {{system.currentDate}}.
En Servicios (5 ubicaciones)
Las variables se resuelven en multiples partes de la configuracion de un servicio:
| Ubicacion | Descripcion | Ejemplo |
|---|
| Endpoint (URL) | Variables en la URL del servicio | https://api.ejemplo.com/users/{{system.sessionId}} |
| Headers | Variables en los encabezados HTTP | Authorization: Bearer {{custom.api_key}} |
| Body Template | Variables en el cuerpo de la peticion | { "cliente": "{{contact.fullname}}" } |
| Response Message | Variables en el mensaje de respuesta | Gracias {{contact.fullname}}, tu solicitud fue procesada |
| Response Conditions | Variables en condiciones de respuesta | Evaluacion dinamica del resultado |
En Acciones (1 ubicacion)
| Ubicacion | Descripcion | Ejemplo |
|---|
| Response Message | Variables en el mensaje de respuesta de la accion | Listo {{contact.fullname}}, se asigno tu caso |
Orden de Resolucion
Cuando un servicio o accion contiene variables, estas se resuelven en un orden especifico:
Variables del Agente
Primero se resuelven las variables con sintaxis {{scope.codigo}} (system, contact, custom).
Variables Legacy
Despues se resuelven las variables con sintaxis legacy [variable] como [lastmessage], [sessionId], etc.
Campos del LLM
Finalmente se sustituyen los campos extraidos por el modelo de IA con sintaxis {campo}, que corresponden a los requiredFields del servicio.
La sintaxis legacy [variable] sigue funcionando para retrocompatibilidad. Los agentes existentes que usan [lastmessage], [sessionId], etc. en sus servicios no necesitan ser modificados.
Configuracion en el Panel
La pestana Variables del agente muestra las 3 categorias de variables organizadas en secciones colapsables:
- Variables del Sistema: Lista de solo lectura con todas las variables predefinidas.
- Variables del Contacto: Lista de solo lectura con las variables disponibles del contacto.
- Variables Personalizadas: Seccion editable donde puedes crear, modificar y eliminar variables propias.
Cada variable incluye un boton de copiar que copia la sintaxis completa {{scope.codigo}} al portapapeles para insertarla facilmente en el prompt, servicios o acciones.
Uso en la API (on-message)
Las variables personalizadas pueden enviarse dinamicamente en cada llamada al endpoint on-message. Esto permite que webhooks, automatizaciones o integraciones externas inyecten valores en tiempo real.
Request
curl -X POST https://api.plazbot.com/agent/on-message \
-H "Content-Type: application/json" \
-d '{
"agentId": "age_xxxxx",
"question": "Hola, necesito informacion",
"sessionId": "51932114990",
"platform": "api",
"variables": {
"empresa": "Acme Corp",
"plan": "Enterprise",
"origen_campana": "Google Ads"
}
}'
Comportamiento de variables
| Escenario | Resultado |
|---|
Se envia variables en el request | Los valores del request tienen prioridad sobre los valores por defecto del agente |
No se envia variables | Se usan los defaultValue configurados en las variables del agente |
| Se envia una variable no definida en el agente | Se resuelve igualmente con el valor enviado |
| No hay variables configuradas ni enviadas | Las expresiones {{custom.X}} quedan sin resolver (string vacio) |
El campo variables es opcional. Si un agente no tiene variables personalizadas y no se envian en el request, todo funciona exactamente como antes.
Ejemplo Completo
1. Definir variables en el agente
En la pestana Variables, crear:
empresa (tipo: string, valor por defecto: "Plazbot")api_key (tipo: string, valor por defecto: "sk-default-123")
2. Usar en el prompt
Eres el asistente virtual de {{custom.empresa}}.
Responde de manera amable y profesional.
El cliente se llama {{contact.fullname}}.
3. Usar en un servicio
{
"intent": "consultar_saldo",
"method": "POST",
"endpoint": "https://api.ejemplo.com/saldo",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer {{custom.api_key}}",
"X-Session": "{{system.sessionId}}"
},
"bodyTemplate": {
"telefono": "{{contact.phone}}",
"consulta": "{{system.lastmessage}}",
"numero_cuenta": "{numero_cuenta}"
},
"requiredFields": [
{
"name": "numero_cuenta",
"description": "Numero de cuenta del cliente",
"type": "string"
}
],
"responseMessage": "{{contact.fullname}}, tu saldo es: {saldo}"
}
4. Enviar variables por API
curl -X POST https://api.plazbot.com/agent/on-message \
-H "Content-Type: application/json" \
-d '{
"agentId": "age_xxxxx",
"question": "Cual es mi saldo?",
"sessionId": "51932114990",
"variables": {
"empresa": "Banco Digital",
"api_key": "sk-prod-456"
}
}'
{{custom.empresa}} se resuelve como "Banco Digital" (valor del request) en lugar de "Plazbot" (valor por defecto).
Retrocompatibilidad
La sintaxis anterior [variable] sigue funcionando. No es necesario migrar agentes existentes. Ambas sintaxis pueden coexistir en el mismo servicio.
| Sintaxis | Estado | Ejemplo |
|---|
[lastmessage] | Activa (legacy) | Funciona en servicios como siempre |
{{system.lastmessage}} | Activa (nueva) | Equivalente, con mas opciones de scope |
{{campo_requerido}} | Activa | Campos extraidos por el LLM en servicios |
{
"bodyTemplate": {
"mensaje": "[lastmessage]",
"sesion": "{{system.sessionId}}",
"empresa": "{{custom.empresa}}",
"campo_llm": "{curp}"
}
}
