> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plazbot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variables del Agente

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

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

<Info>
  Las variables usan la sintaxis `{{scope.codigo}}` donde **scope** indica el origen de la variable y **codigo** es el identificador unico.
</Info>

***

## 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.
</Tip>

### 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 theme={null}
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:

<Steps>
  <Step title="Variables del Agente">
    Primero se resuelven las variables con sintaxis `{{scope.codigo}}` (system, contact, custom).
  </Step>

  <Step title="Variables Legacy">
    Despues se resuelven las variables con sintaxis legacy `[variable]` como `[lastmessage]`, `[sessionId]`, etc.
  </Step>

  <Step title="Campos del LLM">
    Finalmente se sustituyen los campos extraidos por el modelo de IA con sintaxis `{campo}`, que corresponden a los `requiredFields` del servicio.
  </Step>
</Steps>

<Warning>
  La sintaxis legacy `[variable]` sigue funcionando para retrocompatibilidad. Los agentes existentes que usan `[lastmessage]`, `[sessionId]`, etc. en sus servicios no necesitan ser modificados.
</Warning>

***

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

```bash theme={null}
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)                     |

<Info>
  El campo `variables` es **opcional**. Si un agente no tiene variables personalizadas y no se envian en el request, todo funciona exactamente como antes.
</Info>

***

## 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 theme={null}
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 theme={null}
{
  "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 theme={null}
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

<Warning>
  La sintaxis anterior `[variable]` sigue funcionando. No es necesario migrar agentes existentes. Ambas sintaxis pueden coexistir en el mismo servicio.
</Warning>

| 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 theme={null}
{
  "bodyTemplate": {
    "mensaje": "[lastmessage]",
    "sesion": "{{system.sessionId}}",
    "empresa": "{{custom.empresa}}",
    "campo_llm": "{curp}"
  }
}
```