Method: projects.locations.apps.sessions.runSession

セッション内で CES エージェントとの 1 回のターン インタラクションを開始します。

HTTP リクエスト

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

この URL では gRPC Transcoding 構文を使用します。

パスパラメータ

パラメータ
config.session

string

必須。セッションの固有識別子。形式: 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)

省略可。セッション制御がリモート エージェントに転送されたときにリモート Dialogflow エージェントに送信する QueryParameters。
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

必須。セッションの固有識別子。形式: 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)

省略可。セッション制御がリモート エージェントに転送されたときにリモート Dialogflow エージェントに送信する QueryParameters。

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

セッション制御がリモート エージェントに転送されたときにリモート Dialogflow エージェントに送信する QueryParameters。

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

1 つのウェブ検索クエリとそれに関連付けられた検索 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)

リクエスト処理全体のトレース。ルートスパンとして表されます。このスパンには、特定のオペレーションのネストされた子スパンを含めることができます。