21 Sessionvariablen

Mit benutzerdefinierten, vom Agent definierten Sessionvariablen können Sie Ihren Agents während einer Benutzersession zusätzliche kontextbezogene Datenpunkte bereitstellen.

Was ist Sessionvariablen?

Benutzerdefinierte, vom Agent definierte Sessionvariablen stellen zusätzliche kontextbezogene Datenpunkte für den Agent während einer Benutzersession bereit. Die Variablen können für eine Vielzahl von Zwecken verwendet werden, einschließlich der Einstellung von Parametern in Tools, der Angabe allgemeiner Anweisungen an einen Agent und der Bereitstellung kontextbezogener Informationen über den Aufrufer und/oder die Anwendung, in die der Agent eingebettet ist.

Im Folgenden finden Sie ein vereinfachtes Szenario, in dem wir einen Kundensupport-Agent erstellen. Der Customer Support Agent ist in eine Retail-Website integriert. Wenn sich ein Benutzer auf der Retail-Website anmeldet, werden Informationen zu diesem Benutzer von der Client-Anwendung erfasst (Benutzer-ID, Benutzername, Geostandort, verwendetes Gerät, Warenkorb-ID usw.) und diese Informationen könnten vom nachgelagerten Support-Agent verwendet werden. Beispiel für die Verwendung dieser Sessionparameter im Feld "Agent-Anweisungen" in 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}}?  

Im obigen Beispiel werden drei Sessionvariablen verwendet:

• userName
• Bevorzugte Salutation
• aktueller BenutzerGeo

Der Agent hat keine Vorkenntnisse über den Benutzer, der mit der Retail-Website interagiert, weiß nicht, was der Benutzerstandort ist oder keinen Kontext darüber hat, was im Warenkorb des Benutzers enthalten ist. Grundsätzlich kann die Client-Anwendung alle oder eine Teilmenge dieser Werte kennen und diese Werte in einer Anforderung an den Agent übergeben. Im Folgenden finden Sie ein Beispiel dafür, wie eine Anforderung an den Agent aussehen könnte, einschließlich der Sessionparameter.

Hinweis:

Dieses Beispiel veranschaulicht, wie diese Anforderung aussehen könnte. Eine Implementierungsentscheidung ist nicht repräsentativ.

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

Der Agent antwortete zurück: "Hallo Herr Paul, wie ist das Wetter heute in Cancun, Mx?"

Eine weitere Verwendung dieser Sessionparameter besteht in der Einstellung von Parameterwerten in Tools. Beispiel: Mit dem Sessionparameter {{sessionParam.CartID}}} kann eine SQL-Abfrage den Inhalt eines Warenkorbs abrufen:

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

Die Sessionvariablen werden vom Agent-Entwickler definiert, wenn er ihre Agents erstellt, und die Werte dieser Attribute werden von der Clientanwendung festgelegt, wenn eine Session erstellt oder fortgesetzt wird.

Beim Erstellen einer neuen Sessionvariablen können Sie die folgenden Einstellungen konfigurieren:

Einstellung	Beschreibung
Erforderliche Variable	Aktivieren Sie diese Option, um diese Sessionvariable für jeden Aufruf des Agent erforderlich zu machen. Durch die Deaktivierung wird die Sessionvariable für jeden Aufruf optional.
Logvariable	Aktivieren Sie diese Option, um den Wert der Sessionvariablen in Logs und Traces zu erfassen. Durch Deaktivieren wird verhindert, dass die Variable in Logs angezeigt wird. Wir empfehlen, diese Einstellung für Variablen mit sensiblen Daten zu deaktivieren.
Name	Name der Sessionvariablen. Verwenden Sie einen beschreibenden Namen, um es Ihnen und anderen Benutzern zu erleichtern, den Zweck der Variablen zu bestimmen.
Standardwert	Wenn der Standardwert definiert ist, wird er der Sessionvariablen zugewiesen, wenn kein anderer Wert im Aufrufaufruf definiert ist. Wenn kein Wert angegeben wird, muss ein Wert als Teil des Aufrufaufrufs zugewiesen werden.
Beschreibung	Beschreibung der Sessionvariable. Geben Sie eine hilfreiche Beschreibung an, damit Sie und andere Benutzer die Funktion der Sessionvariable verstehen können.

Beispiel: Sessionvariablen in der Tools-Konfiguration verwenden

Sie können eine Sessionvariable in einer SQL-Toolkonfiguration als Teil der SQL-Abfrage selbst verwenden.

In diesem Beispiel wird die Sessionvariable geo verwendet, um das Ergebnis der SQL-Abfrage zu filtern:

Sie können Sessionvariablen und Toolparameter in derselben Abfrage verwenden. Im folgenden Beispiel wird der Parameter titleID vom Agent festgelegt, während die Sessionvariable geo von der aufrufenden Anwendung bereitgestellt wird.

Systemgenerierte Sessionvariablen

Sessionvariablen werden automatisch generiert, wenn ein Remote-MCP-Server mit einem Agent verbunden ist und der MCP-Server wie ein Bearer-Token eine Authentifizierung erfordert.

Die Sessionvariable enthält den Wert des Bearer-Tokens. Der Name dieser systemgenerierten Sessionvariablen kann nicht geändert werden und ist eine erforderliche Variable. Die Systemvariable wird gelöscht, wenn der MCP-Knoten aus der Leinwand entfernt wird.

Im Playground geben Sie einen Wert für die systemgenerierte Sessionvariable an. In diesem Fall müssen Sie ein Bearer-Token angeben, um den MCP-Server zu verwenden. Sie können dasselbe (oder ein anderes) Token auswählen, das Sie während der MCP-Knotenkonfiguration verwendet haben.

Gleiches gilt, wenn Sie den Agent bereitstellen. Sie müssen ein Autorisierungstoken angeben. Weitere Informationen finden Sie unter Sessionvariablen aus dem Playground Werte zuweisen.

Beispiel: Sessionvariablen beim Aufrufen eines bereitgestellten Endpunkts Werte zuweisen

In diesem Beispiel haben Sie zwei Sessionvariablen: userLocation und UserName, die Clientanwendung übergibt Sessionvariablenwerte durch das Feld metadata der body. Wir zeigen, wie Sie Werte über Python und über die OCI-CLI zuweisen können.

Wenn Sie die Python-Anforderungsbibliothek verwenden, ist die Payload wie folgt:

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

Wenn Sie die OCI-CLI verwenden, lautet die Payload alternativ:

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

Sessionvariablen in der Registerkarte "Agent-Variablen" erstellen

Sie können eine neue Sessionvariable erstellen und dem Agent über die Registerkarte "Variablen" hinzufügen.

1. Navigieren Sie zu dem Agent, dem Sie eine Sessionvariable hinzufügen möchten.
2. Klicken Sie auf die Registerkarte Variablen.
   
   

   

   
   
3. Klicken Sie auf Sessionvariable hinzufügen.
   
   

   

   
   
4. Aktivieren Sie dieses Kontrollkästchen, wenn die Sessionvariable eine erforderliche Variable ist.
5. Wählen Sie aus, ob der Wert der Sessionvariable in Logs und Traces aufgezeichnet werden soll. Lassen Sie diese Einstellung für sensible Daten deaktiviert.
6. Geben Sie einen aussagekräftigen Namen und die Beschreibung für die Sessionvariable an.
7. Geben Sie einen Standardwert für die Sessionvariable an. Der Standardwert wird der Sessionvariable zugewiesen, wenn im Rahmen des Aufrufs kein anderer Wert zugewiesen wird.
8. Klicken Sie auf Create.

Sessionvariablen in Agent Flow-Anweisungen referenzieren

Sie können auf Sessionvariablen in Agent-Anweisungen und Toolkonfigurationen verweisen, einschließlich der SQL- und Prompt-Toolabfrage.

1. Navigieren Sie zu Ihrem Agent-Ablauf.
2. Klicken Sie im Playground auf den Werkzeugknoten "SQL" oder "Prompt".
   
   

   

   
   
3. Geben Sie im Feld Abfrage {{sessionvariables} ein.
4. Wählen Sie die Sessionvariable aus der Liste der vorhandenen Sessionvariablen aus.

Agents und Tools mit Sessionvariablen anzeigen

Auf der Registerkarte "Variable" in Ihrem Agent können Sie eine Liste der Agents und Tools mit einer bestimmten Sessionvariable anzeigen.

1. Navigieren Sie zu einem Agent, indem Sie die Sessionvariable verwenden, für die Sie zugehörige Agents und Tools anzeigen möchten.
2. Klicken Sie auf das Register Variable.
3. Klicken Sie neben Verwendet in: für die Sessionvariable auf das Dropdown-Menü. Eine Liste der Agents und Tools, die diese Sessionvariable verwenden, wird angezeigt.

Sessionvariablen aus dem Playground Werte zuweisen

Auf der Registerkarte Playground können Sie Sessionvariablen jederzeit Werte zuweisen.

1. Navigieren Sie zu Ihrem Agent.
2. Klicken Sie oben im Playground auf Sessionparameter. Eine Liste aller Sessionvariablen in Ihrem Agent wird angezeigt.
   
   

   

   
   
3. Ändern Sie die Sessionvariablen. Nach der Fortsetzung der Playground-Session werden die zuletzt zugewiesenen Sessionvariablenwerte verwendet.