Method: projects.locations.apps.sessions.runSession

在工作階段中，與 CES 代理啟動單一回合的互動。

HTTP 要求

POST https://ces.googleapis.com/v1beta/{config.session=projects/*/locations/*/apps/*/sessions/*}:runSession

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
config.session

string

這是必要旗標，工作階段的專屬 ID。格式：projects/{project}/locations/{location}/apps/{app}/sessions/{session}

要求主體

要求主體包含下列結構的資料：

JSON 表示法 
{
  "config": {
    "session": string,
    "inputAudioConfig": {
      "audioEncoding": enum (AudioEncoding),
      "sampleRateHertz": integer,
      "noiseSuppressionLevel": string
    },
    "outputAudioConfig": {
      "audioEncoding": enum (AudioEncoding),
      "sampleRateHertz": integer
    },
    "historicalContexts": [
      {
        "role": string,
        "chunks": [
          {
            object (Chunk)
          }
        ],
        "eventTime": string
      }
    ],
    "entryAgent": string,
    "deployment": string,
    "timeZone": string,
    "useToolFakes": boolean,
    "remoteDialogflowQueryParameters": {
      "webhookHeaders": {
        string: string,
        ...
      },
      "payload": {
        object
      },
      "endUserMetadata": {
        object
      }
    }
  },
  "inputs": [
    {
      object (SessionInput)
    }
  ]
}
欄位
config.inputAudioConfig

object (InputAudioConfig)

選用。用於處理輸入音訊的設定。
config.outputAudioConfig

object (OutputAudioConfig)

選用。用於生成輸出音訊的設定。
config.historicalContexts[]

object (Message)

選用。工作階段的歷史脈絡，包括使用者輸入內容、代理程式回覆和其他訊息。通常 CES 代理程式會自動管理工作階段，因此用戶端不需要明確填入這個欄位。不過，用戶端可以選擇覆寫歷來的情境，強制工作階段從特定狀態開始。
config.entryAgent

string

選用。負責處理工作階段的進入代理程式。如未指定，工作階段會由應用程式的 root agent 處理。格式：projects/{project}/locations/{location}/apps/{app}/agents/{agent}
config.deployment

string

選用。工作階段使用的應用程式部署作業。格式：projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
config.timeZone

string

選用。使用者的時區。如果提供時區，代理程式會將日期和時間相關變數轉換為該時區。否則，代理程式會使用 App.time_zone_settings 中指定的時區。

格式為 IANA 時區資料庫時區，例如「America/Los_Angeles」。
config.useToolFakes

boolean

選用。是否要為工作階段使用工具模擬。如果設定這個欄位，代理程式會嘗試使用工具模擬，而非呼叫實際工具。
config.remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

選用。QueryParameters，以便在工作階段控制項轉移至遠端代理程式時，傳送至遠端 Dialogflow 代理程式。
inputs[]

object (SessionInput)

這是必要旗標，工作階段的輸入內容。

回應主體

SessionService.RunSession 的回應訊息。

如果成功，回應主體會含有以下結構的資料：

JSON 表示法 
{
  "outputs": [
    {
      object (SessionOutput)
    }
  ]
}
欄位
outputs[]

object (SessionOutput)

工作階段的輸出內容。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

詳情請參閱Authentication Overview。

IAM 權限

需要 session 資源的下列 IAM 權限：

  • ces.sessions.runSession

詳情請參閱 IAM 說明文件。

SessionConfig

工作階段的設定。

JSON 表示法 
{
  "session": string,
  "inputAudioConfig": {
    object (InputAudioConfig)
  },
  "outputAudioConfig": {
    object (OutputAudioConfig)
  },
  "historicalContexts": [
    {
      object (Message)
    }
  ],
  "entryAgent": string,
  "deployment": string,
  "timeZone": string,
  "useToolFakes": boolean,
  "remoteDialogflowQueryParameters": {
    object (SessionConfig.RemoteDialogflowQueryParameters)
  }
}
欄位
session

string

這是必要旗標，工作階段的專屬 ID。格式：projects/{project}/locations/{location}/apps/{app}/sessions/{session}
inputAudioConfig

object (InputAudioConfig)

選用。用於處理輸入音訊的設定。
outputAudioConfig

object (OutputAudioConfig)

選用。用於生成輸出音訊的設定。
historicalContexts[]

object (Message)

選用。工作階段的歷史脈絡，包括使用者輸入內容、代理程式回覆和其他訊息。通常 CES 代理程式會自動管理工作階段，因此用戶端不需要明確填入這個欄位。不過，用戶端可以選擇覆寫歷來的情境，強制工作階段從特定狀態開始。
entryAgent

string

選用。負責處理工作階段的進入代理程式。如未指定，工作階段會由應用程式的 root agent 處理。格式：projects/{project}/locations/{location}/apps/{app}/agents/{agent}
deployment

string

選用。工作階段使用的應用程式部署作業。格式：projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
timeZone

string

選用。使用者的時區。如果提供時區，代理程式會將日期和時間相關變數轉換為該時區。否則，代理程式會使用 App.time_zone_settings 中指定的時區。

格式為 IANA 時區資料庫時區，例如「America/Los_Angeles」。
useToolFakes

boolean

選用。是否要為工作階段使用工具模擬。如果設定這個欄位，代理程式會嘗試使用工具模擬，而非呼叫實際工具。
remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

選用。QueryParameters，以便在工作階段控制項轉移至遠端代理程式時，傳送至遠端 Dialogflow 代理程式。

SessionConfig.RemoteDialogflowQueryParameters

QueryParameters，以便在工作階段控制項轉移至遠端代理程式時，傳送至遠端 Dialogflow 代理程式。

JSON 表示法 
{
  "webhookHeaders": {
    string: string,
    ...
  },
  "payload": {
    object
  },
  "endUserMetadata": {
    object
  }
}
欄位
webhookHeaders

map (key: string, value: string)

選用。要以 QueryParameters 中的 webhookHeaders 傳送的 HTTP 標頭。

包含 "key": value 組合清單的物件，範例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
payload

object (Struct format)

選用。要在 QueryParameters 中傳送的酬載。
endUserMetadata

object (Struct format)

選用。要透過 QueryParameters 傳送的消費者中繼資料。

SessionOutput

工作階段的輸出內容。

JSON 表示法 
{
  "turnIndex": integer,
  "turnCompleted": boolean,
  "diagnosticInfo": {
    object (SessionOutput.DiagnosticInfo)
  },

  // Union field output_type can be only one of the following:
  "text": string,
  "audio": string,
  "toolCalls": {
    object (ToolCalls)
  },
  "citations": {
    object (Citations)
  },
  "googleSearchSuggestions": {
    object (GoogleSearchSuggestions)
  },
  "endSession": {
    object (EndSession)
  },
  "payload": {
    object
  }
  // End of list of possible types for union field output_type.
}
欄位
turnIndex

integer

指出這個輸出內容所屬的對話輪次順序，從 1 開始。
turnCompleted

boolean

如果是 true，表示 CES 代理程式已偵測到目前對話回合結束，因此不會再提供這個回合的輸出內容。
diagnosticInfo

object (SessionOutput.DiagnosticInfo)

選用。診斷資訊包含處理輸入內容時的執行詳細資料。只會在每個回合的最後一個 SessionOutput (含 turnCompleted=true) 中填入。
聯集欄位 output_type。輸出類型。output_type 只能是下列其中一個設定：
text

string

CES 服務專員提供的輸出文字。
audio

string (bytes format)

輸出 CES 服務專員的語音。

Base64 編碼字串。
toolCalls

object (ToolCalls)

要求用戶端執行工具。
citations

object (Citations)

引文，提供服務專員生成文字的來源資訊。
googleSearchSuggestions

object (GoogleSearchSuggestions)

呼叫 GoogleSearchTool 後，Google 搜尋傳回的建議。
endSession

object (EndSession)

表示工作階段已結束。
payload

object (Struct format)

自訂酬載，內含 CES 代理的結構化輸出內容。

ToolCalls

要求用戶端執行工具並傳回執行結果，然後再繼續工作階段。

JSON 表示法 
{
  "toolCalls": [
    {
      object (ToolCall)
    }
  ]
}
欄位
toolCalls[]

object (ToolCall)

選用。要執行的工具呼叫清單。

參考資料

與服務專員回覆相關的引用內容。

JSON 表示法 
{
  "citedChunks": [
    {
      object (Citations.CitedChunk)
    }
  ]
}
欄位
citedChunks[]

object (Citations.CitedChunk)

列出引用的資訊。

Citations.CitedChunk

引用的資訊。

JSON 表示法 
{
  "uri": string,
  "title": string,
  "text": string
}
欄位
uri

string

用於引用的 URI。
title

string

所引用文件的標題。
text

string

用於引用的文字。

GoogleSearchSuggestions

Google Search Tool提供的搜尋建議。

JSON 表示法 
{
  "htmls": [
    string
  ],
  "webSearchQueries": [
    {
      object (WebSearchQuery)
    }
  ]
}
欄位
htmls[]

string

符合規定的搜尋建議 HTML 和 CSS 樣式。系統會根據裝置設定自動調整提供的 HTML 和 CSS，並以 @media(prefers-color-scheme) 指示的淺色或深色模式顯示。
webSearchQueries[]

object (WebSearchQuery)

用於執行 Google 搜尋的查詢清單，以及構成搜尋建議的搜尋結果 URI。

WebSearchQuery

代表單一網路搜尋查詢及其相關聯的搜尋 URI。

JSON 表示法 
{
  "query": string,
  "uri": string
}
欄位
query

string

搜尋查詢文字。
uri

string

查詢的 Google 搜尋結果網頁 URI。

EndSession

表示工作階段已終止，可能是因為順利完成 (例如使用者說「再見！」) 或轉接給服務專員。

工作階段終止後，服務專員不會處理任何進一步的輸入內容，且用戶端應在收到服務專員的所有剩餘回覆後，半關閉並中斷連線。

JSON 表示法 
{
  "metadata": {
    object
  }
}
欄位
metadata

object (Struct format)

選用。提供工作階段結束信號的額外資訊，例如工作階段結束原因。

SessionOutput.DiagnosticInfo

內含處理期間的執行詳細資料。

JSON 表示法 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "rootSpan": {
    object (Span)
  }
}
欄位
messages[]

object (Message)

處理期間發生的訊息清單。
rootSpan

object (Span)

整個要求處理作業的追蹤記錄，以根時距表示。這個範圍可以包含特定作業的巢狀子範圍。