# Variables del Agente

> Sistema de variables del Agente de IA: scopes, sintaxis y uso en prompt, servicios, acciones y API

Source: https://docs.plazbot.com/kb/agentes-variables

### Introducción

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 interacción con el modelo de IA, permitiendo personalizar el comportamiento del agente segun el contexto de la conversacion.

Info: Las variables usan la sintaxis {{scope.codigo}} donde scope indica el origen de la variable y codigo es el identificador unico.

![](https://storage-tickos-files.s3.us-east-1.amazonaws.com/tickos-files-compose/kba_f757b2ad428625aa569557a65cb15b45/1788103097127-np9k199mgcn.png)

* * *

## 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

Tip: 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.

```markdown
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:

1. **Variables del Agente** Primero se resuelven las variables con sintaxis `{{scope.codigo}}` (system, contact, custom).
2. **Variables Legacy** Despues se resuelven las variables con sintaxis legacy `[variable]` como `[lastmessage]`, `[sessionId]`, etc.
3. **Campos del LLM** Finalmente se sustituyen los campos extraidos por el modelo de IA con sintaxis `{campo}`, que corresponden a los `requiredFields` del servicio.

Advertencia: La sintaxis legacy \[variable\] sigue funcionando para retrocompatibilidad. Los agentes existentes que usan \[lastmessage\], \[sessionId\], etc. en sus servicios no necesitan ser modificados.

* * *

## Configuración en el Panel

La pestañaa **Variables** del agente muestra las 3 categorías 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**: Sección editable donde puedes crear, modificar y eliminar variables propias.

Cada variable incluye un botón 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

```bash
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

```markdown
Eres el asistente virtual de {{custom.empresa}}.
Responde de manera amable y profesional.
El cliente se llama {{contact.fullname}}.
```

### 3\. Usar en un servicio

```json
{
  "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

```bash
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

Advertencia: 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):

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