Referenz für Exportformate

In diesem Dokument werden die Verzeichnisstruktur und die Dateiorganisation für eine Export- und Importdatei für Agentenanwendungen beschrieben.

Das Format ist eine ZIP-Datei, die nach dem Extrahieren ein Stammverzeichnis enthält, das dem Namen der Agentenanwendung entspricht.

Alle in diesem Dokument beschriebenen Pfade sind relativ zum Stammverzeichnis. Alle Verweise auf andere Objekte (Agents, Tools usw.) müssen die Werte für displayName verwenden.

Die folgenden Toolnamen sind reserviert:

  • end_session
  • transfer_to_agent
  • customize_response

Beim Importieren und Exportieren können Sie für die einzelnen Dateien entweder JSON oder YAML verwenden. In den in diesem Dokument beschriebenen Dateien wird YAML verwendet, die JSON-Elemente sind jedoch ähnlich.

Stammverzeichnis

Das Stammverzeichnis enthält die Hauptkonfigurationsdateien für die Anwendung:

  • app.yaml: Die zentrale Konfigurationsdatei für die Agentenanwendung. Sie definiert:
    • displayName (String): Der für Menschen lesbare Name der Anwendung.
    • rootAgent (String): Der Anzeigename des Agents, der die Unterhaltung startet. Verwenden Sie nicht den Dateinamen oder Verzeichnisnamen.
    • audioProcessingConfig (Objekt): Einstellungen für Sprachausgabe und Sprache zu Text.
      • synthesizeSpeechConfigs (Map): Die Schlüssel sind Gebietsschemacodes (z. B. en-US), die Werte sind Objekte mit voice (String).
      • inactivityTimeout (String): Dauerstring (z. B. „2s“).
      • ambientSoundConfig (Objekt): Konfiguriert Hintergrundgeräusche und enthält volumeGainDb (Float) und prebuiltAmbientSound (String).
    • loggingSettings (Objekt): Konfiguration für Logs und Aufzeichnungen.
      • redactionConfig (Objekt): Konfiguration zum Entfernen vertraulicher Informationen.
      • audioRecordingConfig (Objekt): Enthält gcsBucket (String).
      • bigqueryExportSettings (Objekt): Enthält enabled (boolesch), project (String), dataset (String).
      • cloudLoggingSettings (Objekt): Enthält enableCloudLogging (boolesch).
    • guardrails (Liste von Strings): Eine Liste von Guardrail-Namen, die global angewendet werden.
    • variableDeclarations (Liste von Objekten): Schemadefinitionen für globale Variablen. Jedes Objekt enthält:
      • name (String): Variablenname.
      • description (String): Erläuterung des Zwecks der Variablen.
      • schema (Objekt): Typdefinition (z. B. { type: STRING } oder verschachtelte Eigenschaften).
      • default (beliebig): Der Standardwert für die Variable.
    • globalInstruction (String): Pfad zur Datei mit der globalen Systemanweisung.
    • languageSettings (Objekt):
      • defaultLanguageCode (String): z. B. „de-DE“.
      • supportedLanguageCodes (Liste von Strings): z. B. ["fr", "es"].
      • enableMultilingualSupport (boolesch).
  • environment.json: Schlüssel/Wert-Paare für umgebungsspezifische Variablen.
  • global_instruction.txt: Eine Textdatei mit dem primären Prompt/der primären Anweisung.

agents/

Dieses Verzeichnis enthält die Definitionen für alle Agents in der Anwendung.

Agentstruktur (agents/<agent_name>/)

  • <agent_name>.yaml: Die Konfigurationsdatei für den jeweiligen Agent.
    • displayName (String): Der Name des Agents.
    • modelSettings (Objekt): Enthält model (String).
    • instruction (String): Pfad zur Anweisungsdatei relativ zum Stammverzeichnis (z. B. agents/<agent_name>/instruction.txt).
    • tools (Liste von Strings): Anzeigenamen der lokalen Tools, die für diesen Agent verfügbar sind.
    • toolsets (Liste von Objekten): OpenAPI-Toolsets, die für diesen Agent verfügbar sind. Jedes Objekt enthält:
      • toolset (String): Der Name des Toolsets.
      • toolIds (Liste von Strings): Bestimmte Vorgangs-IDs, die aus diesem Toolset verfügbar gemacht werden sollen.
    • childAgents (Liste von Strings): Anzeigenamen anderer Agents, zu denen dieser Agent wechseln kann. Diese Beziehung ist unidirektional (übergeordnet zu untergeordnet). Untergeordnete Agents sollten ihre übergeordneten Agents nicht als untergeordnete Agents auflisten, es sei denn, ein zirkulärer Übergang ist ausdrücklich beabsichtigt. Agents können nicht mehr als einen übergeordneten Agent haben (Ausnahme: gemeinsam genutzte Utility-Agents wie „Escalation“ oder „Satisfaction“). Der Root-Agent kann nicht als untergeordneter Agent eines anderen Agents aufgeführt werden.
    • *Callbacks (Liste von Objekten): Wird für beforeModelCallbacks, afterModelCallbacks usw. verwendet. Jedes Objekt enthält:
      • pythonCode (String): Pfad zum Callback-Skript.
      • disabled (boolesch): Gibt an, ob der Callback aktiv ist.
      • description (String): Beschreibung der Logik des Callbacks.
  • instruction.txt: Der spezifische Systemprompt für diesen Agent. Verweise auf Tools müssen die Syntax {@TOOL: <tool_display_name>} verwenden, Verweise auf andere Agents müssen {@AGENT: <agent_display_name>} verwenden, und auf Variablen muss mit {variable_name} zugegriffen werden (z. B. {firstname}).
  • before_model_callbacks/usw.: Verzeichnisse für Callback-Skripts.

tools/

Dieses Verzeichnis enthält „lokale“ Tools, die entweder Python-Funktionen oder Data Store-Abrufer sein können.

Toolstruktur (tools/<tool_name>/)

  • <tool_name>.yaml: Konfiguration für das Tool. Verwenden Sie ENTWEDER pythonFunction ODER dataStoreTool, nicht beides.
    • displayName (String): Der Name des Tools.
    • Option A: Python-Funktionstool
      • pythonFunction (Objekt):
        • name (String): Der Funktionsname.
        • pythonCode (String): Pfad zur Python-Implementierung relativ zum Stammverzeichnis (z. B. tools/<tool_name>/python_function/python_code.py).
        • description (String): Semantische Beschreibung für das LLM.
    • Option B: Data Store-Tool
      • dataStoreTool (Objekt):
        • name (String): Der Toolname (entspricht in der Regel dem Verzeichnisnamen).
        • description (String): Beschreibung des Zwecks des Tools für den Agent.
        • engineSource (Objekt):
          • dataStoreSources (Liste von Objekten):
            • dataStore (Objekt):
              • name (String): Der vollständige Ressourcenname des Data Stores (z. B. projects/...) oder eine Umgebungsvariable (z. B. $env_var).
        • modalityConfigs (Liste von Objekten): Optional. Konfiguriert das Verhalten für TEXT oder AUDIO.
          • modalityType (Enum): TEXT oder AUDIO.
          • groundingConfig (Objekt):
            • groundingLevel (Float): z. B. 4.0.
    • executionType (Enum): z. B. SYNCHRONOUS.
  • python_function/python_code.py: Die Python-Codedatei (nur für Python-Funktionstools).

toolsets/

Dieses Verzeichnis enthält OpenAPI-basierte Toolsets.

Toolsetstruktur (toolsets/<toolset_name>/)

  • <toolset_name>.yaml: Konfiguration für das Toolset.
    • displayName (String): Name des Toolsets.
    • openApiToolset (Objekt):
      • openApiSchema (String): Pfad zur OpenAPI-Schemadatei relativ zum Stammverzeichnis (z. B. toolsets/<toolset_name>/open_api_toolset/open_api_schema.yaml).
      • apiAuthentication (Objekt): Authentifizierungskonfiguration (z. B. serviceAgentIdTokenAuthConfig).
  • open_api_toolset/open_api_schema.yaml: Die OpenAPI-Spezifikationsdatei.

guardrails/

In diesem Verzeichnis werden Sicherheitsfilter für Inhalte definiert.

Guardrail-Struktur (guardrails/<guardrail_name>/)

  • <guardrail_name>.yaml:
    • displayName (String): Name der Guardrail.
    • description (String): Zweck.
    • enabled (boolesch): Gibt an, ob sie aktiv ist.
    • contentFilter (Objekt):
      • bannedContentsInUserInput (Liste von Strings): Wörter und Wortgruppen, die blockiert werden sollen.
      • matchType (String): z. B. „WORD_BOUNDARY_STRING_MATCH“.
    • action (Objekt):
      • respondImmediately (Objekt):
        • responses (Liste von Objekten): Jedes Objekt enthält text (String).

examples/

Dieses Verzeichnis enthält die Definitionen für Beispiele für wenige Aufnahmen, die in der Agentenanwendung verwendet werden.

Beispielstruktur (examples/<example_name>/)

  • <example_name>.yaml: Konfiguration für das Beispiel.

evaluations/

Dieses Verzeichnis enthält Testdefinitionen.

Evaluierungsstruktur (evaluations/<evaluation_name>/)

  • <evaluation_name>.yaml: Definiert Testszenarien mit erwarteten Eingaben/Ausgaben.

evaluationDatasets/

Dieses Verzeichnis enthält Evaluierungs-Datasets.

Evaluierungs-Dataset-Struktur (evaluationDatasets/<evaluation_dataset_name>/)

  • <evaluation_dataset_name>.yaml: Konfiguration für das Evaluierungs-Dataset.