Variables del Agente

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`

2. Variables del Contacto (`contact`)

Variables que provienen del contacto que esta conversando con el agente. Se resuelven dinamicamente buscando primero en los campos fijos del contacto y luego en las variables personalizadas del contacto (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

Ejemplo: Si creas una variable con codigo 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"
    }
  }'

En este caso, {{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

Ejemplo mixto (ambas sintaxis en el mismo bodyTemplate):

{
  "bodyTemplate": {
    "mensaje": "[lastmessage]",
    "sesion": "{{system.sessionId}}",
    "empresa": "{{custom.empresa}}",
    "campo_llm": "{curp}"
  }
}

Introducción

Primeros Pasos

Contactos

Agente de IA

Marketing

Partners Marca Blanca

Legal

Introduccion

Scopes de Variables

1. Variables del Sistema (`system`)

2. Variables del Contacto (`contact`)

3. Variables Personalizadas (`custom`)

Donde Usar Variables

En el Prompt

En Servicios (5 ubicaciones)

En Acciones (1 ubicacion)

Orden de Resolucion

Configuracion en el Panel

Uso en la API (on-message)

Request

Comportamiento de `variables`

Ejemplo Completo

1. Definir variables en el agente

2. Usar en el prompt

3. Usar en un servicio

4. Enviar variables por API

Retrocompatibilidad

​Introduccion

​Scopes de Variables

​1. Variables del Sistema (system)

​2. Variables del Contacto (contact)

​3. Variables Personalizadas (custom)

​Donde Usar Variables

​En el Prompt

​En Servicios (5 ubicaciones)

​En Acciones (1 ubicacion)

​Orden de Resolucion

​Configuracion en el Panel

​Uso en la API (on-message)

​Request

​Comportamiento de variables

​Ejemplo Completo

​1. Definir variables en el agente

​2. Usar en el prompt

​3. Usar en un servicio

​4. Enviar variables por API

​Retrocompatibilidad

Introduccion

Scopes de Variables

1. Variables del Sistema (`system`)

2. Variables del Contacto (`contact`)

3. Variables Personalizadas (`custom`)

Donde Usar Variables

En el Prompt

En Servicios (5 ubicaciones)

En Acciones (1 ubicacion)

Orden de Resolucion

Configuracion en el Panel

Uso en la API (on-message)

Request

Comportamiento de `variables`

Ejemplo Completo

1. Definir variables en el agente

2. Usar en el prompt

3. Usar en un servicio

4. Enviar variables por API

Retrocompatibilidad