Method: projects.locations.apps.sessions.runSession

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

HTTP リクエスト

POST https://ces.googleapis.com/v1beta/{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,
    "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)

省略可。セッション制御がリモート エージェントに転送されたときにリモート 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,
  "useToolFakes": boolean,
  "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"）です。
useToolFakes

boolean

省略可。セッションでツール フェイクを使用するかどうか。このフィールドが設定されている場合、エージェントは実際のツールを呼び出す代わりに、ツール フェイクを使用しようとします。
remoteDialogflowQueryParameters

object (SessionConfig.RemoteDialogflowQueryParameters)

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

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 で送信されるエンドユーザーのメタデータ。

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)

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