エクスポート形式のリファレンス

このドキュメントでは、エージェント アプリケーションのエクスポート ファイルとインポート ファイルのディレクトリ構造とファイル構成について説明します。

形式は ZIP ファイルです。抽出すると、エージェント アプリケーション名に対応するルート ディレクトリが含まれます。

このドキュメントで説明するパスはすべて、ルート ディレクトリからの相対パスです。 他のオブジェクト（エージェント、ツールなど）への参照はすべて、displayName 値を使用する必要があります。

次のツール名は予約されています。

  • end_session
  • transfer_to_agent
  • customize_response

インポートとエクスポートを行う場合、個々のファイルには JSON または YAML を使用できます。 このドキュメントで説明するファイルでは YAML を使用していますが、JSON メンバーも同様です。

ルート ディレクトリ

ルート ディレクトリには、アプリケーションのメイン構成ファイルが含まれています。

  • app.yaml: エージェント アプリケーションの中央構成ファイル。次のものを定義します。
    • displayName （文字列）: 人間が読める形式のアプリケーション名。
    • rootAgent （文字列）: 会話を開始するエージェントの表示名 。 ファイル名やディレクトリ名は使用しないでください。
    • audioProcessingConfig （オブジェクト）: テキスト読み上げと音声テキスト変換の設定。
      • synthesizeSpeechConfigs （マップ）: キーはロケールコード（en-US など）、値は voice（文字列）を含むオブジェクト。
      • inactivityTimeout （文字列）: 時間の文字列（「2s」など）。
      • ambientSoundConfig （オブジェクト）: バックグラウンド ノイズを構成します。volumeGainDb（浮動小数点）と prebuiltAmbientSound（文字列）が含まれます。
    • loggingSettings （オブジェクト）: ログと記録の構成。
      • redactionConfig （オブジェクト）: 機密情報を編集するための構成。
      • audioRecordingConfig （オブジェクト）: gcsBucket（文字列）が含まれます。
      • bigqueryExportSettings （オブジェクト）: enabled（ブール値）、project（文字列）、dataset（文字列）が含まれます。
      • cloudLoggingSettings （オブジェクト）: enableCloudLogging（ブール値）が含まれます。
    • guardrails （文字列のリスト）: グローバルに適用されるガードレール名のリスト。
    • variableDeclarations （オブジェクトのリスト）: グローバル変数のスキーマ定義。各オブジェクトには次のものが含まれます。
      • name （文字列）: 変数名。
      • description （文字列）: 変数の目的の説明。
      • schema （オブジェクト）: 型定義（{ type: STRING } やネストされたプロパティなど）。
      • default （任意）: 変数のデフォルト値。
    • globalInstruction （文字列）: グローバル システム命令ファイルへのパス。
    • languageSettings （オブジェクト）:
      • defaultLanguageCode （文字列）: 「en-US」など。
      • supportedLanguageCodes（文字列のリスト）: 例: ["fr", "es"]。
      • enableMultilingualSupport（ブール値）。
  • environment.json: 環境固有の変数の Key-Value ペア。
  • global_instruction.txt: プライマリ プロンプト/命令を含むテキスト ファイル。

agents/

このディレクトリには、アプリケーション内のすべてのエージェントの定義が含まれています。

エージェントの構造（agents/<agent_name>/）

  • <agent_name>.yaml: The configuration file for the specific agent.
    • displayName （文字列）: エージェントの名前。
    • modelSettings（オブジェクト）: model（文字列）が含まれます。
    • instruction（文字列）: ルートからの相対的な命令ファイルへのパス （例: agents/<agent_name>/instruction.txt）。
    • tools （文字列のリスト）: このエージェントで使用できるローカル ツールの表示名。
    • toolsets （オブジェクトのリスト）: このエージェントで使用できる OpenAPI ツールセット。各オブジェクトには次のものが含まれます。
      • toolset （文字列）: ツールセットの名前。
      • toolIds （文字列のリスト）: そのツールセットから公開する特定のオペレーション ID。
    • childAgents （文字列のリスト）: このエージェントが移行できる他のエージェントの表示名。この関係は一方向（親から子）です。循環遷移が明示的に意図されていない限り、子エージェントは親を子としてリストに含めないでください。エージェントは複数の親を持つことはできません（例外: エスカレーションや満足度などの共有ユーティリティ エージェント）。 ルート エージェントを他のエージェントの子としてリストに含めることはできません。
    • *Callbacks （オブジェクトのリスト）: beforeModelCallbacks、afterModelCallbacks などに使用されます。 各オブジェクトには次のものが含まれます。
      • pythonCode（文字列）: コールバック スクリプトへのパス。
      • disabled（ブール値）: コールバックがアクティブかどうか。
      • description（文字列）: コールバックのロジックの説明。
  • instruction.txt: このエージェントの特定のシステム プロンプト。 ツールへの参照には {@TOOL: <tool_display_name>} 構文を使用する必要があります。 他のエージェントへの参照には {@AGENT: <agent_display_name>} を使用する必要があります。 変数には {variable_name} （{firstname} など）を使用してアクセスする必要があります。
  • before_model_callbacks/など: コールバック スクリプトのディレクトリ。

tools/

このディレクトリには「ローカル」ツールが含まれています。これは Python 関数またはデータストア リトリーバーのいずれかです。

ツールの構造（tools/<tool_name>/）

  • <tool_name>.yaml: ツールの構成。pythonFunction または dataStoreTool のいずれか を使用します。両方は使用しないでください。
    • displayName （文字列）: ツールの名前。
    • オプション A: Python 関数ツール
      • pythonFunction （オブジェクト）:
        • name （文字列）: 関数名。
        • pythonCode（文字列）: ルートからの相対的な Python 実装へのパス （例: tools/<tool_name>/python_function/python_code.py）。
        • description （文字列）: LLM のセマンティックな説明。
    • オプション B: データストア ツール
      • dataStoreTool （オブジェクト）:
        • name （文字列）: ツール名（通常はディレクトリ名と一致します）。
        • description （文字列）: エージェントのツールの目的の説明。
        • engineSource （オブジェクト）:
          • dataStoreSources （オブジェクトのリスト）:
            • dataStore （オブジェクト）:
              • name （文字列）: データストアのリソースの完全な名前（projects/... など）または環境変数（$env_var など）。
        • modalityConfigs （オブジェクトのリスト）: 省略可。TEXT または AUDIO の動作を構成します。
          • modalityType （列挙型）: TEXT または AUDIO。
          • groundingConfig （オブジェクト）:
            • groundingLevel （浮動小数点）: 4.0 など。
    • executionType （列挙型）: SYNCHRONOUS など。
  • python_function/python_code.py: Python コード ファイル（Python 関数ツールの場合のみ）。

toolsets/

このディレクトリには、OpenAPI ベースのツールセットが含まれています。

ツールセットの構造（toolsets/<toolset_name>/）

  • <toolset_name>.yaml: ツールセットの構成。
    • displayName （文字列）: ツールセットの名前。
    • openApiToolset （オブジェクト）:
      • openApiSchema（文字列）: ルートからの相対的な OpenAPI スキーマ ファイルへのパス（例: toolsets/<toolset_name>/open_api_toolset/open_api_schema.yaml）。
      • apiAuthentication （オブジェクト）: 認証構成（serviceAgentIdTokenAuthConfig など）。
  • open_api_toolset/open_api_schema.yaml: OpenAPI 仕様ファイル。

guardrails/

このディレクトリでは、コンテンツ セーフティ フィルタを定義します。

ガードレールの構造（guardrails/<guardrail_name>/）

  • <guardrail_name>.yaml:
    • displayName （文字列）: ガードレールの名前。
    • description （文字列）: 目的。
    • enabled （ブール値）: アクティブかどうか。
    • contentFilter （オブジェクト）:
      • bannedContentsInUserInput （文字列のリスト）: ブロックする単語やフレーズ。
      • matchType （文字列）: 「WORD_BOUNDARY_STRING_MATCH」など。
    • action （オブジェクト）:
      • respondImmediately （オブジェクト）:
        • responses （オブジェクトのリスト）: 各オブジェクトには text（文字列）が含まれます。

examples/

このディレクトリには、エージェント アプリケーションで使用されるフューショットの例の定義が含まれています。

例の構造（examples/<example_name>/）

  • <example_name>.yaml: 例の構成。

evaluations/

このディレクトリには、テスト定義が含まれています。

評価の構造（evaluations/<evaluation_name>/）

  • <evaluation_name>.yaml: 予想される入力/出力でテスト シナリオを定義します。

evaluationDatasets/

このディレクトリには、評価データセットが含まれています。

評価データセットの構造（evaluationDatasets/<evaluation_dataset_name>/）

  • <evaluation_dataset_name>.yaml: 評価データセットの構成。