Référence du format d'exportation

Ce document décrit la structure des répertoires et l'organisation des fichiers pour un fichier d'exportation et d'importation d'application d'agent.

Le format est un fichier ZIP qui, une fois extrait, contient un répertoire racine correspondant au nom de l'application de l'agent.

Tous les chemins d'accès décrits dans ce document sont relatifs au répertoire racine. Toutes les références à d'autres objets (agents, outils, etc.) doivent utiliser leurs valeurs displayName.

Les noms d'outils suivants sont réservés :

• end_session
• transfer_to_agent
• customize_response

Lorsque vous importez et exportez des fichiers, vous pouvez utiliser le format JSON ou YAML pour les fichiers individuels. Les fichiers décrits dans ce document utilisent YAML, mais les membres JSON sont similaires.

Répertoire racine

Le répertoire racine contient les principaux fichiers de configuration de l'application :

• app.yaml : fichier de configuration central pour l'application de l'agent. Il définit :
  • displayName (chaîne) : nom de l'application lisible par l'utilisateur.
  • rootAgent (chaîne) : Nom à afficher de l'agent qui lance la conversation. N'utilisez pas le nom du fichier ni celui du répertoire.
  • audioProcessingConfig (objet) : Paramètres de synthèse vocale et de reconnaissance vocale.
    • synthesizeSpeechConfigs (map) : Les clés sont des codes de langue (par exemple, en-US), les valeurs sont des objets contenant voice (chaîne).
    • inactivityTimeout (chaîne) : Chaîne de durée (par exemple, "2s").
    • ambientSoundConfig (objet) : configure le bruit de fond, contenant volumeGainDb (float) et prebuiltAmbientSound (string).
  • loggingSettings (objet) : configuration des journaux et de l'enregistrement.
    • redactionConfig (objet) : Configuration pour masquer les informations sensibles.
    • audioRecordingConfig (objet) : contient gcsBucket (chaîne).
    • bigqueryExportSettings (objet) : contient enabled (booléen), project (chaîne) et dataset (chaîne).
    • cloudLoggingSettings (objet) : Contient enableCloudLogging (booléen).
  • guardrails (liste de chaînes) : liste des noms de garde-fous appliqués globalement.
  • variableDeclarations (liste d'objets) : définitions de schéma pour les variables globales. Chaque objet contient les éléments suivants :
    • name (chaîne) : Nom de la variable.
    • description (chaîne) : explication de l'objectif de la variable.
    • schema (objet) : Définition du type (par exemple, { type: STRING } ou propriétés imbriquées).
    • default (n'importe quelle valeur) : valeur par défaut de la variable.
  • globalInstruction (chaîne) : chemin d'accès au fichier d'instructions système global.
  • languageSettings (objet) :
    • defaultLanguageCode (chaîne) : par exemple, "en-US".
    • supportedLanguageCodes (liste de chaînes) : par exemple, ["fr", "es"].
    • enableMultilingualSupport (booléen).
• environment.json : paires clé/valeur pour les variables spécifiques à l'environnement.
• global_instruction.txt : fichier texte contenant la requête ou l'instruction principale.

agents/

Ce répertoire contient les définitions de tous les agents de l'application.

Structure de l'agent (agents/<agent_name>/)

• <agent_name>.yaml : fichier de configuration de l'agent spécifique.
  • displayName (chaîne) : nom de l'agent.
  • modelSettings (objet) : contient model (chaîne).
  • instruction (chaîne) : chemin d'accès au fichier d'instructions par rapport à la racine (par exemple, agents/<agent_name>/instruction.txt).
  • tools (liste de chaînes) : noms à afficher des outils locaux disponibles pour cet agent.
  • toolsets (liste d'objets) : ensembles d'outils OpenAPI disponibles pour cet agent. Chaque objet contient les éléments suivants :
    • toolset (chaîne) : Nom de l'ensemble d'outils.
    • toolIds (liste de chaînes) : ID d'opération spécifiques à exposer à partir de cet ensemble d'outils.
  • childAgents (liste de chaînes) : Noms à afficher des autres agents vers lesquels cet agent peut effectuer une transition. Cette relation est unidirectionnelle (parent à enfant). Les agents enfants ne doivent pas lister leurs parents comme enfants, sauf si une transition circulaire est explicitement prévue. Les agents ne peuvent pas avoir plusieurs parents (sauf les agents utilitaires partagés tels que les agents d'escalade ou de satisfaction). L'agent racine ne peut pas être listé comme enfant d'un autre agent.
  • *Callbacks (liste d'objets) : utilisé pour beforeModelCallbacks, afterModelCallbacks, etc. Chaque objet contient les éléments suivants :
    • pythonCode (chaîne) : chemin d'accès au script de rappel.
    • disabled (booléen) : indique si le rappel est actif.
    • description (chaîne) : description de la logique du rappel.
• instruction.txt : invite système spécifique à cet agent. Les références aux outils doivent utiliser la syntaxe {@TOOL: <tool_display_name>}, les références aux autres agents doivent utiliser {@AGENT: <agent_display_name>} et les variables doivent être accessibles à l'aide de {variable_name} (par exemple, {firstname}).
• before_model_callbacks/, etc. : répertoires pour les scripts de rappel.

tools/

Ce répertoire contient des outils "locaux", qui peuvent être des fonctions Python ou des récupérateurs de Data Store.

Structure de l'outil (tools/<tool_name>/)

• <tool_name>.yaml : configuration de l'outil. Utilisez pythonFunction OU dataStoreTool, mais pas les deux.
  • displayName (chaîne) : nom de l'outil.
  • Option A : Outil de fonction Python
    • pythonFunction (objet) :
      • name (chaîne) : nom de la fonction.
      • pythonCode (chaîne) : chemin d'accès à l'implémentation Python par rapport à la racine (par exemple, tools/<tool_name>/python_function/python_code.py).
      • description (chaîne) : description sémantique pour le LLM.
  • Option B : Outil Data Store
    • dataStoreTool (objet) :
      • name (chaîne) : nom de l'outil (correspond généralement au nom du répertoire).
      • description (chaîne) : description de l'objectif de l'outil pour l'agent.
      • engineSource (objet) :
        • dataStoreSources (liste d'objets) :
          • dataStore (objet) :
            • name (chaîne) : Nom complet de la ressource du data store (par exemple, projects/...) ou variable d'environnement (par exemple, $env_var).
      • modalityConfigs (liste d'objets) : facultatif. Configure le comportement pour TEXT ou AUDIO.
        • modalityType (énumération) : TEXT ou AUDIO.
        • groundingConfig (objet) :
          • groundingLevel (float) : par exemple, 4.0.
  • executionType (enum) : par exemple, SYNCHRONOUS.
• python_function/python_code.py : fichier de code Python (uniquement pour les outils de fonction Python).

toolsets/

Ce répertoire contient des ensembles d'outils basés sur OpenAPI.

Structure de l'ensemble d'outils (toolsets/<toolset_name>/)

• <toolset_name>.yaml : configuration de l'ensemble d'outils.
  • displayName (chaîne) : nom de l'ensemble d'outils.
  • openApiToolset (objet) :
    • openApiSchema (chaîne) : Chemin d'accès au fichier de schéma OpenAPI par rapport à la racine (par exemple, toolsets/<toolset_name>/open_api_toolset/open_api_schema.yaml).
    • apiAuthentication (objet) : configuration de l'authentification (par exemple, serviceAgentIdTokenAuthConfig).
• open_api_toolset/open_api_schema.yaml : fichier de spécification OpenAPI.

guardrails/

Ce répertoire définit les filtres de sécurité du contenu.

Structure des garde-fous (guardrails/<guardrail_name>/)

• <guardrail_name>.yaml :
  • displayName (chaîne) : nom du garde-fou.
  • description (chaîne) : objectif.
  • enabled (booléen) : indique si l'élément est actif.
  • contentFilter (objet) :
    • bannedContentsInUserInput (liste de chaînes) : mots et expressions à bloquer.
    • matchType (chaîne) : par exemple, "WORD_BOUNDARY_STRING_MATCH".
  • action (objet) :
    • respondImmediately (objet) :
      • responses (liste d'objets) : chaque objet contient text (chaîne).

examples/

Ce répertoire contient les définitions des exemples few-shot utilisés dans l'application d'agent.

Exemple de structure (examples/<example_name>/)

• <example_name>.yaml : configuration de l'exemple.

evaluations/

Ce répertoire contient les définitions de test.

Structure de l'évaluation (evaluations/<evaluation_name>/)

• <evaluation_name>.yaml : définit les scénarios de test avec les entrées/sorties attendues.

evaluationDatasets/

Ce répertoire contient des ensembles de données d'évaluation.

Structure de l'ensemble de données d'évaluation (evaluationDatasets/<evaluation_dataset_name>/)

• <evaluation_dataset_name>.yaml : configuration de l'ensemble de données d'évaluation.