21 Variabili di sessione
È possibile utilizzare variabili di sessione personalizzate definite dall'agente per fornire datapoint contestuali aggiuntivi agli agenti durante una sessione utente.
Descrizione delle variabili di sessione
Le variabili di sessione personalizzate definite dall'agente forniscono all'agente datapoint contestuali aggiuntivi durante una sessione utente. Le variabili possono essere utilizzate per una serie di scopi, tra cui l'impostazione di valori di parametri negli strumenti, fornendo istruzioni generali a un agente e fornendo informazioni contestuali sul chiamante e/o sull'applicazione in cui è incorporato l'agente.
Ecco uno scenario semplificato in cui stiamo creando un agente di assistenza clienti. L'agente di assistenza clienti è integrato all'interno di un sito Web di vendita al dettaglio. Quando un utente accede al sito Web retail, le informazioni su tale utente vengono acquisite dall'applicazione client (ID utente, nome utente, posizione geografica, dispositivo utilizzato, ID carrello della spesa, ecc.) e tali informazioni potrebbero essere utilizzate dall'agente di supporto a valle. Esaminiamo un esempio di come questi parametri di sessione potrebbero essere utilizzati nel campo delle istruzioni dell'agente 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}}? - userName
- Formula di anticipo preferita
- utente correnteGeo
L'agente non ha alcuna conoscenza preliminare dell'utente che interagisce con il sito web di vendita al dettaglio, non sa quale sia la posizione dell'utente o non ha alcun contesto su ciò che è nel carrello dell'utente. In linea di principio, l'applicazione client potrebbe conoscere tutti o un sottoinsieme di tali valori e passare tali valori in una richiesta all'agente. Ecco un esempio di come potrebbe essere una richiesta all'agente, inclusi i parametri della sessione.
Nota
In questo esempio viene illustrato l'aspetto di questa richiesta. Non è rappresentativo di una decisione di implementazione."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'agente avrebbe risposto: "Ciao signor Paul, com'è il tempo oggi a Cancun, Mx?"
Un altro uso di questi parametri di sessione è l'impostazione dei valori dei parametri negli strumenti. Ad esempio, una query SQL potrebbe recuperare il contenuto di un carrello utilizzando il parametro di sessione {{sessionParam.CartID}}:
Select productID, productName, productDescription,
productPrice from cartTable where cartID ==
{{sessionVariable.cartID}} Le variabili di sessione vengono definite dallo sviluppatore agente quando crea i propri agenti e i valori di tali attributi vengono impostati dall'applicazione client quando viene creata o ripresa una sessione.
È possibile configurare le seguenti impostazioni quando si crea una nuova variabile di sessione:
| Impostazione | Descrizione |
|---|---|
| Variabile obbligatoria | Abilitare per rendere necessaria questa variabile di sessione per ogni chiamata di richiamo dell'agente. La disabilitazione rende la variabile di sessione facoltativa per ogni chiamata di richiamo. |
| Variabile di log | Consente di acquisire il valore della variabile di sessione nei log e nei trace. La disabilitazione impedisce la visualizzazione della variabile nei log. Si consiglia di disabilitare questa impostazione per le variabili con dati riservati. |
| Nome | Nome della variabile di sessione. Utilizzare un nome descrittivo per semplificare la determinazione dello scopo della variabile da parte dell'utente e di altri utenti. |
| Valore predefinito | Se definito, il valore predefinito viene assegnato alla variabile di sessione se nella chiamata di richiamo non è definito un altro valore. Se lasciato vuoto, un valore deve essere assegnato come parte della chiamata di richiamo. |
| Descrizione | Descrizione della variabile di sessione. Fornire una descrizione utile in modo che tu e gli altri utenti siate in grado di comprendere la funzione della variabile di sessione. |
Esempio: utilizzo delle variabili di sessione nella configurazione di Tools
È possibile utilizzare una variabile di sessione in una configurazione dello strumento SQL come parte della query SQL stessa.
In questo esempio, la variabile di sessione geo viene utilizzata per filtrare il risultato della query SQL:
È possibile utilizzare variabili di sessione e parametri degli strumenti all'interno della stessa query. Nell'esempio seguente, il parametro titleID viene impostato dall'agente mentre la variabile di sessione geo viene fornita dall'applicazione chiamante.
Variabili di sessione generate dal sistema
Le variabili di sessione vengono generate automaticamente quando un server MCP remoto è connesso a un agente e tale server MCP richiede l'autenticazione, come un token bearer.
La variabile di sessione contiene il valore del token bearer. Il nome di questa variabile di sessione generata dal sistema non può essere modificato ed è una variabile obbligatoria. La variabile di sistema viene eliminata quando il nodo MCP viene rimosso dallo sfondo.
In Playground, si fornisce un valore per la variabile di sessione generata dal sistema. In questo caso, è necessario fornire un token bearer per utilizzare il server MCP. È possibile selezionare lo stesso token (o un token diverso) utilizzato durante la configurazione del nodo MCP.
Lo stesso vale se si distribuisce l'agente. Sarà necessario fornire un token di autorizzazione. Per ulteriori informazioni, vedere Assegnare valori alle variabili di sessione dall'area di esecuzione.
Esempio: assegnazione di valori alle variabili di sessione durante la chiamata di un endpoint distribuito
In questo esempio, sono disponibili due variabili di sessione: userLocation e UserName. L'applicazione client passa i valori delle variabili di sessione tramite il campo metadata di body. Dimostreremo come è possibile assegnare valori tramite Python e l'interfaccia CLI OCI.
Se si utilizza la libreria di richieste Python, il payload è il seguente:
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>,}
) In alternativa, se si utilizza l'interfaccia CLI OCI, il payload è il seguente:
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>" Crea una variabile di sessione nella scheda Variabili agente
È possibile creare una nuova variabile di sessione e aggiungerla all'agente dalla scheda Variabili.
- Fare clic sulla scheda Variabili.
- Fare clic su
Aggiungi variabile di sessione.
Fare riferimento alle variabili di sessione nelle istruzioni del flusso agente
È possibile fare riferimento alle variabili di sessione nelle istruzioni dell'agente e nelle configurazioni degli strumenti, inclusa la query degli strumenti SQL e Prompt.
- Fare clic sul nodo dello strumento SQL o Prompt nell'area di esecuzione.
Visualizzare agenti e strumenti utilizzando una variabile di sessione
È possibile visualizzare una lista di agenti e strumenti utilizzando una variabile di sessione specifica dalla scheda Variabile dell'agente.
- Passare a un agente utilizzando la variabile di sessione per la quale si desidera visualizzare gli agenti e gli strumenti correlati.
- Fare clic sulla scheda Variabile.
- Avanti, fare clic sul menu a discesa Utilizzato in: per la variabile di sessione. Viene visualizzato un elenco di agenti e strumenti che utilizzano la variabile di sessione.
Assegna valori a variabili di sessione da Playground
È possibile assegnare valori alle variabili di sessione in qualsiasi momento dalla scheda Playground.
- Nella parte superiore dell'area di gioco, fare clic su
Parametri sessione. Viene visualizzato un elenco di tutte le variabili di sessione nell'agente.
- Modificare le variabili di sessione. Dopo aver ripreso la sessione di Playground, vengono utilizzati i valori delle ultime variabili di sessione assegnate.
