21 Variables de session

Vous pouvez utiliser des variables de session personnalisées définies par l'agent pour fournir des points de données contextuelles supplémentaires à vos agents au cours d'une session utilisateur.

Définition des variables de session

Les variables de session personnalisées définies par l'agent fournissent des points de données contextuels supplémentaires à l'agent au cours d'une session utilisateur. Les variables peuvent être utilisées à diverses fins, notamment en définissant des valeurs de paramètres dans les outils, en donnant des instructions générales à un agent et en fournissant des informations contextuelles sur l'appelant et/ou l'application dans laquelle l'agent est intégré.

Voici un scénario simplifié dans lequel nous créons un agent de support client. L'agent de support client est intégré à un site Web de vente au détail. Lorsqu'un utilisateur se connecte au site Web de vente au détail, les informations sur cet utilisateur sont capturées par l'application client (ID utilisateur, nom d'utilisateur, emplacement géographique, appareil utilisé, ID panier, etc.) et ces informations peuvent être utilisées par l'agent de support en aval. Examinons un exemple de la façon dont ces paramètres de session peuvent être utilisés dans le champ des instructions d'agent dans 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}}?  

Trois variables de session sont utilisées dans l'exemple ci-dessus :

• userName
• Salutation préférée
• currentUserGeo

L'agent n'a aucune connaissance préalable de l'utilisateur interagissant avec le site Web de vente au détail, ne sait pas quel est l'emplacement de l'utilisateur ou n'a aucun contexte sur ce qui se trouve dans le panier de l'utilisateur. En principe, l'application client peut connaître l'ensemble ou un sous-ensemble de ces valeurs et transmettre ces valeurs dans une demande à l'agent. Voici un exemple de ce à quoi pourrait ressembler une demande adressée à l'agent, y compris les paramètres de session.

Remarques :

Cet exemple illustre à quoi pourrait ressembler cette demande. Il n'est pas représentatif d'une décision d'implémentation.

"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”]  
} 
  ]  
} 
] 

L'agent répondrait : "Bonjour M. Paul, quel temps fait-il aujourd'hui à Cancun, Mx ?"

Une autre utilisation de ces paramètres de session consiste à définir des valeurs de paramètre dans les outils. Par exemple, une interrogation SQL peut extraire le contenu d'un panier à l'aide du paramètre de session {{sessionParam.CartID}}} :

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

Les variables de session sont définies par le développeur d'agent lorsqu'il crée ses agents et les valeurs de ces attributs sont définies par l'application client lors de la création ou de la reprise d'une session.

Vous pouvez configurer les paramètres suivants lors de la création d'une variable de session :

Paramétrage	Description
Variable requise	Activez cette option pour rendre cette variable de session obligatoire pour chaque appel d'appel de l'agent. La désactivation rend la variable de session facultative pour chaque appel d'appel.
Variable de journal	Activer pour capturer la valeur de la variable de session dans les journaux et les traces. La désactivation empêche la variable d'apparaître dans les journaux. Nous vous recommandons de désactiver ce paramètre pour les variables avec des données sensibles.
Nom	Nom de la variable de session. Utilisez un nom descriptif pour faciliter la détermination de l'objectif de la variable pour vous et les autres utilisateurs.
Valeur par défaut	Si elle est définie, la valeur par défaut est affectée à la variable de session si aucune autre valeur n'est définie dans l'appel d'appel. Si aucune valeur n'est indiquée, une valeur doit être affectée dans le cadre de l'appel d'appel.
Description	Description de la variable de session. Fournissez une description utile pour que vous et d'autres utilisateurs puissiez comprendre la fonction de la variable de session.

Exemple : utilisation de variables de session dans la configuration des outils

Vous pouvez utiliser une variable de session dans une configuration d'outil SQL dans le cadre de la requête SQL elle-même.

Dans cet exemple, la variable de session geo est utilisée pour filtrer le résultat de la requête SQL :

Vous pouvez utiliser des variables de session et des paramètres d'outil dans la même requête. Dans l'exemple ci-dessous, le paramètre titleID est défini par l'agent tandis que la variable de session geo est fournie par l'application appelante.

Variables de session générées par le système

Les variables de session sont générées automatiquement lorsqu'un serveur MCP distant est connecté à un agent et que le serveur MCP nécessite une authentification, comme un jeton de support.

La variable de session contient la valeur du jeton porteur. Le nom de cette variable de session générée par le système ne peut pas être modifié et est une variable obligatoire. La variable système est supprimée lorsque le noeud MCP est supprimé du canevas.

Dans Playground, vous indiquez une valeur pour la variable de session générée par le système. Dans ce cas, vous devez fournir un jeton porteur pour utiliser le serveur MCP. Vous pouvez sélectionner le même jeton (ou un autre) que celui que vous avez utilisé lors de la configuration du noeud MCP.

Il en va de même si vous déployez l'agent. Vous devrez fournir un jeton d'autorisation. Pour plus d'informations, reportez-vous à Affectation de valeurs aux variables de session à partir de la zone de lecture.

Exemple : affectation de valeurs à des variables de session lors de l'appel d'une adresse déployée

Dans cet exemple, vous disposez de deux variables de session : userLocation et UserName, l'application client transmet les valeurs de variable de session via le champ metadata de body. Nous allons montrer comment affecter des valeurs via Python et via l'interface de ligne de commande OCI.

Si vous utilisez la bibliothèque de demandes Python, la charge utile est la suivante :

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>,} 
)  

Sinon, si vous utilisez l'interface de ligne de commande OCI, la charge utile est la suivante :

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

Créer une variable de session dans l'onglet Variables de l'agent

Vous pouvez créer une variable de session et l'ajouter à votre agent à partir de l'onglet Variables.

1. Accédez à l'agent auquel vous voulez ajouter une variable de session.
2. Cliquez sur l'onglet Variables.
   
   

   

   
   
3. Cliquez sur Ajouter une variable de session.
   
   

   

   
   
4. Cochez cette case si la variable de session est obligatoire.
5. Indiquez si la valeur de la variable de session doit être enregistrée dans les journaux et les traces. Laissez ce paramètre désactivé pour les données confidentielles.
6. Fournissez une description et un nom explicites pour la variable de session.
7. Indiquez une valeur par défaut pour la variable de session. La valeur par défaut est affectée à la variable de session si aucune autre valeur n'est affectée dans le cadre de l'appel.
8. Cliquez sur Créer.

Reportez-vous aux variables de session dans les instructions de flux d'agent

Vous pouvez faire référence aux variables de session dans les instructions d'agent et les configurations d'outils, y compris la requête SQL et l'outil d'invite.

1. Accédez au flux de l'agent.
2. Cliquez sur le noeud SQL ou Invite de l'outil Playground.
   
   

   

   
   
3. Dans le champ Requête, commencez à saisir {{sessionvariables.
4. Sélectionnez la variable de session dans la liste des variables de session existantes.

Affichage des agents et des outils à l'aide d'une variable de session

Vous pouvez afficher la liste des agents et des outils à l'aide d'une variable de session spécifique dans l'onglet Variable de votre agent.

1. Accédez à un agent à l'aide de la variable de session pour laquelle vous voulez afficher les agents et outils associés.
2. Cliquez sur l'onglet Variable.
3. En regard de Utilisé dans : pour votre variable de session, cliquez sur le menu déroulant. La liste des agents et des outils utilisant la variable de session apparaît.

Affecter des valeurs aux variables de session à partir du Playground de test

Vous pouvez affecter des valeurs aux variables de session à tout moment à partir de l'onglet Playground de test.

1. Accédez à votre agent.
2. En haut de la zone de mémoire, cliquez sur Paramètres de session. La liste de toutes les variables de session de votre agent apparaît.
   
   

   

   
   
3. Modifiez les variables de session. Après la reprise de la session Playground de test, les valeurs des dernières variables de session affectées sont utilisées.