Method: projects.locations.apps.sessions.runSession

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

HTTP 要求

POST https://ces.googleapis.com/v1/{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,
    "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.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,
  "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」。
remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

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

InputAudioConfig

InputAudioConfig 會設定 CES 代理程式解讀傳入音訊資料的方式。

JSON 表示法 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer,
  "noiseSuppressionLevel": string
}
欄位
audioEncoding

enum (AudioEncoding)

這是必要旗標，輸入音訊資料的編碼。
sampleRateHertz

integer

這是必要旗標，輸入音訊資料的取樣率 (單位為赫茲)。
noiseSuppressionLevel

string

選用。是否要對輸入音訊啟用噪音抑制功能。可用的值為「low」、「moderate」、「high」、「very_high」。

AudioEncoding

AudioEncoding 會指定音訊資料的編碼格式。

列舉
AUDIO_ENCODING_UNSPECIFIED 未指定音訊編碼。
LINEAR16 16 位元線性 PCM 音訊編碼。
MULAW 使用 G.711 PCMU/mu-law 來壓縮 14 位元音訊樣本，並在傳輸後將其擴展的 8 位元樣本。
ALAW 使用 G.711 PCMU/A-law 壓縮 14 位元音訊樣本的 8 位元樣本。

OutputAudioConfig

OutputAudioConfig 會設定 CES 代理程式合成外送音訊回應的方式。

JSON 表示法 
{
  "audioEncoding": enum (AudioEncoding),
  "sampleRateHertz": integer
}
欄位
audioEncoding

enum (AudioEncoding)

這是必要旗標，輸出音訊資料的編碼。
sampleRateHertz

integer

這是必要旗標，輸出音訊資料的取樣率 (單位為赫茲)。

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 傳送的消費者中繼資料。

SessionInput

工作階段的輸入內容。

JSON 表示法 
{
  "willContinue": boolean,

  // Union field input_type can be only one of the following:
  "text": string,
  "dtmf": string,
  "audio": string,
  "toolResponses": {
    object (ToolResponses)
  },
  "image": {
    object (Image)
  },
  "blob": {
    object (Blob)
  },
  "variables": {
    object
  },
  "event": {
    object (Event)
  }
  // End of list of possible types for union field input_type.
}
欄位
willContinue

boolean

選用。這個旗標用於指出目前訊息是否為雙向串流工作階段中較大輸入內容的片段。

設為 true 時，代理程式會延後處理作業，直到收到後續訊息 (其中 willContinue 為 false)，或系統在音訊輸入中偵測到端點為止。

注意：音訊和 DTMF 輸入內容一律會根據終止信號自動處理，因此不適用於這個欄位。
聯集欄位 input_type。輸入內容的類型。input_type 只能是下列其中一個設定：
text

string

選用。來自使用者的文字資料。
dtmf

string

選用。來自使用者的 DTMF 數字。
audio

string (bytes format)

選用。終端使用者的音訊資料。

Base64 編碼字串。
toolResponses

object (ToolResponses)

選用。用戶端工具呼叫的執行結果。
image

object (Image)

選用。來自使用者的圖片資料。
blob

object (Blob)

選用。來自使用者的 Blob 資料。
variables

object (Struct format)

選用。工作階段的內容變數，以名稱做為鍵。CES 代理程式只會使用在應用程式中宣告的變數。

無法辨識的變數仍會以額外工作階段參數的形式傳送至 [Dialogflow 代理程式][Agent.RemoteDialogflowAgent]。
event

object (Event)

選用。活動輸入。

ToolResponses

用戶端要求工具呼叫的執行結果。

JSON 表示法 
{
  "toolResponses": [
    {
      object (ToolResponse)
    }
  ]
}
欄位
toolResponses[]

object (ToolResponse)

選用。工具執行結果清單。

事件

活動輸入。

JSON 表示法 
{
  "event": string
}
欄位
event

string

這是必要旗標，活動名稱。

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)

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