Method: projects.locations.apps.assistantSessions.streamChatAiAssistant

以串流方式,為指定助理工作階段執行 AI 助理 Arc。

HTTP 要求

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

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

路徑參數

參數
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 (回覆待確認訊息,但不新增訊息),這個欄位可以留空。不過,這兩個欄位至少要提供一個。

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

事件的專屬 ID。

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

選用。指出轉彎是否仍在背景執行。

事件酬載。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位:
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。

使用者的答案。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位:
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

助理正在生成的串流文件構件片段 (例如 Markdown TDD)。系統會在寫入文件時串流內容差異,讓用戶端顯示即時預覽畫面;檔案保存後,FINALIZED 區塊會攜帶 Cloud Storage URI。

JSON 表示法
{
  "artifactId": string,
  "displayName": string,
  "mimeType": string,
  "contentDelta": string,
  "gcsUri": string,
  "state": enum (ArtifactChunk.State),
  "targetApp": string
}
欄位
artifactId

string

構件的 ID,在串流中一個構件的所有區塊中皆相同。

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

僅供輸出。如果這個構件是為某個應用程式產生,則會顯示該應用程式。格式:projects/{project}/locations/{location}/apps/{app}

ArtifactChunk.State

這個區塊在構件串流中的生命週期位置。

列舉
STATE_UNSPECIFIED 未使用的預設值。
STARTED 助理已開始生成構件。
DELTA 內容增量;已設定 contentDelta。
FINALIZED 構件已保存,gcsUri 已設定。
FAILED 生成或保存失敗,未儲存構件。
CLOSED 文件串流完成:內容已透過 contentDelta 區塊完整傳送。系統仍可能執行永久保存作業;如果構件已儲存,系統會傳送含有 gcsUri 的 FINALIZED 區塊。

OptionQuestionsChunk

Google 助理要求使用者選擇的結構化釐清選項,由伺服器端從模型的回覆中轉換而來 (選項區塊會從串流和保留的文字中移除)。控制台會顯示可透過鍵盤操作的選項清單,並固定在撰寫工具上方。

JSON 表示法
{
  "questions": [
    {
      object (OptionQuestionsChunk.Question)
    }
  ]
}
欄位
questions[]

object (OptionQuestionsChunk.Question)

本回合提出的問題。如果有多個項目,控制台會顯示「1 of N」翻頁元素。

OptionQuestionsChunk.Question

一個問題和選項。

JSON 表示法
{
  "question": string,
  "options": [
    {
      object (OptionQuestionsChunk.Option)
    }
  ]
}
欄位
question

string

問題標題文字。

options[]

object (OptionQuestionsChunk.Option)

可選取的選項,依顯示順序排列。

OptionQuestionsChunk.Option

單一可選取的選項。

JSON 表示法
{
  "title": string,
  "details": string,
  "submitText": string
}
欄位
title

string

簡短的純文字選項標題 (不含 Markdown 和編號)。

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

將這項要求與其回應建立關聯的 ID。對用戶端不透明;必須在回答要求時逐字回應。

context

string

說明確認內容的背景資訊 (例如:代理要執行的動作,或需要回答的問題)。以純文字形式顯示,而非 Markdown。

positiveLabel

string

二進位確認核准動作的標籤 (例如「發布」)。如果已填入 questions,則不設定。

negativeLabel

string

二進位確認拒絕動作的標籤 (例如「還沒」)。如果已填入 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 個應用程式」和每個應用程式一個徽章。舊版單一目標資訊卡則為空白。

AssistantConfirmationRequest.Target

確認動作會變更的一項資源。

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}

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)

如果沒有任何用戶端連結,系統會關閉 TURN。

使用 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

已結束轉彎的 ID,與 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 回合已執行完畢,工作階段會保留已提交的輸出內容。
ABANDONED 沒有任何工作在驅動該回合,該回合已密封為已提交的部分,無法繼續。
RESUME_UNAVAILABLE 這個伺服器不提供附加或繼續工作階段的功能,因此未追蹤任何內容;用戶端應重新載入工作階段。

TurnMetadata

回合層級中繼資料和意圖分類。

JSON 表示法
{
  "contractRelated": boolean,
  "contractFinalized": boolean,
  "contractStreamingPhase": enum (TurnMetadata.ContractStreamingPhase),
  "contractDraftComplete": boolean
}
欄位
contractFinalized

boolean

在合約草稿發布 (修訂版本已啟用) 的回合最終構件事件中設定。這份草稿的釐清流程終端:contractProgress 具有權威性且完整。

contractStreamingPhase

enum (TurnMetadata.ContractStreamingPhase)

僅在合約構件柵欄串流期間發出的執行中進度預估,以及修訂版本開始事件中設定。未設定授權酬載。

contractDraftComplete

boolean

在合約草稿的終端事件上設定,該草稿的每個預留位置都已解析 (contractProgress 為 100%),無論草稿是否已發布。用戶端完成並關閉合約進度顯示畫面;發布作業會由 contractFinalized 另外回報。

TurnMetadata.ContractStreamingPhase

合約進度酬載的串流階段。

列舉
CONTRACT_STREAMING_PHASE_UNSPECIFIED 酬載具有權威性 (根據完整合約文件、永久快照或預先草稿狀態計算)。用戶端必須將先前收到的進度替換為此進度。
DRAFTING 系統正在串流初始合約草稿。contractProgress 是進行中的預估值:在一個構件範圍內不會減少,上限低於授權範圍,且 pillarBreakdowns 包含 totalItemCount == 0,用於標示預估的支柱狀態。
REVISING 現有合約的修訂版本正在串流 (例如提交註解後)。預估語意與 DRAFTING 相同。