Method: projects.locations.collections.engines.assistants.streamAssist

以串流方式協助使用者查詢。

HTTP 要求


POST https://discoveryengine.googleapis.com/v1alpha/{name=projects/*/locations/*/collections/*/engines/*/assistants/*}:streamAssist

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

路徑參數

參數
name

string

這是必要旗標，Assistant 的資源名稱。格式：projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/assistants/{assistant}

要求主體

要求主體包含下列結構的資料：

JSON 表示法 
{
  "query": {
    object (Query)
  },
  "answerGenerationMode": enum (AnswerGenerationMode),
  "session": string,
  "isSessionLess": boolean,
  "assistSkippingMode": enum (AssistSkippingMode),
  "fileIds": [
    string
  ],
  "browserContext": {
    object (BrowserContext)
  },
  "userMetadata": {
    object (AssistUserMetadata)
  },
  "languageCode": string,
  "googleSearchGroundingEnabled": boolean,
  "webGroundingEnabled": boolean,
  "dataStoreSpecs": [
    {
      object (DataStoreSpec)
    }
  ],
  "agentsConfig": {
    object (AgentsConfig)
  },
  "agentsSpec": {
    object (AgentsSpec)
  },
  "assistGenerationConfig": {
    object (AssistGenerationConfig)
  },
  "cannedQuery": string,
  "toolsSpec": {
    object (ToolsSpec)
  },
  "generationSpec": {
    object (GenerationSpec)
  },
  "actionSpec": {
    object (ActionSpec)
  }
}
欄位
query

object (Query)

選用。目前使用者查詢。

只有在提供 fileIds 時，系統才支援空白查詢。在這種情況下，系統會根據這些脈絡檔案生成回覆。
answerGenerationMode

enum (AnswerGenerationMode)

選用。生成答案的模式。如未指定，則預設為 NORMAL。
session

string

選用。用於要求的會期。如果指定，助理就能存取工作階段記錄，並將查詢和答案儲存在該處。

如果將 - 指定為工作階段 ID，或將其留空，系統就會建立新的工作階段，並自動產生 ID。

格式：projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}
isSessionLess

boolean

選用。指定要求是否不含工作階段。

如果為 true，要求會在沒有任何工作階段的情況下執行：系統不會建立工作階段，要求也不會與任何現有工作階段建立關聯，即使 session 為空或設為「-」也一樣。回應的 SessionInfo.session 會是空白。

如果為 true，且 session 也設為非空值 (「-」除外)，系統會拒絕要求並傳回 INVALID_ARGUMENT。
assistSkippingMode

enum (AssistSkippingMode)

選用。決定助理不會回覆查詢的案例。如果跳過回答，原因會列在 AssistAnswer.assist_skipped_reasons 的 AssistResponse.answer 中。
fileIds[]

string

選用。用於回覆要求的檔案 ID。上傳檔案時，系統會在 AddContextFileResponse.file_id 中傳回檔案 ID。
browserContext

object (BrowserContext)

選用。使用者正在瀏覽的網頁內容，例如來自 Gemini Enterprise Chrome 側邊面板。
userMetadata

object (AssistUserMetadata)

選用。發起查詢的使用者相關資訊。
languageCode
(deprecated)

string

選用。已淘汰，請改用 preferredLanguageCode。如果語言偵測失敗，系統會使用此語言回覆。無論語言偵測結果為何，動作建立的錯誤訊息都會使用這個語言。
googleSearchGroundingEnabled
(deprecated)

boolean

選用。已淘汰，請勿使用這個欄位。
webGroundingEnabled
(deprecated)

boolean

選用。已淘汰，請勿使用這個欄位。
dataStoreSpecs[]
(deprecated)

object (DataStoreSpec)

選用。已淘汰：請改用 dataStoreSpecs。定義 DataStore 的規格，可在搜尋呼叫中進行篩選，以及這些資料儲存庫的設定。只有在Engine有多個資料儲存庫時，系統才會考量這項因素。

如果未設定這個欄位，系統會使用引擎中的所有資料儲存庫，但 ignoreDataStores 設為 true 時除外。
agentsConfig

object (AgentsConfig)

選用。用於處理要求的代理程式設定。
agentsSpec

object (AgentsSpec)

選用。用於處理要求的代理程式規格。
assistGenerationConfig
(deprecated)

object (AssistGenerationConfig)

選用。已淘汰，請改用 generationSpec。要求層級的生成設定。這項設定可用於在引擎層級覆寫預設的生成設定。
cannedQuery

string

選用。這項要求的 CannedQuery 資源名稱。只有在工作階段為新工作階段時，才能設定這個參數，否則系統會傳回 INVALID_ARGUMENT 錯誤。

如果提供 StreamAssistRequest.session，但對應的 Session 沒有任何輪流對話，或未提供 StreamAssistRequest.session (並建立新的 Session)，系統就會將工作階段視為新的工作階段。

如果提供 cannedQuery 參數，系統會在處理期間考量對應的 CannedQuery。CannedQuery中會說明並記錄確切行為。

格式：projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/assistants/{assistant}/cannedQueries/{cannedQuery}
toolsSpec

object (ToolsSpec)

選用。用於處理要求的工具規格。
generationSpec

object (GenerationSpec)

選用。要求的生成設定規格。
actionSpec

object (ActionSpec)

選用。要求的動作規格。

回應主體

AssistantService.StreamAssist 方法的回應。

如果成功，回應主體會含有以下結構的資料：

JSON 表示法 
{
  "answer": {
    object (AssistAnswer)
  },
  "sessionInfo": {
    object (SessionInfo)
  },
  "statusUpdates": [
    {
      object (StatusUpdate)
    }
  ],
  "assistToken": string,
  "toolResult": [
    {
      object (ToolResult)
    }
  ],
  "finalResultToolInvocationId": string,
  "invocationTools": [
    string
  ],
  "invokedSkills": [
    {
      object (InvokedSkill)
    }
  ],
  "connectorAuthErrors": [
    {
      object (ConnectorAuthError)
    }
  ]
}
欄位
answer

object (AssistAnswer)

assistants.assist 答案資源物件，內含 AI 助理對使用者查詢的最終回覆部分內容。

如果目前的回覆未在先前傳送的 AssistAnswer.replies 中新增任何內容，則不會顯示。

觀察 AssistAnswer.state，看看是否會出現更多部分。當狀態為 IN_PROGRESS 時，每個回應中的 AssistAnswer.replies 欄位都會包含回覆 (回覆片段)，這些回覆會附加至先前回應中收到的回覆。AssistAnswer.name不會填入。

如果狀態為 SUCCEEDED、FAILED 或 SKIPPED，則回應為最後一個回應，且 AssistAnswer.name 會包含值。
sessionInfo

object (SessionInfo)

工作階段資訊。僅包含在回覆串流的最終 StreamAssistResponse 中。
statusUpdates[]

object (StatusUpdate)

選用進度更新。
assistToken

string

全域專屬 ID，用於識別目前的要求和回覆串流。用於意見回饋和支援。
toolResult[]
(deprecated)

object (ToolResult)

工具呼叫的結果。
finalResultToolInvocationId

string

如果這個欄位存在，則包含工具調用的 ID，其結果會做為最終答案。
invocationTools[]

string

所叫用工具的工具名稱。
invokedSkills[]

object (InvokedSkill)

該回合執行的技能。
connectorAuthErrors[]

object (ConnectorAuthError)

要求期間發生每個連接器的驗證錯誤。當一或多個連接器驗證失敗，但要求繼續使用其餘連接器時，就會顯示這項資訊。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.assist.readwrite
  • https://www.googleapis.com/auth/discoveryengine.readwrite
  • https://www.googleapis.com/auth/discoveryengine.serving.readwrite

詳情請參閱Authentication Overview。

IAM 權限

需要 name 資源的下列 IAM 權限：

  • discoveryengine.assistants.assist

詳情請參閱 IAM 說明文件。

AnswerGenerationMode

可用的答案生成模式。

列舉
ANSWER_GENERATION_MODE_UNSPECIFIED 未指定答案生成模式。
NORMAL 一般答案生成模式。可能會觸發幾次搜尋和通話動作。
RESEARCH 研究答案生成模式。深入瞭解查詢，針對與查詢相關的各種主題觸發許多搜尋。
AGENT 直接代理程式答案生成模式：使用 agentsConfig 中定義的代理程式生成答案。

AssistSkippingMode

可略過的輔助要求。

列舉
ASSIST_SKIPPING_MODE_UNSPECIFIED 預設值。如果查詢並非尋求協助，可以略過答案。
REQUEST_ASSIST 要求 Google 助理回答問題。如果查詢未通過政策檢查，系統仍可能會略過答案。

BrowserContext

使用者正在瀏覽的網頁內容，例如來自 Gemini Enterprise Chrome 側邊面板。這類檔案會由用戶端加密，不會以模型輸入內容的形式附加至要求；消費者會使用 encryptionMetadata 讀取這些檔案。

JSON 表示法 
{
  "activeTab": {
    object (Tab)
  },
  "encryptionMetadata": {
    object (EncryptionMetadata)
  }
}
欄位
activeTab

object (Tab)

選用。使用者目前瀏覽的分頁。每個檔案 ID 都代表先前上傳至工作階段的檔案 (其 ID 會在 AddContextFileResponse.file_id 中傳回)。請勿在 fileIds 中列出這些 ID：這會將檔案附加為一般檔案，並略過瀏覽器環境處理程序。
encryptionMetadata

object (EncryptionMetadata)

選用。這個瀏覽器環境參照的檔案加密方式。一個鍵組涵蓋整個要求，而非個別索引標籤。

Tab 鍵

內容附加至要求的瀏覽器分頁。

JSON 表示法 
{
  "uri": string,
  "title": string,
  "selectedText": string,
  "screenshotFileId": string,
  "annotatedPageContentFileId": string
}
欄位
uri

string

選用。分頁顯示的網頁 URI。不一定是 http(s) 網址：分頁可能顯示 chrome://settings、about:blank 或 file:// 路徑。
title

string

選用。分頁顯示的網頁標題。
selectedText

string

選用。使用者在頁面上選取的文字 (如有)。
screenshotFileId

string

選用。上傳的顯示頁面螢幕截圖 ID。
annotatedPageContentFileId

string

選用。上傳頁面內容的 ID：序列化的註解頁面內容 (APC) 擷取內容，而非預先算繪的文字。

EncryptionMetadata

用戶端如何加密瀏覽器內容檔案。

JSON 表示法 
{
  "encrypted": boolean,
  "keyset": string
}
欄位
encrypted

boolean

選用。瀏覽器內容檔案是否經過加密。如果值為 true，則必須設定 keyset，否則無法讀取檔案。
keyset

string (bytes format)

選用。使用 AEAD 原始功能序列化的 Tink 金鑰集，用於解密瀏覽器脈絡檔案。僅在要求生命週期內存在，且絕不會記錄。

Base64 編碼字串。

AgentsConfig

用於處理要求的代理程式設定。

JSON 表示法 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "noCodeAgentsConfig": {
    object (NoCodeAgentsConfig)
  },
  "assistantAgentConfigId": string,
  "agent": string,
  "inlineAgent": {
    object (Agent)
  },
  "vertexAiAgentId": string
  // End of mutually exclusive fields.
}
欄位
設定不同類型的代理程式。以下列出互斥欄位。回應中最多會設定一個欄位：
noCodeAgentsConfig
(deprecated)

object (NoCodeAgentsConfig)

選用。已淘汰：無程式碼 Agentspace 代理的設定。設定完成後，系統會根據設定處理 assistants.assist 要求。請改用 agent。
assistantAgentConfigId

string

選用。來自 Assistant.agent_configs 的代理程式 ID
agent

string

要使用的代理程式名稱。格式：projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/assistants/{assistant}/agents/{agent}
inlineAgent

object (Agent)

要使用的 Agent 內嵌定義。如果提供，系統會使用根據這項定義的代理。這是代理的暫時代表，系統會忽略 Agent.name 欄位。
vertexAiAgentId

string

選用。來自 Assistant.vertex_ai_agent_configs 的代理程式 ID。ID 可以是設定中註冊的全名，也可以是最後一個斜線後的部分。
互斥欄位的結尾。

NoCodeAgentsConfig

已淘汰：無程式碼 Agentspace 代理的設定。請改用 agent。

JSON 表示法 
{
  "agent": string
}
欄位
agent

string

選用。要使用的代理程式名稱。

AgentsSpec

用於處理要求的代理程式規格。

JSON 表示法 
{
  "agentSpecs": [
    {
      object (AgentSpec)
    }
  ],
  "mentionMode": enum (MentionMode)
}
欄位
agentSpecs[]

object (AgentSpec)

選用。用於處理要求的代理程式規格。
mentionMode

enum (MentionMode)

選用。如何在 agentSpecs 中叫用提及的代理。詳情請參閱 MentionMode。

AgentSpec

代理程式規格。

JSON 表示法 
{
  "agentId": string,
  "inputVariables": {
    object
  }
}
欄位
agentId

string

這是必要旗標，用於識別處理要求的代理程式資源。

這個欄位必須符合 RFC-1034，長度上限為 63 個半形字元。
inputVariables

object (Struct format)

選用。在 WorkflowAgent 叫用時提供的輸入變數。鍵是已宣告的輸入變數名稱，值則是使用者或呼叫端提供的值。以全域輸入內容的形式，向下游節點公開。

MentionMode

如何在 agentSpecs 中叫用提及的代理。

列舉
MENTION_MODE_UNSPECIFIED 預設值為 DIRECT。
DIRECT 提及的代理程式會成為執行回合的頂層代理程式。agentSpecs 中只能有一個項目。
TOOL 每個 AgentSpec 都會以工具形式附加至合成的協調器。多次提及。MVP：僅限工作流程代理程式，最新發布的修訂版本；請勿設定 version / revisionId。
TOOL_WORKFLOW_DIRECT 單一工作流程代理，做為獨立的對話介面。只能設定一個 AgentSpec；請設定 version = "draft" (代理程式資料表) 或 revisionId (特定 AgentRevision)。工作流程必須有 ManualTrigger。

ToolsSpec

用於處理要求的工具規格。

JSON 表示法 
{
  "toolRegistry": string,
  "vertexAiSearchSpec": {
    object (VertexAiSearchSpec)
  },
  "webGroundingSpec": {
    object (WebGroundingSpec)
  },
  "imageGenerationSpec": {
    object (ImageGenerationSpec)
  },
  "videoGenerationSpec": {
    object (VideoGenerationSpec)
  },
  "mapsGroundingSpec": {
    object (MapsGroundingSpec)
  }
}
欄位
toolRegistry

string

選用。要使用的工具登錄檔名稱。格式：projects/{project}/locations/{location}/toolRegistries/{toolRegistry}
vertexAiSearchSpec

object (VertexAiSearchSpec)

選用。Vertex AI Search 工具的規格。
webGroundingSpec

object (WebGroundingSpec)

選用。網頁基準工具的規格。如有這個欄位，即可啟用網頁搜尋基準建立功能。只有在 Assistant.web_grounding_type 為 WEB_GROUNDING_TYPE_GOOGLE_SEARCH 或 WEB_GROUNDING_TYPE_ENTERPRISE_WEB_SEARCH 時，這項屬性才會生效。
imageGenerationSpec

object (ImageGenerationSpec)

選用。圖像生成工具的規格。
videoGenerationSpec

object (VideoGenerationSpec)

選用。影片生成工具的規格。
mapsGroundingSpec

object (MapsGroundingSpec)

選用。Google 地圖建立基準工具的規格。如有這個欄位，則會啟用利用 Google 地圖建立基準的服務。

VertexAiSearchSpec

Vertex AI Search 工具的規格。

JSON 表示法 
{
  "disabled": boolean,
  "dataStoreSpecs": [
    {
      object (DataStoreSpec)
    }
  ],
  "filter": string
}
欄位
disabled
(deprecated)

boolean

選用。已淘汰，請勿使用這個欄位。Vertex AI Search 工具是否已停用。預設值為 false，工具預設為啟用。
dataStoreSpecs[]

object (DataStoreSpec)

選用。定義 DataStore 的規格，可在搜尋呼叫中進行篩選，以及這些資料儲存庫的設定。只有在Engine有多個資料儲存庫時，系統才會考量這項因素。
filter

string

選用。篩選器語法包含運算式語言，可從要篩選的文件中一或多個欄位建構述詞。篩選運算式會區分大小寫。

如果無法辨識這個欄位，系統會傳回 INVALID_ARGUMENT。

在 Vertex AI Search 中，篩選作業是透過將 LHS 篩選鍵對應至 Vertex AI Search 後端定義的鍵屬性來完成，而這項對應是由客戶在結構定義中定義。舉例來說，媒體客戶的結構定義中可能會有「name」欄位。在本例中，篩選器會如下所示：filter --> name:'ANY("king kong")'

如要進一步瞭解篩選功能，包括語法和篩選運算子，請參閱「篩選」

WebGroundingSpec

這個類型沒有任何欄位。

網頁基準工具的規格。

ImageGenerationSpec

這個類型沒有任何欄位。

圖像生成工具的規格。

VideoGenerationSpec

這個類型沒有任何欄位。

影片生成工具的規格。

MapsGroundingSpec

這個類型沒有任何欄位。

Google 地圖基礎工具的規格。

GenerationSpec

要求的 Google 助理生成規格。這項功能可讓您在引擎層級覆寫預設生成設定。

JSON 表示法 
{
  "modelId": string
}
欄位
modelId

string

選用。用於生成模型的 Vertex AI modelId。如未設定，系統會使用預設的 Google 助理模型。

ActionSpec

要求的動作規格。

JSON 表示法 
{
  "actionDisabled": boolean
}
欄位
actionDisabled

boolean

選用。如果是 true，系統就不會放送要求中的動作。這項功能僅適用於企業版。

SessionInfo

工作階段相關資訊。

JSON 表示法 
{
  "session": string,
  "queryId": string
}
欄位
session

string

新生成或繼續的對話名稱。

格式：projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}。
queryId

string

與這項輔助 API 呼叫相應的查詢 ID。一個工作階段可以有多個回合，每個回合都有專屬的查詢 ID。

在 assistants.assist API 呼叫中指定工作階段名稱和這個查詢 ID，輔助要求就會在這個搜尋呼叫的搜尋結果環境中進行。

StatusUpdate

提供有關輔助通話進度的最新消息。

JSON 表示法 
{
  "updateText": string,
  "invocationId": string
}
欄位
updateText

string

自由輸入狀態更新，例如「開始在人資文件內搜尋福利」或「搜尋『登月』得到 12 個結果」。
invocationId

string

產生更新的調用作業專屬 ID。

ToolResult

(部分) 工具呼叫結果。

JSON 表示法 
{
  "toolInvocationId": string,
  "result": {
    object (Reply)
  }
}
欄位
toolInvocationId

string

生成結果的工具調用專屬 ID。
result

object (Reply)

結果的部分內容。

InvokedSkill

代表在輔助通話期間使用的技能。

JSON 表示法 
{
  "name": string,
  "displayName": string
}
欄位
name

string

技能的資源名稱。
displayName

string

技能的顯示名稱。

ConnectorAuthError

說明特定資料連接器的驗證錯誤。

JSON 表示法 
{
  "dataConnector": string,
  "errorMessage": string
}
欄位
dataConnector

string

無法通過驗證的資料連接器資源名稱。
errorMessage

string

人類可讀的錯誤訊息，說明驗證失敗的原因。