匯出格式參考資料

本文將說明代理程式應用程式匯出和匯入檔案的目錄結構和檔案組織。

格式為 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：環境專屬變數的鍵/值組合。
  • global_instruction.txt： 包含主要提示/指令的文字檔案。

agents/

這個目錄包含應用程式中所有代理程式的定義。

服務專員結構 (agents/<agent_name>/)

  • <agent_name>.yaml：特定代理程式的設定檔。
    • displayName (字串)： 代理程式的名稱。
    • modelSettings (物件)： 包含 model (字串)。
    • instruction (字串)： 相對於根目錄的指令檔路徑 (例如 agents/<agent_name>/instruction.txt)。
    • tools (字串清單)： 這個代理程式可用的本機工具顯示名稱。
    • toolsets (物件清單)：這個代理可用的 OpenAPI 工具組。每個物件都包含：
      • toolset (字串)： 工具集名稱。
      • toolIds (字串清單)： 要從該工具組公開的特定作業 ID。
    • childAgents (字串清單)： 這個代理程式可轉移給其他代理程式的顯示名稱。這種關係是單向的 (父項到子項)；除非明確要進行循環轉換，否則子項代理程式不應將父項列為子項。代理最多只能有一個上層代理 (例外：共用的公用程式代理，例如 Escalation 或 Satisfaction)。根代理程式不得列為任何其他代理程式的子項。
    • *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： 評估資料集的設定。