- HTTP 要求
- 路徑參數
- 要求主體
- 回應主體
- 授權範圍
- IAM 權限
- AssistantConfirmationResponse
- StreamChatAiAssistantRequest.ClientCapability
- OperationCompletedEvent
- ArtifactChunk
- ArtifactChunk.State
- OptionQuestionsChunk
- OptionQuestionsChunk.Question
- OptionQuestionsChunk.Option
- AssistantConfirmationRequest
- AssistantConfirmationRequest.Target
- TurnResumeSnapshot
- TurnHandoffEvent
- TurnHandoffEvent.Reason
- TurnCompletedEvent
- TurnCompletedEvent.Reason
- TurnMetadata
- TurnMetadata.ContractStreamingPhase
以串流方式,為指定助理工作階段執行 AI 助理 Arc。
HTTP 要求
POST https://ces.googleapis.com/v1beta/{name=projects/*/locations/*/apps/*/assistantSessions/*}:streamChatAiAssistant
這個網址使用 gRPC 轉碼語法。
路徑參數
| 參數 | |
|---|---|
name |
這是必要旗標,用於執行助理的助理工作階段。格式: |
要求主體
要求主體包含下列結構的資料:
| JSON 表示法 |
|---|
{ "message": string, "attachedGcsUris": [ string ], "contextToken": string, "confirmationResponse": { object ( |
| 欄位 | |
|---|---|
message |
選用。要傳送給助理代理的訊息。如果已設定 |
attachedGcsUris[] |
選用。使用者在這輪對話上傳檔案的 Cloud Storage URI。範例:「gs://cxas-transient-uploads/uuid/prd.pdf」 |
contextToken |
選用。 |
confirmationResponse |
選用。使用者對待處理 |
clientCapabilities[] |
選用。這個用戶端可顯示的回應功能。伺服器只會在宣告功能時,發出需要該功能的事件 (例如 |
operationCompletedEvent |
選用。繼續執行助理工作階段,該工作階段先前因等待用戶端管理的長時間執行的作業完成而暫停。 |
resumeFromSequenceNumber |
選用。選用游標,可從進行中或已完成的回合繼續及重播事件。 |
attachOnly |
選用。選用標記,可附加至現有的進行中回合,不需提交新訊息。 |
回應主體
SessionService.StreamChatAiAssistant 的回應訊息。
如果成功,回應主體會含有以下結構的資料:
| JSON 表示法 |
|---|
{ "eventId": string, "eventTime": string, "uiEvent": { object ( |
| 欄位 | |
|---|---|
eventId |
事件的專屬 ID。 |
eventTime |
事件發生時的時間戳記。 使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例: |
uiEvent |
選用。UI 事件酬載。 |
turnMetadata |
選用。回合層級中繼資料和意圖分類。 |
sequenceNumber |
選用。這個工作階段回合的序號,會單調遞增。 |
turnInProgress |
選用。指出轉彎是否仍在背景執行。 |
| 事件酬載。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位: | |
textChunk |
文字詞元 (用於逐字串流 Gemini 回覆)。 |
status |
簡單的狀態更新。 |
thoughtChunk |
思考文字區塊 (代理生成回覆前的推論過程)。 |
toolCall |
工具呼叫執行事件。 |
toolResponse |
工具呼叫回應事件。 |
artifactChunk |
生成文件構件事件 (即時預覽差異 + 最終 Cloud Storage 指標)。 |
optionQuestionsChunk |
從模型對話剖析出的結構化澄清選項。控制台會將這些內容轉譯為可選取的選項清單,而非原始文字。 |
confirmationRequest |
代理暫停時的封鎖確認。當後續要求的 |
sessionCheckpoint |
工作階段檢查點/壓縮摘要事件,包含使用者意圖和滾動摘要。 |
resumeSnapshot |
在任何即時事件之前,系統會傳送壓縮的重播事件,做為每個附加或繼續事件的第一個事件。用戶端會將這個回合在本機轉譯的所有狀態,替換為快照內容。 |
handoff |
指示用戶端使用 resumeFromSequenceNumber 重新連線,且不顯示任何訊息:提供這個串流的工作即將結束,且會繼續在其他位置執行。這不是錯誤,串流會在這個事件後正常完成。 |
turnCompleted |
回合已結束。在原始串流和每個附加或恢復的串流上,做為每個回合的最後一個事件傳送,讓用戶端能根據明確信號結束回合,而非從串流關閉推斷。 |
| 互斥欄位結束。 | |
授權範圍
需要下列其中一種 OAuth 範圍:
https://www.googleapis.com/auth/cloud-platformhttps://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 |
|
| 使用者的答案。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位: | |
confirmed |
二進位答案:true 表示核准暫停動作,false 表示拒絕。 |
answerText |
所選選項的 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 ( |
| 欄位 | |
|---|---|
operationName |
作業資源名稱 (例如 |
targetResourceName |
作業的主要目標或產生的資源 (例如評估執行作業 ID、應用程式 ID、資料集 ID)。 |
operationType |
作業類型或工具名稱 (例如「run_evaluation」、「copy_app」、「export_app」)。 |
status |
作業執行的狀態 (例如「SUCCEEDED」、「FAILED」、「CANCELLED」)。 |
deduplicationToken |
選用簡化權杖 (例如 UUID),防止並行瀏覽器分頁重複執行回合。 |
error |
作業失敗時的標準錯誤狀態 (選用)。 |
metadata |
選填的結構化結果中繼資料 (例如 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 ( |
| 欄位 | |
|---|---|
artifactId |
構件的 ID,在串流中一個構件的所有區塊中皆相同。 |
displayName |
向使用者顯示的檔案名稱,例如「hotel_booking_tdd.md」。在 STARTED 狀態設定 (並在 FINALIZED 狀態重複)。 |
mimeType |
構件內容的 IANA 媒體類型,例如「text/markdown」。 |
contentDelta |
增量構件內容。在 DELTA 區塊上設定。 |
gcsUri |
構件保存至的 Cloud Storage 物件。在 FINALIZED 區塊上設定。 |
state |
這個區塊的生命週期位置。 |
targetApp |
僅供輸出。如果這個構件是為某個應用程式產生,則會顯示該應用程式。格式: |
ArtifactChunk.State
這個區塊在構件串流中的生命週期位置。
| 列舉 | |
|---|---|
STATE_UNSPECIFIED |
未使用的預設值。 |
STARTED |
助理已開始生成構件。 |
DELTA |
內容增量;已設定 contentDelta。 |
FINALIZED |
構件已保存,gcsUri 已設定。 |
FAILED |
生成或保存失敗,未儲存構件。 |
CLOSED |
文件串流完成:內容已透過 contentDelta 區塊完整傳送。系統仍可能執行永久保存作業;如果構件已儲存,系統會傳送含有 gcsUri 的 FINALIZED 區塊。 |
OptionQuestionsChunk
Google 助理要求使用者選擇的結構化釐清選項,由伺服器端從模型的回覆中轉換而來 (選項區塊會從串流和保留的文字中移除)。控制台會顯示可透過鍵盤操作的選項清單,並固定在撰寫工具上方。
| JSON 表示法 |
|---|
{
"questions": [
{
object ( |
| 欄位 | |
|---|---|
questions[] |
本回合提出的問題。如果有多個項目,控制台會顯示「1 of N」翻頁元素。 |
OptionQuestionsChunk.Question
一個問題和選項。
| JSON 表示法 |
|---|
{
"question": string,
"options": [
{
object ( |
| 欄位 | |
|---|---|
question |
問題標題文字。 |
options[] |
可選取的選項,依顯示順序排列。 |
OptionQuestionsChunk.Option
單一可選取的選項。
| JSON 表示法 |
|---|
{ "title": string, "details": string, "submitText": string } |
| 欄位 | |
|---|---|
title |
簡短的純文字選項標題 (不含 Markdown 和編號)。 |
details |
次要文字顯示選用的權衡詳細資料。 |
submitText |
選擇選項時要傳送的訊息文字 (選用);如果留空,預設為 |
AssistantConfirmationRequest
助理需要先回答封鎖問題或確認,才能繼續執行代理動作。提出要求的代理會暫停,直到後續的 StreamChatAiAssistantRequest.confirmation_response 傳回答案後才會恢復。
| JSON 表示法 |
|---|
{ "confirmationId": string, "context": string, "positiveLabel": string, "negativeLabel": string, "questions": [ { object ( |
| 欄位 | |
|---|---|
confirmationId |
將這項要求與其回應建立關聯的 ID。對用戶端不透明;必須在回答要求時逐字回應。 |
context |
說明確認內容的背景資訊 (例如:代理要執行的動作,或需要回答的問題)。以純文字形式顯示,而非 Markdown。 |
positiveLabel |
二進位確認核准動作的標籤 (例如「發布」)。如果已填入 |
negativeLabel |
二進位確認拒絕動作的標籤 (例如「還沒」)。如果已填入 |
questions[] |
確認的多選表單。填入後,資訊卡會顯示可選取的選項清單,並將所選選項的 submitText (或任意形式的使用者文字) 傳回為 |
tool |
代理暫停的工具呼叫名稱 (例如「update_app」),用於資訊卡標題。如果是純問題,則不設定。 |
agentName |
資訊卡標頭:提出確認要求的代理顯示標籤 (例如「 |
expireTime |
超過這個時間後,就無法再回覆這項確認要求。過期的卡片會顯示為無效,伺服器會在下一輪拒絕確認,因此暫停的代理不會無限期等待。 使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例: |
targets[] |
確認動作會變更的所有內容,因此控制台可以顯示「更新 2 個應用程式」和每個應用程式一個徽章。舊版單一目標資訊卡則為空白。 |
AssistantConfirmationRequest.Target
確認動作會變更的一項資源。
| JSON 表示法 |
|---|
{ "resource": string, "displayName": string, "action": string, "targetApp": string } |
| 欄位 | |
|---|---|
resource |
要變更的資源,以完整資源名稱表示。 |
displayName |
資訊卡中資源或應用程式的顯示名稱。 |
action |
動作,例如 |
targetApp |
資源所屬的應用程式,如果是建立應用程式等位置範圍動作,則留空。格式: |
TurnResumeSnapshot
轉彎期間的精簡重播:轉彎時顯示輸出內容所需的一切,以及即時事件繼續的位置。
| JSON 表示法 |
|---|
{
"turnId": string,
"resolvedSequenceNumber": string,
"events": [
{
object ( |
| 欄位 | |
|---|---|
turnId |
用於識別要附加的轉彎。 |
resolvedSequenceNumber |
這個快照代表的位置。現場直播活動的 sequenceNumber 必須大於這個值。如果低於用戶端要求的 resumeFromSequenceNumber,清除進度會落後於用戶端已算繪的內容:用戶端必須捨棄這一輪超過這個位置的算繪內容,才能套用快照。 |
events[] |
精簡事件會按照轉譯順序,使用與直播相同的事件形狀,重建該回合的可見輸出內容。 |
orphanDeadlineTime |
如果沒有任何用戶端連結,系統會關閉 TURN。 使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例: |
TurnHandoffEvent
這項工作在對話中途停止提供串流 (例如伺服器重新啟動) 前,會發出這個事件。系統會保留對話狀態,並在重新連線時,使用 resumeFromSequenceNumber 繼續執行其他工作。
| JSON 表示法 |
|---|
{
"turnId": string,
"reason": enum ( |
| 欄位 | |
|---|---|
turnId |
識別要繼續的回合。 |
reason |
串流接力播放的原因。 |
TurnHandoffEvent.Reason
串流接力播放的原因。
| 列舉 | |
|---|---|
REASON_UNSPECIFIED |
未指定。 |
SERVER_RESTART |
服務工作正在關閉 (發布推送或重新排程)。 |
TurnCompletedEvent
對話回合的終端事件 (請參閱 StreamChatAiAssistantResponse.turn_completed)。
| JSON 表示法 |
|---|
{
"turnId": string,
"reason": enum ( |
| 欄位 | |
|---|---|
turnId |
已結束轉彎的 ID,與 TurnResumeSnapshot.turn_id 和 ActiveTurnInfo.turn_id 相符。 |
reason |
回合結束的原因。 |
finalSequenceNumber |
回合產生的最後一個事件序號。如果用戶端的游標位置較低,表示錯過了內容,應重新載入工作階段才能看到。 |
touchedApps[] |
本次指定或變更的應用程式,讓控制台能準確重新整理這些應用程式的商店。僅限專案範圍工作階段。格式: |
TurnCompletedEvent.Reason
回合結束的原因,讓較晚加入的用戶端可以根據結果判斷,而不是從空白串流中猜測。
| 列舉 | |
|---|---|
REASON_UNSPECIFIED |
未指定。 |
COMPLETED |
回合已執行完畢,工作階段會保留已提交的輸出內容。 |
ABANDONED |
沒有任何工作在驅動該回合,該回合已密封為已提交的部分,無法繼續。 |
RESUME_UNAVAILABLE |
這個伺服器不提供附加或繼續工作階段的功能,因此未追蹤任何內容;用戶端應重新載入工作階段。 |
TurnMetadata
回合層級中繼資料和意圖分類。
| JSON 表示法 |
|---|
{
"contractRelated": boolean,
"contractFinalized": boolean,
"contractStreamingPhase": enum ( |
| 欄位 | |
|---|---|
contractRelated |
指出這個助理回合是否與合約相關 (例如合約草擬、調整、擷取或修訂)。 |
contractFinalized |
在合約草稿發布 (修訂版本已啟用) 的回合最終構件事件中設定。這份草稿的釐清流程終端:contractProgress 具有權威性且完整。 |
contractStreamingPhase |
僅在合約構件柵欄串流期間發出的執行中進度預估,以及修訂版本開始事件中設定。未設定授權酬載。 |
contractDraftComplete |
在合約草稿的終端事件上設定,該草稿的每個預留位置都已解析 (contractProgress 為 100%),無論草稿是否已發布。用戶端完成並關閉合約進度顯示畫面;發布作業會由 contractFinalized 另外回報。 |
TurnMetadata.ContractStreamingPhase
合約進度酬載的串流階段。
| 列舉 | |
|---|---|
CONTRACT_STREAMING_PHASE_UNSPECIFIED |
酬載具有權威性 (根據完整合約文件、永久快照或預先草稿狀態計算)。用戶端必須將先前收到的進度替換為此進度。 |
DRAFTING |
系統正在串流初始合約草稿。contractProgress 是進行中的預估值:在一個構件範圍內不會減少,上限低於授權範圍,且 pillarBreakdowns 包含 totalItemCount == 0,用於標示預估的支柱狀態。 |
REVISING |
現有合約的修訂版本正在串流 (例如提交註解後)。預估語意與 DRAFTING 相同。 |