Riferimento al formato di esportazione

Questo documento descrive la struttura delle directory e l'organizzazione dei file per un file di esportazione e importazione dell'applicazione agente.

Il formato è un file ZIP che, una volta estratto, contiene una directory principale che corrisponde al nome dell'applicazione dell'agente.

Tutti i percorsi descritti in questo documento sono relativi alla directory principale. Tutti i riferimenti ad altri oggetti (agenti, strumenti e così via) devono utilizzare i relativi valori displayName.

I seguenti nomi di strumenti sono riservati:

  • end_session
  • transfer_to_agent
  • customize_response

Durante l'importazione e l'esportazione, puoi utilizzare JSON o YAML per i singoli file. I file descritti in questo documento utilizzano YAML, ma i membri JSON sono simili.

Directory root

La directory principale contiene i file di configurazione principali per l'applicazione:

  • app.yaml: Il file di configurazione centrale per l'applicazione agente. Definisce:
    • displayName (stringa): Il nome leggibile dell'applicazione.
    • rootAgent (stringa): Il nome visualizzato dell'agente che avvia la conversazione. Non utilizzare il nome del file o della directory.
    • audioProcessingConfig (oggetto): Impostazioni per la sintesi vocale e lo speech-to-text.
      • synthesizeSpeechConfigs (mappa): le chiavi sono codici di lingua (ad esempio en-US), i valori sono oggetti contenenti voice (stringa).
      • inactivityTimeout (stringa): Stringa di durata (ad esempio, "2s").
      • ambientSoundConfig (oggetto): Configura il rumore di fondo, contenente volumeGainDb (float) e prebuiltAmbientSound (stringa).
    • loggingSettings (oggetto): Configurazione per log e registrazione.
      • redactionConfig (oggetto): Configurazione per l'oscuramento delle informazioni sensibili.
      • audioRecordingConfig (oggetto): Contiene gcsBucket (stringa).
      • bigqueryExportSettings (oggetto): Contiene enabled (booleano), project (stringa), dataset (stringa).
      • cloudLoggingSettings (oggetto): Contiene enableCloudLogging (booleano).
    • guardrails (elenco di stringhe): Un elenco di nomi di guardrail applicati a livello globale.
    • variableDeclarations (elenco di oggetti): Definizioni dello schema per le variabili globali. Ogni oggetto contiene:
      • name (stringa): Nome della variabile.
      • description (stringa): Spiegazione dello scopo della variabile.
      • schema (oggetto): Definizione del tipo (ad esempio { type: STRING } o proprietà nidificate).
      • default (qualsiasi): Il valore predefinito per la variabile.
    • globalInstruction (stringa): percorso del file di istruzioni di sistema globali.
    • languageSettings (oggetto):
      • defaultLanguageCode (stringa): ad esempio, "en-US".
      • supportedLanguageCodes (elenco di stringhe): ad esempio, ["fr", "es"].
      • enableMultilingualSupport (booleano).
  • environment.json: Coppie chiave-valore per le variabili specifiche dell'ambiente.
  • global_instruction.txt: Un file di testo contenente il prompt/l'istruzione principale.

agents/

Questa directory contiene le definizioni di tutti gli agenti nell'applicazione.

Struttura dell'agente (agents/<agent_name>/)

  • <agent_name>.yaml: Il file di configurazione per l'agente specifico.
    • displayName (stringa): Il nome dell'agente.
    • modelSettings (oggetto): Contiene model (stringa).
    • instruction (stringa): percorso del file di istruzioni relativo alla radice (ad esempio, agents/<agent_name>/instruction.txt).
    • tools (elenco di stringhe): Nomi visualizzati degli strumenti locali disponibili per questo agente.
    • toolsets (elenco di oggetti): Set di strumenti OpenAPI disponibili per questo agente. Ogni oggetto contiene:
      • toolset (stringa): il nome del set di strumenti.
      • toolIds (elenco di stringhe): ID operazione specifici da esporre dal toolset.
    • childAgents (elenco di stringhe): Nomi visualizzati di altri agenti a cui questo agente può passare. Questa relazione è unidirezionale (da genitore a figlio); gli agenti secondari non devono elencare i genitori come figli a meno che non sia esplicitamente prevista una transizione circolare. Gli agenti non possono avere più di un genitore (eccezione: agenti di utilità condivisi come Escalation o Soddisfazione). L'agente principale non può essere elencato come agente secondario di un altro agente.
    • *Callbacks (elenco di oggetti): Utilizzato per beforeModelCallbacks, afterModelCallbacks e così via. Ogni oggetto contiene:
      • pythonCode (stringa): percorso dello script di callback.
      • disabled (booleano): indica se il callback è attivo.
      • description (stringa): descrizione della logica del callback.
  • instruction.txt: Il prompt di sistema specifico per questo agente. I riferimenti agli strumenti devono utilizzare la sintassi {@TOOL: <tool_display_name>}, i riferimenti ad altri agenti devono utilizzare {@AGENT: <agent_display_name>} e le variabili devono essere accessibili utilizzando {variable_name} (ad esempio, {firstname}).
  • before_model_callbacks/ e così via: Directory per gli script di richiamata.

tools/

Questa directory contiene strumenti "locali", che possono essere funzioni Python o retriever Data Store.

Struttura dello strumento (tools/<tool_name>/)

  • <tool_name>.yaml: Configurazione dello strumento. Utilizza pythonFunction O dataStoreTool, non entrambi.
    • displayName (stringa): il nome dello strumento.
    • Opzione A: strumento Funzione Python
      • pythonFunction (oggetto):
        • name (stringa): il nome della funzione.
        • pythonCode (stringa): percorso dell'implementazione di Python rispetto alla radice (ad esempio, tools/<tool_name>/python_function/python_code.py).
        • description (stringa): Descrizione semantica per l'LLM.
    • Opzione B: strumento Data Store
      • dataStoreTool (oggetto):
        • name (stringa): Il nome dello strumento (in genere corrisponde al nome della directory).
        • description (stringa): Descrizione dello scopo dello strumento per l'agente.
        • engineSource (oggetto):
          • dataStoreSources (elenco di oggetti):
            • dataStore (oggetto):
              • name (stringa): Il nome completo della risorsa del datastore (ad esempio, projects/...) o una variabile di ambiente (ad esempio, $env_var).
        • modalityConfigs (elenco di oggetti): Facoltativo. Configura il comportamento per TEXT o AUDIO.
          • modalityType (enum): TEXT o AUDIO.
          • groundingConfig (oggetto):
            • groundingLevel (float): ad esempio, 4.0.
    • executionType (enum): ad esempio, SYNCHRONOUS.
  • python_function/python_code.py: Il file di codice Python (solo per gli strumenti per le funzioni Python).

toolsets/

Questa directory contiene set di strumenti basati su OpenAPI.

Struttura del toolset (toolsets/<toolset_name>/)

  • <toolset_name>.yaml: Configurazione del set di strumenti.
    • displayName (stringa): Nome del set di strumenti.
    • openApiToolset (oggetto):
      • openApiSchema (stringa): percorso del file schema OpenAPI relativo alla radice (ad esempio, toolsets/<toolset_name>/open_api_toolset/open_api_schema.yaml).
      • apiAuthentication (oggetto): Configurazione dell'autenticazione (ad esempio, serviceAgentIdTokenAuthConfig).
  • open_api_toolset/open_api_schema.yaml: Il file di specifica OpenAPI.

guardrails/

Questa directory definisce i filtri per la sicurezza dei contenuti.

Struttura dei guardrail (guardrails/<guardrail_name>/)

  • <guardrail_name>.yaml:
    • displayName (stringa): il nome del guardrail.
    • description (stringa): Scopo.
    • enabled (booleano): indica se è attivo.
    • contentFilter (oggetto):
      • bannedContentsInUserInput (elenco di stringhe): Parole e frasi da bloccare.
      • matchType (stringa): ad esempio, "WORD_BOUNDARY_STRING_MATCH".
    • action (oggetto):
      • respondImmediately (oggetto):
        • responses (elenco di oggetti): ogni oggetto contiene text (stringa).

examples/

Questa directory contiene le definizioni degli esempi few-shot utilizzati nell'applicazione agente.

Struttura di esempio (examples/<example_name>/)

  • <example_name>.yaml: Configurazione per l'esempio.

evaluations/

Questa directory contiene le definizioni dei test.

Struttura della valutazione (evaluations/<evaluation_name>/)

  • <evaluation_name>.yaml: Definisce gli scenari di test con input/output previsti.

evaluationDatasets/

Questa directory contiene set di dati di valutazione.

Struttura del set di dati di valutazione (evaluationDatasets/<evaluation_dataset_name>/)

  • <evaluation_dataset_name>.yaml: Configurazione per il set di dati di valutazione.