21 Variables de sesión

Puede utilizar variables de sesión personalizadas y definidas por el agente para proporcionar puntos de datos contextuales adicionales a los agentes durante una sesión de usuario.

¿Qué son las variables de sesión?

Las variables de sesión personalizadas y definidas por el agente proporcionan puntos de datos contextuales adicionales al agente durante una sesión de usuario. Las variables se pueden utilizar para una variedad de propósitos, incluyendo la configuración de valores de parámetros en herramientas, dando instrucciones generales a un agente, y proporcionando información contextual sobre el emisor de llamada y/o la aplicación donde el agente está embebido.

A continuación, se muestra un escenario simplificado en el que estamos creando un agente de soporte al cliente. El agente de soporte al cliente está integrado en un sitio web minorista. Cuando un usuario inicia sesión en el sitio web minorista, la información sobre ese usuario es capturada por la aplicación cliente (ID de usuario, nombre de usuario, ubicación geográfica, dispositivo utilizado, ID de carro de compra, etc.) y esa información podría ser utilizada por el agente de soporte descendente. Veamos un ejemplo de cómo se podrían utilizar estos parámetros de sesión en el campo de instrucciones de agente de AIDP:

You are a customer support agent for the retail website belts-and-buckles.com, specializing in the sales of belts and buckles. Your objective is to answer questions that customers have about their current and past orders, answer questions about items they put in their shopping cart, and answer general questions about belts-and-buckles.com.  
A few guidelines before your start:  
    You are interacting with user {{sessionVariable.userName}}. Always start with a welcome message: Hello {{sessionVariable.preferredSalutation}} {{sessionVariable.userName}}! What’s the weather like today in {{sessionVariable.currentUserGeo}}?  

En el ejemplo anterior se utilizan tres variables de sesión:

• userName
• Saludo preferido
• Grupo de usuarios actuales

El agente no tiene conocimiento previo del usuario que interactúa con el sitio web minorista, no sabe cuál es la ubicación del usuario o no tiene contexto sobre lo que hay en el carrito de la compra del usuario. En principio, la aplicación cliente podría conocer todos o un subconjunto de esos valores y transferir esos valores en una solicitud al agente. A continuación, se muestra un ejemplo del aspecto que podría tener una solicitud al agente, incluidos los parámetros de sesión.

Note:

Este ejemplo ilustra el aspecto que podría tener esta solicitud. No es representante de una decisión de implantación.

"input": [  
{ "role": "user", 
         "content": [  
{ "type": "input_text”,  
	  "text": "What material is the belt Mr Outcast made of?", 
	  “variables”: [“userName”: “Paul”, “preferredSalutation”: “Hon”, “cartID”: NULL, “currentUserGeo”: “Cancun, MX”]  
} 
  ]  
} 
] 

El agente respondería: "Hola señor Paul, ¿cómo es el clima hoy en Cancún, Mx?"

Otro uso de estos parámetros de sesión es la definición de valores de parámetros en las herramientas. Por ejemplo, una consulta SQL puede recuperar el contenido de un carro de compra mediante el parámetro de sesión {{sessionParam.CartID}} :

Select productID, productName, productDescription, 
productPrice from cartTable where cartID == 
{{sessionVariable.cartID}}  

Las variables de sesión las define el desarrollador del agente cuando crea sus agentes y los valores de esos atributos los define la aplicación cliente cuando se crea o reanuda una sesión.

Puede configurar los siguientes valores al crear una nueva variable de sesión:

Valor	Descripción
Variable necesaria	Active esta opción para que esta variable de sesión sea necesaria para cada llamada de llamada del agente. La desactivación hace que la variable de sesión sea opcional para cada llamada de llamada.
Variable de log	Active esta opción para capturar el valor de la variable de sesión en logs y rastreos. La desactivación impide que la variable aparezca en los logs. Recomendamos desactivar este valor para variables con datos confidenciales.
Nombre	Nombre de la variable de sesión. Utilice un nombre descriptivo para que tanto usted como otros usuarios puedan determinar fácilmente la finalidad de la variable.
Valor por defecto	Si se define, el valor por defecto se asigna a la variable de sesión si no se define otro valor en la llamada de llamada. Si se deja en blanco, se debe asignar un valor como parte de la llamada de llamada.
Descripción	Descripción de la variable de sesión. Proporcione una descripción útil para que usted y otros usuarios puedan comprender la función de la variable de sesión.

Ejemplo: uso de variables de sesión en la configuración de herramientas

Puede utilizar una variable de sesión en una configuración de herramienta SQL como parte de la propia consulta SQL.

En este ejemplo, la variable de sesión geo se utiliza para filtrar el resultado de la consulta SQL:

Puede utilizar variables de sesión y parámetros de herramienta en la misma consulta. En el siguiente ejemplo, el agente define el parámetro titleID mientras que la variable de sesión geo la proporciona la aplicación que realiza la llamada.

Variables de sesión generadas por el sistema

Las variables de sesión se generan automáticamente cuando un servidor MCP remoto está conectado a un agente y ese servidor MCP requiere autenticación, como un token portador.

La variable de sesión contiene el valor del token portador. El nombre de esta variable de sesión generada por el sistema no se puede cambiar y es una variable necesaria. La variable del sistema se suprime cuando el nodo MCP se elimina del lienzo.

En Playground, se proporciona un valor para la variable de sesión generada por el sistema. En este caso, debe proporcionar un token de portador para utilizar el servidor MCP. Puede seleccionar el mismo token (o un token diferente) que utilizó durante la configuración del nodo MCP.

Lo mismo se aplica si despliega el agente. Deberá proporcionar un token de autorización. Para obtener más información, consulte Asignación de valores a variables de sesión desde el patio de recreo.

Ejemplo: asignación de valores a variables de sesión al llamar a un punto final desplegado

En este ejemplo, tiene dos variables de sesión: userLocation y UserName, la aplicación cliente está transfiriendo valores de variables de sesión mediante el campo metadata de body. Mostraremos cómo puede asignar valores a través de Python y de la CLI de OCI.

Si utiliza la biblioteca de solicitudes de Python, la carga útil es la siguiente:

body = { 

            "isStreamEnabled" : False, 

            "trace" : False, 
            "input" :[{ 
                "role":"User", 
                "content":[{ 
                    "type" : "INPUT_TEXT", 
                    "text" : “Hello how can you help me?”                  
                }] 
            }], 

            "metadata": { 
            "sessionvariables.userLocation": "Canada",  
            "sessionvariables.UserName": "George" 
        } 
        } 

response = requests.post( 
url = <insert-chat-url>,  
params = None,  
auth = <insert-oci-signer>, 
json = body, 
headers={“x-session-id": <insert-a-session-key>,} 
)  

Como alternativa, si utiliza la CLI de OCI, la carga útil es la siguiente:

oci raw-request \ 
  --http-method POST \ 
  --auth security_token \ 
  --request-body '{ 
    "isStreamEnabled": false, 
    "input": [ 
      { 
        "role": "user", 
        "content": [ 
          { 
            "type": "INPUT_TEXT", 
            "text": "Hello how can you help me?" 
          } 
        ] 
      } 
    ], 
    "metadata": { 
      "sessionvariables.userName": "George", 
      "sessionvariables.userLocation": "Canada"}" 
    } 
  }' \ 
  --request-headers '{ 
    "x-session-id": "george-session-may11" 
  }' \ 
  --target-uri "<insert-your-agent-flow-uri>" 

Creación de una variable de sesión en el separador Variables de agente

Puede crear una nueva variable de sesión y agregarla al agente desde el separador Variables.

1. Navegue hasta el agente al que desea agregar una variable de sesión.
2. Haga clic en el separador Variables.
   
   

   

   
   
3. Haga clic en Agregar variable de sesión.
   
   

   

   
   
4. Seleccione esta opción si la variable de sesión es obligatoria.
5. Seleccione si el valor de la variable de sesión se debe registrar en logs y rastreos. Deje esta configuración desactivada para los datos confidenciales.
6. Proporcione un nombre y descripción significativos para la variable de sesión.
7. Proporcione un valor por defecto para la variable de sesión. El valor por defecto se asigna a la variable de sesión si no se asigna ningún otro valor como parte de la llamada de llamada.
8. Haga clic en Create.

Consulte las variables de sesión en las instrucciones de flujo de agente

Puede consultar las variables de sesión en las instrucciones del agente y las configuraciones de la herramienta, incluida la consulta de la herramienta SQL y Prompt.

1. Navegue hasta el flujo de agentes.
2. Haga clic en el nodo de la herramienta SQL o Prompt en Playground.
   
   

   

   
   
3. En el campo Consulta, comience a escribir {{sessionvariables.
4. Seleccione la variable de sesión de la lista de variables de sesión existentes.

Visualización de Agentes y Herramientas mediante una Variable de Sesión

Puede ver una lista de agentes y herramientas mediante una variable de sesión específica en el separador Variable del agente.

1. Navegue a un agente mediante la variable de sesión para la que desea ver los agentes y herramientas relacionados.
2. Haga clic en el separador Variable.
3. Junto a Utilizado en: para la variable de sesión, haga clic en el menú desplegable. Se muestra una lista de agentes y herramientas que utilizan la variable de sesión.

Asignación de Valores a Variables de Sesión desde el Área de Juego

Puede asignar valores a variables de sesión en cualquier momento desde el separador Playground.

1. Vaya a su agente.
2. En la parte superior del área de juegos, haga clic en Parámetros de sesión. Se muestra una lista de todas las variables de sesión del agente.
   
   

   

   
   
3. Modifique las variables de sesión. Después de reanudar la sesión de Playground, se utilizan los últimos valores de variables de sesión asignados.