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

如要呼叫特定已註冊的代理程式，請在 streamAssist REST API 要求或用戶端程式庫呼叫中，提供選用的 agentsSpec 欄位。AgentsSpec API 會定義用於處理要求的代理程式規格。Google 助理會直接將查詢轉送給該代理，並在回合之間保留工作階段脈絡。

概覽

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

事前準備

  1. 在 Google Cloud 專案中啟用 Discovery Engine API (discoveryengine.googleapis.com)。
  2. 請確認主體 (使用者帳戶或服務帳戶) 具備授予 discoveryengine.assistants.assist IAM 權限的角色，例如 Discovery Engine 編輯者 (roles/discoveryengine.editor) 或 Gemini Enterprise 管理員 (roles/discoveryengine.agentspaceAdmin)。
  3. 確認您已建立 Gemini Enterprise 應用程式 (引擎)，且其中至少有一個已註冊的代理程式。
  4. 如果您使用應用程式預設憑證 (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)。

如需完整的代理程式資源結構定義，請參閱 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 會自動產生新的獨立工作階段。

限制

透過 streamAssist 呼叫代理程式時，有以下限制：

  • 不支援的代理程式類型：
    • 不支援工作流程代理程式。
    • streamAssist不支援向 Gemini Enterprise 應用程式註冊的 A2A 或 ADK 代理。如要使用註冊端點直接呼叫 A2A 代理，請參閱「使用註冊 A2A 端點呼叫代理」。
  • 變動動作：streamAssist API 經過最佳化，可處理對話式查詢，並透過連接器擷取唯讀資料。系統不支援透過 streamAssist 以程式輔助方式執行變更工具和動作 (例如草擬電子郵件、建立日曆活動或傳送即時通訊訊息)。嘗試叫用會執行變動動作的代理程式工作流程時，可能會導致無聲失敗或無根據的執行迴圈。

疑難排解

請參閱下表，排解常見的 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"。

後續步驟