Variables MCP

Resumen: cinco conceptos

Nombres de variables

Los identificadores de variables (memoria, paso y session_state) deben usar solo letras ASCII sin tildes (a-z, A-Z), dígitos y guion bajo (_). Deben empezar por letra o _.

Ejemplos válidos: telefono, userLead, has_session. Inválidos: teléfono, dirección, mi variable.

Estado de sesión (session_state)

Variables que el bot necesita recordar y que cambian durante la conversación (pedido activo, fase del flujo, flags de negocio). Se almacenan en Redis con la misma TTL que la memoria de sesión.

Escribir variables

• Sección C. Variables de una intención MCP → alcance Estado de sesión.
• API Connect en cadena → route.memory.set[] con scope: session_state.

Descripción opcional

Al escribir con alcance session_state puedes añadir una descripción legible para el LLM. Se muestra junto al valor en el bloque efímero de cada turno.

Placeholders

Usa {{session_state.nombre_variable}} en instrucciones, URLs, plantillas de correo, etc. Orden de resolución: paso > estado de sesión > memoria > parámetros.

Condiciones

Las condiciones memory_var_* en disponibilidad de intención (activation_when) evalúan variables según el alcance elegido: memory o session_state.

También están disponibles los tipos básicos: exists, equals, is_string, is_number, arrays vacíos/con elementos, etc.

Contexto Chatwoot (user_contact)

En sesiones con session_origin=chatwoot, EasyChatBot sincroniza datos del visitante (nombre, teléfono, etiquetas, notas, atributos custom) a Redis como {{memory.user_contact}} para condiciones y placeholders.

Bloque de prompt vs memoria

• Bloque efímero [Contexto visitante — Chatwoot]: se inyecta al final del turno con datos frescos (notas/etiquetas que cambian). No va en el system prompt.
• Variable user_contact: JSON en memoria Redis para activation_when, API Connect y placeholders {{memory.user_contact}}.

Configura qué campos incluir en el dashboard → Chatwoot → Contexto del visitante. En acciones MCP con cw_user_contact_show se inyecta un subconjunto de campos.

Guía completa de integración Chatwoot

Parámetros de intención (tool_parameters)

En el modal MCP, la sección Parámetros de la intención define qué arguments debe enviar el router cuando invoca la intención. El servidor valida tipos y restricciones antes de ejecutar la acción.

Restricciones JSON Schema

En el panel Restricciones (JSON Schema) puedes añadir validación alineada al estándar MCP:

• pattern (regex), format (email, uri, date, date-time, uuid)
• min_length / max_length en strings
• minimum / maximum en números
• min_items / max_items y items_pattern en arrays de strings

Placeholder en acciones: {{parameters.nombre_parametro}}. Un parámetro object se resuelve como valor JSON completo.

Routing tras API Connect (otra intención MCP)

Una intención API Connect en modo cadena no puede forzar directamente otra intención. El patrón oficial es solo configuración:

1. En el paso de lookup: response_mapping (ej. lead) y en Memoria → escribir variable con + Condición (ej. mi_bandera=true solo si array_empty en campo_del_paso).
2. En Siguiente paso: transición a __finish__ (éxito o vacío) para cerrar la cadena tras escribir la bandera.
3. En la intención destino: Activación condicional con memory_var_equals o memory_var_exists sobre esa variable (scope memory o session_state según dónde escribiste).
4. En configuración MCP: activar Orquestación multi-tool por turno y al menos 2 rondas para que el router haga una segunda pasada en el mismo turno.

Dos tipos de «when»

• Condición para escribir (memory.set[].when): evalúa variables del paso (response_mapping). Controla si se escribe la bandera. Puede incluir varias condiciones con when.mode (all / any) y when.conditions[].
• Activación de intención (activation_when): evalúa memoria o estado de sesión ya guardados. Controla si la intención destino entra al catálogo del router.

Flujo en runtime

Tras escribir memoria o session_state, el orquestador marca el estado como «dirty», refresca activation_when y, si hay tools nuevas visibles y multi-tool está activo, programa una 2ª ronda del router con un hint genérico. El panel Intenciones en test-chatbot muestra el Log de routing por memoria con cada paso (escritura, dirty, desbloqueo, ronda 2).

Guiar al LLM del router

Los mensajes de finalización de cadena (success_message / error_message) son texto para el usuario, no instrucciones de routing. Para decir al router qué intención ejecutar después, usa Instrucciones de uso de intenciones (mcp_intent_usage_rules) en configuración MCP.

Límites y buenas prácticas

• Los bloques efímeros se truncan aprox. a 8 KB en la inyección al LLM; los placeholders siguen usando el valor completo.
• user_contact es variable reservada de memoria: no la declares en session_state ni en memory.set manual.
• «Nueva sesión» limpia memoria y estado de sesión en Redis.