Method: projects.locations.apps.assistantSessions.streamChatAiAssistant

指定されたアシスタント セッションで AI アシスタントの Arc をストリーミング形式で実行します。

HTTP リクエスト

POST https://ces.googleapis.com/v1/{name=projects/*/locations/*/apps/*/assistantSessions/*}:streamChatAiAssistant

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

パスパラメータ

パラメータ
name

string

必須。アシスタントの実行に使用されるアシスタント セッション。形式: projects/{project}/locations/{location}/apps/{app}/assistantSessions/{assistantSession}

リクエストの本文

リクエストの本文には、次の構造のデータが含まれます。

JSON 表現 
{
  "message": string,
  "attachedGcsUris": [
    string
  ],
  "contextToken": string,
  "confirmationResponse": {
    object (AssistantConfirmationResponse)
  },
  "clientCapabilities": [
    enum (StreamChatAiAssistantRequest.ClientCapability)
  ],
  "operationCompletedEvent": {
    object (OperationCompletedEvent)
  },
  "resumeFromSequenceNumber": string,
  "attachOnly": boolean
}
フィールド
message

string

省略可。アシスタント エージェントに送信するメッセージ。confirmationResponse が設定されている場合（新しいメッセージを追加せずに保留中の確認に応答する場合）は、空にすることができます。2 つのうち少なくとも 1 つを指定する必要があります。
attachedGcsUris[]

string

省略可。このターン中にユーザーがアップロードしたファイルの Cloud Storage URI。例: 「gs://cxas-transient-uploads/uuid/prd.pdf」
contextToken

string

省略可。SessionService.GenerateOnboardingSuggestions から返される不透明なオンボーディング コンテキスト トークン。設定されていて、まだ新しい場合、サーバーは最初の会話ターンで再計算するのではなく、ゼロ状態用に計算されたオンボーディング スナップショットを再利用します。
confirmationResponse

object (AssistantConfirmationResponse)

省略可。保留中の AssistantConfirmationRequest に対するユーザーの回答。設定すると、サーバーは新しいプロンプト ターンを開始する代わりに（またはそれに加えて）、この回答で一時停止されたエージェントを再開します。
clientCapabilities[]

enum (StreamChatAiAssistantRequest.ClientCapability)

省略可。このクライアントがレンダリングできるレスポンス機能。サーバーは、機能（confirmationRequest など）を必要とするイベントを、その機能が宣言されている場合にのみ出力します。そのため、古いクライアントがイベントを受信して、何もせずに破棄することはありません。
operationCompletedEvent

object (OperationCompletedEvent)

省略可。クライアント管理の長時間実行オペレーションの完了を待機して一時停止したアシスタント セッションを再開します。
resumeFromSequenceNumber

string (int64 format)

省略可。処理中または完了したターンからイベントを再開して再生するためのオプションのカーソル。
attachOnly

boolean

省略可。新しいメッセージを送信せずに、既存の処理中のターンにアタッチするためのオプション フラグ。

レスポンスの本文

SessionService.StreamChatAiAssistant に対するレスポンス メッセージです。

成功した場合、レスポンスの本文には次の構造のデータが含まれます。

JSON 表現 
{
  "eventId": string,
  "eventTime": string,
  "uiEvent": {
    object (UiEvent)
  },
  "turnMetadata": {
    object (TurnMetadata)
  },
  "sequenceNumber": string,
  "turnInProgress": boolean,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "textChunk": string,
  "status": {
    object (Status)
  },
  "thoughtChunk": string,
  "toolCall": {
    object (ToolCall)
  },
  "toolResponse": {
    object (ToolResponse)
  },
  "artifactChunk": {
    object (ArtifactChunk)
  },
  "optionQuestionsChunk": {
    object (OptionQuestionsChunk)
  },
  "confirmationRequest": {
    object (AssistantConfirmationRequest)
  },
  "sessionCheckpoint": {
    object (SessionCheckpoint)
  },
  "resumeSnapshot": {
    object (TurnResumeSnapshot)
  },
  "handoff": {
    object (TurnHandoffEvent)
  },
  "turnCompleted": {
    object (TurnCompletedEvent)
  }
  // End of mutually exclusive fields.
}
フィールド
eventId

string

イベントの固有識別子。
eventTime

string (Timestamp format)

イベントが発生したタイムスタンプ。

RFC 3339 を使用します。生成された出力は常に Z 正規化され、小数点以下は 0、3、6、または 9 桁になります。「Z」以外のオフセットも使用できます。例: "2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z"、"2014-10-02T15:01:23+05:30"。
uiEvent

object (UiEvent)

省略可。UI イベントのペイロード。
turnMetadata

object (TurnMetadata)

省略可。ターンレベルのメタデータとインテントの分類。
sequenceNumber

string (int64 format)

省略可。このセッション ターンの単調増加するシーケンス番号。
turnInProgress

boolean

省略可。ターンがバックグラウンドでまだアクティブに実行されているかどうかを示します。
イベント ペイロード。相互に排他的なフィールドのリストは次のとおりです。レスポンスに設定されるフィールドは、最大 1 つです。
textChunk

string

テキスト トークン（Gemini の回答を単語ごとにストリーミングする場合）。
status

object (Status)

簡単なステータス更新。
thoughtChunk

string

思考テキスト チャンク（回答を生成する前のエージェントの推論）。
toolCall

object (ToolCall)

ツール呼び出し実行イベント。
toolResponse

object (ToolResponse)

ツール呼び出しレスポンス イベント。
artifactChunk

object (ArtifactChunk)

生成されたドキュメント アーティファクト イベント（ライブ プレビューの差分 + 最終的な Cloud Storage ポインタ）。
optionQuestionsChunk

object (OptionQuestionsChunk)

モデルターンから解析された構造化された明確化オプション。コンソールでは、これらは未加工のテキストではなく、選択可能なオプション リストとしてレンダリングされます。
confirmationRequest

object (AssistantConfirmationRequest)

エージェントが一時停止したブロック確認。エージェントは、後続のリクエストの confirmationResponse で回答が届くと再開します。リクエストで CONFIRMATION_CARDS 機能を宣言したクライアントにのみ送信されます。
sessionCheckpoint

object (SessionCheckpoint)

ユーザーの意図とローリング サマリーを含むセッション チェックポイント / 圧縮要約イベント。
resumeSnapshot

object (TurnResumeSnapshot)

処理中のターンの圧縮されたリプレイ。ライブイベントの前に、アタッチまたは再開の最初のイベントとして送信されます。クライアントは、このターンのローカルでレンダリングされた状態をスナップショットの内容に置き換えます。
handoff

object (TurnHandoffEvent)

resumeFromSequenceNumber を使用してサイレントに再接続するようクライアントに指示します。このストリームを処理するタスクは終了し、ターンは別の場所で続行されます。エラーではありません。このイベントの後、ストリームは正常に完了します。
turnCompleted

object (TurnCompletedEvent)

ターンが終了しました。元のストリームと、接続されたストリームまたは再開されたストリームで、すべてのターンの最後のイベントとして送信されます。これにより、クライアントはストリームの終了から推測するのではなく、明示的なシグナルでターンを終了できます。
相互に排他的なフィールドの終了。

認可スコープ

次の OAuth スコープのいずれかが必要です。

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

詳細については、Authentication Overview をご覧ください。

IAM 権限

name リソースに対する次の IAM 権限が必要です。

  • ces.assistantSessions.get

詳細については、IAM のドキュメントをご覧ください。

AssistantConfirmationResponse

AssistantConfirmationRequest に対するユーザーの回答。一時停止したエージェントを再開するために、次の SessionService.StreamChatAiAssistant 呼び出しで送信されます。

JSON 表現 
{
  "confirmationId": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "confirmed": boolean,
  "answerText": string
  // End of mutually exclusive fields.
}
フィールド
confirmationId

string

応答される AssistantConfirmationRequest.confirmation_id。
ユーザーの回答。相互に排他的なフィールドのリストは次のとおりです。レスポンスに設定されるフィールドは、最大 1 つです。
confirmed

boolean

バイナリ回答: true は一時停止されたアクションを承認し、false は拒否します。
answerText

string

選択したオプションの submitText、または自由形式のユーザー テキスト。一時停止されたアクションはキャンセルされ、テキストがエージェントに渡されて処理されます。
相互に排他的なフィールドの終了。

StreamChatAiAssistantRequest.ClientCapability

クライアントが宣言できるレスポンス機能。

列挙型
CLIENT_CAPABILITY_UNSPECIFIED 指定されていない機能。無視されます。
CONFIRMATION_CARDS クライアントは AssistantConfirmationRequest カードをレンダリングし、confirmationResponse を介して回答します。
CLIENT_MANAGED_LRO クライアントは、オペレーションをポーリングし、operationCompletedEvent を送信してターンを再開することで、長時間実行オペレーションを帯域外で管理します。宣言されていない場合、サーバーは LRO ポーリングを管理し、ターンをインラインで完了します。
PROJECT_SCOPE クライアントは、プロジェクト スコープのイベントをレンダリングします。typedPayload カード、ツール呼び出しとレスポンスの targetApp、確認リクエストの targets、ターンの完了の touchedApps。

OperationCompletedEvent

非同期の長時間実行オペレーション（LRO）の完了後にアシスタント セッションを再開するために、クライアントまたはバックグラウンド ワーカーから送信されるイベント。

JSON 表現 
{
  "operationName": string,
  "targetResourceName": string,
  "operationType": string,
  "status": string,
  "deduplicationToken": string,
  "error": {
    object (Status)
  },
  "metadata": {
    object
  }
}
フィールド
operationName

string

オペレーション リソース名（例: operations/{op}）。
targetResourceName

string

オペレーションの対象となる、またはオペレーションによって生成されるプライマリ リソース（評価実行 ID、アプリ ID、データセット ID など）。
operationType

string

オペレーション タイプまたはツール名（「run_evaluation」、「copy_app」、「export_app」など）。
status

string

オペレーション実行のステータス（「SUCCEEDED」、「FAILED」、「CANCELLED」など）。
deduplicationToken

string

同時実行のブラウザタブから重複したターンの実行を防ぐための、オプションの重複除去トークン（UUID など）。
error

object (Status)

オペレーションが失敗した場合の正規エラー ステータス（省略可）。
metadata

object (Struct format)

省略可能な構造化された結果メタデータ（pass_rate、total_examples、export_uri など）。

ArtifactChunk

アシスタントが生成しているドキュメント アーティファクト（マークダウン TDD など）のストリーミングされたフラグメント。ドキュメントの書き込み中にコンテンツ デルタがストリーミングされるため、クライアントはライブ プレビューをレンダリングできます。ファイルが永続化されると、FINALIZED チャンクが Cloud Storage URI を伝送します。

JSON 表現 
{
  "artifactId": string,
  "displayName": string,
  "mimeType": string,
  "contentDelta": string,
  "gcsUri": string,
  "state": enum (ArtifactChunk.State),
  "targetApp": string
}
フィールド
artifactId

string

アーティファクトの識別子。ストリーム内の 1 つのアーティファクトのすべてのチャンクで安定しています。
displayName

string

ユーザーに表示されるファイル名（例: 「hotel_booking_tdd.md」）。STARTED で設定（FINALIZED で繰り返し）。
mimeType

string

アーティファクト コンテンツの IANA メディアタイプ（例: text/markdown）。
contentDelta

string

増分アーティファクトのコンテンツ。DELTA チャンクに設定します。
gcsUri

string

アーティファクトが永続化された Cloud Storage オブジェクト。FINALIZED チャンクに設定します。
state

enum (ArtifactChunk.State)

このチャンクのライフサイクル位置。
targetApp

string

出力専用。このアーティファクトが生成されたアプリ（1 つのアプリ用に生成された場合）。形式: projects/{project}/locations/{location}/apps/{app}

ArtifactChunk.State

アーティファクトのストリーム内でのこのチャンクのライフサイクル位置。

列挙型
STATE_UNSPECIFIED 未使用のデフォルト。
STARTED アシスタントがアーティファクトの生成を開始しました。
DELTA コンテンツの増分。contentDelta が設定されています。
FINALIZED アーティファクトが永続化されました。gcsUri が設定されています。
FAILED 生成または永続化に失敗しました。アーティファクトは保存されませんでした。
CLOSED ドキュメントのストリーミングが完了しました。コンテンツは contentDelta チャンクを介して完全に配信されました。永続化は引き続き行われる可能性があります。アーティファクトが保存されると、gcsUri を含む FINALIZED チャンクが送信されます。

OptionQuestionsChunk

アシスタントがユーザーに選択を求める構造化された明確化オプション。モデルのターン外でサーバーサイドで変換されます（オプション ブロックは、ストリーミングされたテキストと永続化されたテキストから削除されます）。コンソールには、キーボードで操作可能なオプション リストが作成ツールの上のドックに表示されます。

JSON 表現 
{
  "questions": [
    {
      object (OptionQuestionsChunk.Question)
    }
  ]
}
フィールド
questions[]

object (OptionQuestionsChunk.Question)

このターンで質問された内容。複数のエントリがコンソールの「1 of N」ページャーを駆動します。

OptionQuestionsChunk.Question

1 つの質問とその選択肢。

JSON 表現 
{
  "question": string,
  "options": [
    {
      object (OptionQuestionsChunk.Option)
    }
  ]
}
フィールド
question

string

質問のヘッダー テキスト。
options[]

object (OptionQuestionsChunk.Option)

選択可能なオプション（表示順）。

OptionQuestionsChunk.Option

選択可能なオプションが 1 つ。

JSON 表現 
{
  "title": string,
  "details": string,
  "submitText": string
}
フィールド
title

string

短い書式なしテキストのオプション タイトル（マークダウンなし、番号なし）。
details

string

オプションのトレードオフの詳細がセカンダリ テキストとして表示されます。
submitText

string

オプションが選択されたときに送信するオプションのメッセージ テキスト。空の場合はデフォルトで title になります。

AssistantConfirmationRequest

エージェントのアクションを続行する前に、アシスタントが回答する必要があるブロック質問または確認。リクエスト元のエージェントは一時停止し、後で StreamChatAiAssistantRequest.confirmation_response で回答が届いた場合にのみ再開します。

JSON 表現 
{
  "confirmationId": string,
  "context": string,
  "positiveLabel": string,
  "negativeLabel": string,
  "questions": [
    {
      object (OptionQuestionsChunk.Question)
    }
  ],
  "tool": string,
  "agentName": string,
  "expireTime": string,
  "targets": [
    {
      object (AssistantConfirmationRequest.Target)
    }
  ]
}
フィールド
confirmationId

string

このリクエストをレスポンスに関連付ける識別子。クライアントには不透明。応答リクエストでそのままエコーする必要があります。
context

string

確認対象を説明するコンテキスト（エージェントが実行するアクション、回答が必要な質問など）。マークダウンではなく、書式なしテキストとしてレンダリングされます。
positiveLabel

string

2 択の確認の承認アクションのラベル（例: 「公開」）。questions が入力されている場合は設定されません。
negativeLabel

string

2 択の確認で拒否する操作のラベル（例: 「まだ」）。questions が入力されている場合は設定されません。
questions[]

object (OptionQuestionsChunk.Question)

確認の多肢選択形式。入力すると、カードに選択可能なオプション リストが表示され、選択したオプションの submitText（または自由形式のユーザー テキスト）が AssistantConfirmationResponse.answer_text として返されます。
tool

string

エージェントが一時停止したツール呼び出しの名前（例: 「update_app」）。カードのヘッダーに使用されます。純粋な質問の場合は未設定。
agentName

string

確認を生成したエージェントの表示ラベル（例: "Contract Architect"）。カードヘッダーに使用されます。
expireTime

string (Timestamp format)

この確認に回答できなくなる時間。期限切れのカードは無効としてレンダリングされ、サーバーは次のターンで確認を拒否するため、一時停止されたエージェントは無期限に待機することはありません。

RFC 3339 を使用します。生成された出力は常に Z 正規化され、小数点以下は 0、3、6、または 9 桁になります。「Z」以外のオフセットも使用できます。例: "2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z"、"2014-10-02T15:01:23+05:30"。
targets[]

object (AssistantConfirmationRequest.Target)

確認されたアクションによって変更されるすべてのもの。これにより、コンソールで「2 個のアプリを更新」とアプリごとに 1 つのバッジをレンダリングできます。以前の単一ターゲット カードの場合は空です。

AssistantConfirmationRequest.Target

確認済みの操作によって変更される 1 つのリソース。

JSON 表現 
{
  "resource": string,
  "displayName": string,
  "action": string,
  "targetApp": string
}
フィールド
resource

string

変更されるリソース（完全なリソース名）。
displayName

string

カードのリソースまたはアプリの表示名。
action

string

アクション（CREATE、UPDATE、DELETE、COPY、LINK など）。
targetApp

string

リソースが属するアプリ。アプリの作成など、ロケーション スコープのアクションの場合は空です。形式: projects/{project}/locations/{location}/apps/{app}

SessionCheckpoint

セッション タイトルと UI の推定ユーザー インテントを含むセッション チェックポイント。

JSON 表現 
{
  "userIntent": string
}
フィールド
userIntent

string

セッションの推定ユーザー目標またはトピック（例: 「e コマース サポート エージェントの構築」）。

TurnResumeSnapshot

処理中のターンの圧縮されたリプレイ。これまでにターンの表示可能な出力をレンダリングするために必要なすべての情報と、ライブイベントが継続する位置が含まれます。

JSON 表現 
{
  "turnId": string,
  "resolvedSequenceNumber": string,
  "events": [
    {
      object (StreamChatAiAssistantResponse)
    }
  ],
  "orphanDeadlineTime": string
}
フィールド
turnId

string

アタッチされるターンを識別します。
resolvedSequenceNumber

string (int64 format)

このスナップショットが表す位置。ライブイベントは、これよりも厳密に大きい sequenceNumber で続きます。クライアントがリクエストした resumeFromSequenceNumber よりも小さい場合、フラッシュされた進行状況はクライアントがすでにレンダリングした内容よりも遅れています。クライアントは、スナップショットを適用する前に、この位置を超えるこのターンのレンダリングされたコンテンツを破棄する必要があります。
events[]

object (StreamChatAiAssistantResponse)

ライブ ストリーミングと同じイベント形状を使用して、ターンの表示可能な出力をレンダリング順に再構築する圧縮イベント。
orphanDeadlineTime

string (Timestamp format)

クライアントが接続されていない場合に、ターンが終了するタイミング。

RFC 3339 を使用します。生成された出力は常に Z 正規化され、小数点以下は 0、3、6、または 9 桁になります。「Z」以外のオフセットも使用できます。例: "2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z"、"2014-10-02T15:01:23+05:30"。

TurnHandoffEvent

このタスクがターンの途中でストリームの提供を停止する前に出力されます（サーバーの再起動など）。ターンの状態は永続化されます。resumeFromSequenceNumber を含む再接続により、別のタスクで継続されます。

JSON 表現 
{
  "turnId": string,
  "reason": enum (TurnHandoffEvent.Reason)
}
フィールド
turnId

string

再開するターンを識別します。
reason

enum (TurnHandoffEvent.Reason)

ストリームが引き継がれている理由。

TurnHandoffEvent.Reason

ストリームが引き継がれる理由。

列挙型
REASON_UNSPECIFIED 指定なし。
SERVER_RESTART サービング タスクがシャットダウンしている（リリース プッシュまたは再スケジュール）。

TurnCompletedEvent

ターンのターミナル イベント（StreamChatAiAssistantResponse.turn_completed を参照）。

JSON 表現 
{
  "turnId": string,
  "reason": enum (TurnCompletedEvent.Reason),
  "finalSequenceNumber": string,
  "touchedApps": [
    string
  ]
}
フィールド
turnId

string

終了したターンの識別子。TurnResumeSnapshot.turn_id および ActiveTurnInfo.turn_id と一致します。
reason

enum (TurnCompletedEvent.Reason)

ターンが終了した理由。
finalSequenceNumber

string (int64 format)

ターンで生成された最後のイベントのシーケンス番号。カーソルが低いクライアントはコンテンツを見逃しているため、セッションを再読み込みしてコンテンツを表示する必要があります。
touchedApps[]

string

このターンで対象となった、または変更されたアプリ。コンソールは、これらのアプリのストアのみを更新できます。プロジェクト スコープのセッションのみ。形式: projects/{project}/locations/{location}/apps/{app}

TurnCompletedEvent.Reason

ターンが終了した理由。これにより、遅れて接続したクライアントは、空のストリームから推測するのではなく、結果を言葉で表現できます。

列挙型
REASON_UNSPECIFIED 指定なし。
COMPLETED ターンが完了しました。セッションは commit された出力を保持します。
ABANDONED ターンを駆動するタスクがなくなったため、コミットされた部分にシールされ、続行できません。
RESUME_UNAVAILABLE このサーバーはセッションのアタッチまたは再開を処理しないため、何もテールされませんでした。クライアントは代わりにセッションを再読み込みする必要があります。

UiEvent

UI イベント ペイロードを表します。

JSON 表現 
{
  "mimeType": string,
  "jsonPayload": string
}
フィールド
mimeType

string

UI イベント ペイロードの形式を示すメディアタイプ（MIME タイプ）（例: 「application/json+a2ui」）。
jsonPayload

string

A2UI サーフェスを表す JSON ペイロード。

TurnMetadata

ターンレベルのメタデータとインテントの分類。

JSON 表現 
{
  "contractRelated": boolean,
  "contractFinalized": boolean,
  "contractStreamingPhase": enum (TurnMetadata.ContractStreamingPhase),
  "contractDraftComplete": boolean
}
フィールド
contractFinalized

boolean

契約の下書きが公開された（リビジョンが有効化された）ターンの最終アーティファクト イベントに設定されます。このドラフトの明確化フローのターミナル: contractProgress は信頼できるものであり、完了しています。
contractStreamingPhase

enum (TurnMetadata.ContractStreamingPhase)

契約アーティファクト フェンスのストリーミング中に生成される処理中の進捗状況の見積もりと、revision-turn-start イベントにのみ設定されます。信頼できるペイロードでは設定されていません。
contractDraftComplete

boolean

すべてのプレースホルダが解決された（contractProgress が 100%）契約ドラフトのターミナル イベントに設定されます。ドラフトが公開されたかどうかは関係ありません。クライアントは、契約の進行状況の表示を完了して閉じます。公開は contractFinalized によって別途報告されます。

TurnMetadata.ContractStreamingPhase

契約の進行状況ペイロードのストリーミング フェーズ。

列挙型
CONTRACT_STREAMING_PHASE_UNSPECIFIED ペイロードは信頼できるものです（完全な契約ドキュメント、永続化されたスナップショット、またはドラフト前の状態から計算されます）。クライアントは、以前に受信した進行状況をこの値に置き換える必要があります。
DRAFTING 最初の契約ドラフトがストリーミングされています。contractProgress は処理中の推定値です。1 つのアーティファクト フェンス内で減少しない、信頼できる範囲の下限、柱の内訳は totalItemCount == 0 で、推定された柱の状態を示します。
REVISING 既存の契約の改訂がストリーミングされている（アノテーションの送信後など）。DRAFTING と同じ見積もりセマンティクス。