附註：這組說明文件適用於 Gemini Enterprise 的 Standard、Plus、即付即用和 Frontline 版本。如需 Business 版說明文件，請參閱 Gemini Enterprise - Business 版說明中心。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用 StreamAssist API 呼叫特定代理程式

如要呼叫特定已註冊的代理程式，請在 streamAssist REST API 要求或用戶端程式庫呼叫中提供選用的 agentsSpec 欄位。AgentsSpec API 定義用於處理要求的代理規格。助理會將查詢直接轉送至該代理，並在各輪對話中保留工作階段內容。

概覽

規格	詳細資料
API 方法	`projects.locations.collections.engines.assistants.streamAssist`
端點版本	`v1alpha` 用於探索代理 ID；`v1` 用於呼叫 `streamAssist`
主要參數	`agentsSpec.agentSpecs[].agentId`
支援的代理程式類型	核心助理、深入研究、Workflow Builder 對話代理程式 (原為低程式碼) 和 Workflow Builder 工作流程 (請參閱「呼叫工作流程」)
必要的 IAM 權限	`discoveryengine.assistants.assist`
必要的 OAuth 範圍	`https://www.googleapis.com/auth/cloud-platform`

事前準備

在 Google Cloud 專案中啟用 Discovery Engine API (discoveryengine.googleapis.com)。
確認主體 (使用者帳戶或服務帳戶) 具有授予 discoveryengine.assistants.assist IAM 權限的角色，例如「Discovery Engine 編輯者」 (roles/discoveryengine.editor) 或「Gemini Enterprise 管理員」 (roles/discoveryengine.agentspaceAdmin)。
確認已建立 Gemini Enterprise 應用程式 (引擎)，且其中至少有一個已註冊的代理。
如果您使用應用程式預設憑證 (ADC) 進行驗證，請確認用戶端傳送配額專案標頭：-H "X-Goog-User-Project: PROJECT_ID"。

找出應用程式 ID 和位置

streamAssist 網址需要引擎 ID 和位置 (global、us 或 eu)。如果您只知道應用程式的顯示名稱，請列出專案中的引擎，找出基礎 ID：

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines"

在回應中，引擎 name 格式為 projects/{project}/locations/{location}/collections/default_collection/engines/{ENGINE_ID}。ENGINE_ID 區隔是呼叫中必要的 APP_ID。

找出代理 ID

agentId 是 Discovery Engine API 中代理完整資源名稱的最後一個區段：

projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/assistants/{assistant}/agents/{AGENT_ID}

註冊代理商會使用長數字 ID (例如 15492003793394502655)，而非友善的顯示名稱。在要求中，請只提供這個最終的 {AGENT_ID} 數字字串。

如要列出已向應用程式註冊的代理程式，並找出其數字 ID，請呼叫 v1alpha 端點上的 agents 集合：

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"

每個傳回的代理資源都包含下列欄位：

name：以 {AGENT_ID} 結尾的完整資源路徑。
displayName：顯示在 Google Cloud 控制台中的人類可讀名稱。
state：作業狀態 (例如 ENABLED 或 PRIVATE)。
定義物件，指出代理類型 (例如 a2aAgentDefinition、lowCodeAgentDefinition 或 workflowAgentDefinition)。

如需完整的代理資源結構定義，請參閱 agents REST API 參考資料。

傳送查詢給代理

如要將查詢傳送至特定代理，您必須使用適當的 agentsSpec 建構要求，並透過 REST 或用戶端程式庫執行。

要求主體結構

如要將查詢轉送至特定代理，請在 POST 要求主體中加入選用的 agentsSpec 物件：

{
  "query": {
    "text": "QUERY_TEXT"
  },
  "session": "SESSION_RESOURCE_NAME",
  "agentsSpec": {
    "agentSpecs": [
      {
        "agentId": "AGENT_ID"
      }
    ]
  }
}

欄位參考資料

agentsSpec (物件，選用)：用於處理要求的代理規格。
agentsSpec.agentSpecs[] (陣列，選用)：代理規格清單。您可以在這個陣列中指定多個代理程式。
agentsSpec.agentSpecs[].agentId (字串，規格內必填)：用於識別已註冊代理資源的 ID。必須符合 RFC-1034 規範，長度上限為 63 個字元。

如需完整的要求結構定義，請參閱 streamAssist REST API 參考資料。

通話串流小幫手

REST

下列 curl 指令會使用 REST API，將查詢傳送至特定代理：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant:streamAssist" \
  -d '{
    "query": {
      "text": "List all contact cards."
    },
    "agentsSpec": {
      "agentSpecs": [
        {
          "agentId": "AGENT_ID"
        }
      ]
    }
  }'

請替換下列預留位置：

LOCATION：主機名稱和資源路徑的多區域 (global、us 或 eu)。如果應用程式位於 global 位置，請從主機名稱中省略位置前置字元 (discoveryengine.googleapis.com)。
PROJECT_ID：您的 Google Cloud 專案 ID。
APP_ID：Gemini Enterprise 引擎 ID (請參閱「找出應用程式 ID 和位置」)。
AGENT_ID：代理的數字 ID (在「找出代理 ID」中找到)。

Python

這個 Python 範例使用 google-cloud-discoveryengine 用戶端程式庫呼叫 streamAssist：

# Install library: pip install google-cloud-discoveryengine
from google.api_core.client_options import ClientOptions
from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Replace placeholder values with your project and agent details.
project_id = "PROJECT_ID"
location = "LOCATION"          # For example: "us", "eu", or "global"
engine_id = "APP_ID"
agent_id = "AGENT_ID"          # The numeric agent ID
query_text = "List all contact cards."

client_options = (
    ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
    if location != "global"
    else None
)
client = discoveryengine.AssistantServiceClient(client_options=client_options)

assistant_path = client.assistant_path(
    project=project_id,
    location=location,
    collection="default_collection",
    engine=engine_id,
    assistant="default_assistant",
)

request = discoveryengine.StreamAssistRequest(
    name=assistant_path,
    query=discoveryengine.Query(text=query_text),
    agents_spec=discoveryengine.StreamAssistRequest.AgentsSpec(
        agent_specs=[
            discoveryengine.StreamAssistRequest.AgentsSpec.AgentSpec(
                agent_id=agent_id,
            )
        ]
    ),
)

for response in client.stream_assist(request=request):
    for reply in response.answer.replies:
        # Filter out model reasoning fragments (thought: true)
        if hasattr(reply, "grounded_content") and reply.grounded_content.content:
            print(reply.grounded_content.content.text, end="", flush=True)

print()

瞭解串流回應

streamAssist 端點會透過 REST 傳回 JSON 區塊串流，或在用戶端程式庫中傳回回應物件疊代器：

答案文字：增量回應文字會顯示在 answer.replies[].groundedContent.content.text 中。按照接收順序串連這些文字片段，即可重構完整答案。
推論片段：標示為 "thought": true 的片段代表模型的內部推論過程。向使用者呈現最終輸出內容時，請濾除這些片段。
執行狀態：answer.state 欄位會從 IN_PROGRESS 進入終端狀態：
- SUCCEEDED：要求已完成並生成答案。
- SKIPPED：系統已忽略或略過查詢。檢查 assistSkippedReasons 以瞭解詳情 (例如 NON_ASSIST_SEEKING_QUERY_IGNORED 代表簡短問候語)。
- FAILED：叫用作業發生執行錯誤。
工作階段連續性：終端區塊包含 sessionInfo.session (工作階段資源名稱) 和 assistToken。

在同一個工作階段中繼續對話

如要在多輪對話中保留情境資訊，請在後續要求中傳遞 sessionInfo 的 session 字串：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant:streamAssist" \
  -d '{
    "session": "projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/sessions/SESSION_ID",
    "query": {
      "text": "Who is John Doe?"
    },
    "agentsSpec": {
      "agentSpecs": [
        {
          "agentId": "AGENT_ID"
        }
      ]
    }
  }'

如果省略 session 欄位，或將工作階段 ID 指定為 -，API 會自動產生新的獨立工作階段。

呼叫工作流程

如要執行 Workflow Builder 工作流程，請傳送相同要求，並在 agentsSpec.agentSpecs[].agentId 中加入工作流程 ID。每次通話都會手動執行工作流程。

執行的版本：如果工作流程已發布，呼叫會執行已發布的版本。在 Workflow Builder 中儲存但尚未發布的變更，要等到發布後才會影響 API 呼叫端。如果工作流程從未發布，呼叫會執行草稿。
誰可以呼叫：工作流程的擁有者和管理員可以呼叫。其他使用者在您與他們共用已發布的工作流程後，即可呼叫該工作流程。只有擁有者或管理員可以呼叫從未發布的工作流程，其他呼叫者會收到 HTTP 403。
觸發條件：工作流程只能有一個手動觸發條件。如果工作流程結合手動觸發程序與任何其他觸發程序，或有多個手動觸發程序，就會導致呼叫失敗。
輸入：您無法透過 streamAssist 設定手動觸發條件的輸入變數。如果手動觸發條件有必要輸入內容，即使輸入內容有預設值，執行作業仍會失敗。選填輸入內容為空白，且未套用預設值。查詢文字會傳遞至工作流程的 LLM 節點，因此您可以在該處加入資料，但不會填入輸入變數。

限制

使用 streamAssist 呼叫代理時，有下列限制：

不支援的代理類型：透過 streamAssist 不支援註冊至 Gemini Enterprise 應用程式的 A2A 或 ADK 代理。如要使用 A2A 代理的註冊端點直接呼叫該代理，請參閱「使用註冊 A2A 端點呼叫代理」。
可變更動作：streamAssist API 經過最佳化，可透過連接器處理對話式查詢和唯讀檢索。streamAssist 不支援透過程式輔助方式執行會造成變更的工具和動作，例如撰寫電子郵件、建立日曆活動或傳送即時通訊訊息。嘗試叫用 Agentic Workflows，可能會導致無訊息失敗或無依據的執行迴圈。

疑難排解

請參閱下表，排解常見的 streamAssist 呼叫錯誤：

問題	可能原因	解析度
列出代理程式時出現 HTTP 404	在 `v1` 或 `v1beta` 端點上呼叫 `agents`。	改為將清單要求傳送至 `v1alpha` 端點。
即使設定 `agentsSpec`，回覆仍顯得籠統	數字 `agentId` 無效，或查詢過於籠統，無法觸發網域行為。	從 `v1alpha` 代理清單確認確切的數字 ID、傳送特定領域的查詢，以及檢查回覆文字是否包含代理專屬用詞。
未傳回任何錯誤，但目標代理程式未執行	`agentId` 格式錯誤，因此自動改用預設自動調度管理。	確認`agentId`僅由數字組成，且與註冊資料庫清單中的 ID 完全相符。
回應狀態會傳回 `SKIPPED`	輸入內容評估結果為非尋求協助的查詢 (例如簡短的問候語)。	傳送實質工作查詢；檢查回應酬載中的 `assistSkippedReasons`。
`HTTP 401`或`HTTP 403 Permission Denied`	缺少 OAuth 範圍、IAM 角色不足，或缺少配額專案標頭。	確認呼叫者有 `discoveryengine.assistants.assist`；確保 OAuth 範圍包含 `cloud-platform`；如果使用 ADC，請新增 `-H "X-Goog-User-Project: PROJECT_ID"`。
`HTTP 403Only the agent owner or an admin can run a draft of this agent.`	工作流程從未發布，且呼叫者不是擁有者或管理員。	在 Workflow Builder 中發布工作流程，並與來電者共用。
`HTTP 403User does not have permission to access the Agent.`	工作流程不會與來電者共用。	與來電者共用工作流程。
工作流程的運作方式與舊版本相同	系統會執行已發布的版本，而不是 Workflow Builder 中未發布的變更。	發布工作流程。
工作流程呼叫以 `answer.state` `FAILED` 和 `INTERNAL` 錯誤結束	工作流程有一個手動觸發條件和另一個觸發條件，或多個手動觸發條件。	保留單一手動觸發條件。