Le variabili vengono utilizzate per archiviare e recuperare i dati tra i turni di conversazione. Consentono agli agenti di ricordare le informazioni e mantenere il contesto. Quando scrivi le istruzioni del prompt per l'agente, puoi includere riferimenti a queste variabili.
Tipi di variabili
Il builder di agenti supporta due tipi distinti di variabili nelle istruzioni: variabili statiche e variabili dinamiche.
La scelta del tipo corretto dipende dal fatto che il valore della variabile debba cambiare durante la sessione dell'utente e dalla quantità di ottimizzazione necessaria per la latenza.
Variabili statiche
Le variabili statiche vengono compilate direttamente nel prompt dell'agente prima della chiamata al modello. Fungono da sostituzione di testo diretta 1:1 e vengono aggiornate di rado.
Le variabili statiche massimizzano la qualità delle istruzioni e sono adatte per le istruzioni condizionali in molti scenari. Utilizza le variabili statiche per i dati di configurazione, le regole aziendali rigide o i payload contestuali di grandi dimensioni che non cambiano durante la durata di una singola conversazione.
Per fare riferimento a una variabile statica per nome nelle istruzioni,
utilizza le doppie parentesi graffe:
{{variable_name}}.
Ad esempio, se stai creando un agente di vendita al dettaglio con un catalogo di prodotti statico di grandi dimensioni, puoi utilizzare un'istruzione come la seguente:
You are a helpful shopping assistant.
Please follow these business rules: {{business_rules}}.
Variabili dinamiche
Le variabili dinamiche possono essere aggiornate in qualsiasi momento durante una conversazione da strumenti, callback o richieste API.
Non vengono sostituite direttamente nel testo del prompt.
Quando vengono aggiornate, i nuovi valori vengono aggiunti come eventi state update alla cronologia delle conversazioni.
Ad esempio: <state_update>var_name: value</state_update>.
Utilizza le variabili dinamiche per le informazioni estratte dall'utente durante la sessione, gli output recuperati dalle API esterne (strumenti) o qualsiasi stato che cambia man mano che la conversazione procede.
Le seguenti limitazioni si applicano alle variabili dinamiche:
- Le variabili dinamiche vengono aggiunte alla cronologia delle conversazioni, quindi se una sessione lunga supera il limite della finestra contestuale, l'agente potrebbe dimenticare i valori delle variabili che vengono persi durante il taglio della cronologia.
- Le variabili dinamiche potrebbero comportare un'aderenza leggermente inferiore alle istruzioni rispetto alle variabili statiche. Ciò è dovuto al fatto che i valori delle variabili sono definiti più lontano dalle istruzioni. Questo può anche aggiungere latenza, poiché il modello di pensiero deve trovare il valore più lontano dall'istruzione.
Per fare riferimento a una variabile dinamica per nome nelle istruzioni, utilizza le parentesi graffe singole: {variable_name}.
Ad esempio, se stai creando un agente che deve autenticare un utente e poi cercare i dettagli specifici del suo account utilizzando uno strumento, puoi utilizzare un'istruzione come la seguente:
If the user asks for their balance, call the {@TOOL: LookupBalance}.
The tool will update the {current_account_balance} variable.
Always share the {current_account_balance} with the user.
Dati delle variabili
Le variabili hanno i seguenti dati:
- Nome: nome della variabile utilizzando la notazione snake_case
- Tipo: tipo di dati sottostante:
- Testo: valori stringa
- Numero: valori numerici
- Sì/No: valori booleani
- Oggetto personalizzato: fornisci uno schema per l'oggetto
- Elenco: elenco di variabili. Fornisci i valori come elenco delimitato da virgole.
- Valore predefinito: valore predefinito per la variabile
- Descrizione: descrizione facoltativa della variabile
Aggiornamento dei valori delle variabili
L'agente stesso non può aggiornare il valore di una variabile, ma gli strumenti e i callback possono aggiornare i valori delle variabili.
Le variabili dell'agente utilizzano lo
stato del contesto ADK,
che può essere utilizzato per aggiornare le variabili.
Una variabile globale denominata context è disponibile per l'utilizzo nel codice dello strumento Python.
Ad esempio, puoi utilizzare la seguente istruzione in uno strumento Python per aggiornare una variabile utilizzando le funzionalità ADK:
context.state["variable_name"] = value
Variabili di contesto della sessione integrate
Oltre alle variabili personalizzate, gli strumenti OpenAPI e MCP possono fare riferimento alle variabili di contesto della sessione integrate. Queste sono disponibili per impostazione predefinita e possono essere trasmesse all'interno delle intestazioni HTTP o dei parametri della richiesta. Non è possibile fare riferimento a queste variabili nelle istruzioni e non possono essere sovrascritte manualmente. Sono disponibili le seguenti variabili integrate:
$context.project_id,$context.project_number,$context.location,$context.app_id,$context.session_id,$context.turn_indexper gli ID risorsa a livello di app/sessione.$context.variables.variable_nameper un valore di variabile agente specifico.$context.variablesper tutti i valori delle variabili dell'agente come oggetto.