Variables

Les variables permettent de stocker et de récupérer des données entre les tours de conversation. Elles permettent aux agents de se souvenir des informations et de maintenir le contexte. Lorsque vous rédigez des instructions de requête 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 type approprié dépend de la nécessité de modifier la valeur de la variable pendant la session de l'utilisateur et de la mesure dans laquelle vous devez optimiser la latence.

Variables statiques

Les variables statiques sont compilées directement dans l'invite de l'agent avant l'appel du modèle. Elles servent de substitution directe de texte à texte et sont mises à jour peu fréquemment.

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 faire référence à une variable statique par son nom dans vos instructions, utilisez des doubles accolades : {{variable_name}}.

Par exemple, si vous créez un agent commercial avec un catalogue de produits statique et volumineux, vous pouvez utiliser une instruction telle que :

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

Variables dynamiques

Les outils, les rappels ou les requêtes d'API peuvent mettre à jour les variables dynamiques à tout moment au cours d'une conversation. Elles ne sont pas directement substituées au texte de votre requête. Au lieu de cela, lorsqu'elles sont mises à jour, leurs nouvelles valeurs sont ajoutées en tant qu'événements state update à l'historique des conversations. Par exemple : <state_update>var_name: value</state_update>.

Utilisez des variables dynamiques pour les informations extraites de l'utilisateur au cours de 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 inconvénients suivants s'appliquent aux variables dynamiques :

  • 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 de variables qui sont perdues lors de la suppression de l'historique.
  • Les variables dynamiques peuvent entraîner une conformité légèrement inférieure aux instructions par rapport aux variables statiques. Cela s'explique par le fait que les valeurs des variables sont définies plus loin des instructions. Cela peut également ajouter de la latence, car la réflexion du modèle doit trouver la valeur plus loin de l'instruction.

Pour faire référence à 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 spécifiques de son compte à l'aide d'un outil, vous pouvez utiliser une instruction comme celle-ci :

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) : 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 des variables. Indiquez les valeurs sous la forme d'une 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 peuvent le faire.

Les variables d'agent utilisent l'état du 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 ADK :

context.state["variable_name"] = value

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 des en-têtes HTTP ou des paramètres de requête. Ces variables ne peuvent pas être référencées dans les instructions ni être remplacé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 agent variable spécifique.
  • $context.variables pour toutes les valeurs de variable d'agent sous forme d'objet.