Variables

Les variables servent à stocker et à récupérer des données d'un tour de conversation à l'autre. Ils permettent aux agents de mémoriser des informations et de conserver le contexte. Lorsque vous rédigez des instructions de prompt pour votre agent, vous pouvez inclure des références à ces variables.

Types de variables

Le générateur d'agents accepte deux types de variables distincts dans les instructions : les variables statiques et les variables dynamiques.

Le choix du bon type dépend de la nécessité de modifier la valeur de la variable pendant la session de l'utilisateur et de l'optimisation de la latence.

Variables statiques

Les variables statiques sont compilées directement dans la requête de l'agent avant l'appel du modèle. Elles agissent comme une substitution de texte directe et sont rarement mises à jour.

Les variables statiques maximisent la qualité du suivi des instructions et conviennent aux instructions conditionnelles dans de nombreux scénarios. Utilisez des variables statiques pour les données de configuration, les règles métier rigides ou les charges utiles contextuelles volumineuses qui ne changent pas au cours d'une même conversation.

Pour référencer une variable statique par son nom dans vos instructions, utilisez des accolades doubles : {{variable_name}}.

Par exemple, si vous créez un agent de vente au détail avec un catalogue de produits statique volumineux, vous pouvez utiliser une instruction telle que :

You are a helpful shopping assistant.
Please follow these business rules: {{business_rules}}.

Avertissement : La mise à jour des valeurs des variables statiques invalide la mise en cache des requêtes, ce qui peut entraîner une latence plus élevée des appels de modèle.

Variables dynamiques

Les variables dynamiques peuvent être mises à jour à tout moment au cours d'une conversation par des outils, des rappels ou des requêtes API. Ils ne sont pas directement substitués dans le texte de votre requête. Lorsqu'ils sont mis à jour, leurs nouvelles valeurs sont ajoutées à l'historique de la conversation en tant qu'événements state update. Par exemple : <state_update>var_name: value</state_update>.

Utilisez des variables dynamiques pour les informations extraites de l'utilisateur pendant la session, les résultats récupérés à partir d'API externes (outils) ou tout état qui change au fur et à mesure de la conversation.

Les variables dynamiques présentent les inconvénients suivants :

• Les variables dynamiques sont ajoutées à l'historique des conversations. Par conséquent, si une longue session dépasse la limite de la fenêtre de contexte, l'agent peut oublier les valeurs des variables qui sont perdues lors de la suppression de l'historique.
• Les variables dynamiques peuvent entraîner un respect légèrement inférieur des instructions par rapport aux variables statiques. Cela est dû au fait que les valeurs des variables sont définies plus loin des instructions. Cela peut également ajouter de la latence, car le raisonnement du modèle doit trouver la valeur plus loin de l'instruction.

Pour référencer une variable dynamique par son nom dans vos instructions, utilisez des accolades simples : {variable_name}.

Par exemple, si vous créez un agent qui doit authentifier un utilisateur, puis rechercher les détails de son compte à l'aide d'un outil, vous pouvez utiliser une instruction de ce type :

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.

Données variables

Les variables contiennent les données suivantes :

• Name : nom de la variable en snake_case
• Type : type de données sous-jacent :
  • Texte : valeurs de chaîne
  • Nombre : valeurs numériques
  • Oui/Non : valeurs booléennes
  • Objet personnalisé : vous fournissez un schéma pour l'objet.
  • Liste : liste de variables. Fournissez les valeurs sous forme de liste d'éléments séparés par une virgule.
• Valeur par défaut : valeur par défaut de la variable.
• Description : description facultative de la variable

Mettre à jour les valeurs des variables

L'agent lui-même ne peut pas modifier la valeur d'une variable, mais les outils et les rappels le peuvent.

Les variables d'agent utilisent l'état de contexte ADK, qui peut être utilisé pour mettre à jour les variables. Une variable globale appelée context est disponible pour être utilisée dans le code de votre outil Python. Par exemple, vous pouvez utiliser l'instruction suivante dans un outil Python pour mettre à jour une variable à l'aide des fonctionnalités de l'ADK :

context.state["variable_name"] = value

Avertissement : Les modèles d'instructions sont affichés entre le rappel before_agent et le rappel before_model. Les mises à jour de variables effectuées dans un rappel before_agent prennent effet immédiatement au tour actuel, tandis que les mises à jour de variables effectuées dans un rappel before_model ne sont visibles dans les instructions affichées qu'au tour de conversation suivant. Référencez les variables mises à jour par les rappels before_model en tant que variables {{variable_name}} statiques plutôt que variables {variable_name} dynamiques, car les rappels before_model n'ajoutent pas d'événements <state_update> à l'historique des conversations.

Variables de contexte de session intégrées

Au-delà des variables personnalisées, les outils OpenAPI et MCP peuvent référencer des variables de contexte de session intégrées. Ils sont disponibles par défaut et peuvent être transmis dans les en-têtes HTTP ou les paramètres de requête. Ces variables ne peuvent pas être référencées dans les instructions ni être écrasées manuellement. Les variables intégrées suivantes sont disponibles :

• $context.project_id, $context.project_number, $context.location, $context.app_id, $context.session_id, $context.turn_index pour les ID de ressources au niveau de l'application/de la session.
• $context.variables.variable_name pour une valeur de variable d'agent spécifique.
• $context.variables pour toutes les valeurs de variable d'agent en tant qu'objet.