使用 Gemini Deep Research 代理

Gemini Deep Research 代理是受管理的 AI 代理，可規劃、執行及統整複雜的多步驟研究工作流程。這項代理程式由 Gemini 提供技術支援，可瀏覽各種資訊環境，包括公開網路和私人企業資料，生成詳盡且附有出處的報告，協助您加快做出明智決策。

本頁面說明如何使用 Gemini Deep Research 代理，包括主要功能和限制、如何開始研究任務，以及如何處理逾時和錯誤處理。

使用 Deep Research 的時機

Deep Research 是代理，而不只是模型。最適合採用非同步分析方法的工作負載，而非低延遲的即時通訊。

規劃專案時，請考量 Deep Research 的下列優點：

  • 疊代程序：與標準對話模型不同，Deep Research 不會立即生成回覆，而是會遵循有條不紊的多步驟工作流程：規劃 > 多來源搜尋 > 疊代 > 輸出。

  • 進階工作負載：Deep Research 專為處理複雜工作而設計，例如盡職調查、市場分析和競爭環境。

  • 廣泛的資料基礎：Gemini Deep Research 代理可以同時對各種資料來源進行推論。包括遠端 MCP 伺服器、機構內部知識，以及從上傳的檔案或資料夾取得的直接背景資訊。

  • 精美報表：生成詳盡的報表，並附上出處，還能提供可直接用於簡報的圖片。包括財務圖表、內嵌資訊圖表和市場定位矩陣，這些都是使用 HTML 和圖片模型生成。

  • 高可控性：您可以直接在提示中大幅自訂最終輸出內容。包括設定特定語氣 (例如技術或主管)、定義嚴格格式，或要求結構化資料表。

下表比較 Gemini Deep Research Agent 與標準 Gemini 模型的多項指標，包括延遲時間、輸出內容，以及最適合的用途：

功能 標準 Gemini 模型 Gemini Deep Research 代理
延遲時間 秒 分鐘
程序 生成 → 輸出內容 規劃 → 多來源搜尋 → 反覆運算 → 輸出
輸出內容 對話風格的文字和程式碼 詳細的引用報告，內含內嵌圖表和圖片
最適合用於 聊天機器人、資訊擷取、摘要生成 市場分析、深入研究、競爭環境

主要功能

Deep Research 具備下列功能：

  • 以多個來源為依據，包括：
  • 圖片和圖表輸出內容：生成詳細報表，內含可直接用於簡報的素材資源，例如內嵌資訊圖表、市場定位矩陣圖表和財務成效圖表
  • 內嵌引用資料

如何使用 Deep Research

您可以使用 Google Gen AI SDK 或直接發出 REST API 要求，透過全域端點 (v1beta1) 存取 Gemini Deep Research Agent。如需使用範例，請參閱 GitHub 上的 Gemini Deep Research Agent 筆記本簡介。

事前準備

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. Make sure that you have the following role or roles on the project: roles/aiplatform.user, roles/serviceusage.serviceUsageConsumer

    Check for the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

開始執行 Deep Research 工作

研究工作需要反覆搜尋和閱讀，可能需要幾分鐘才能完成。您必須將 background 設為 True，以非同步方式執行 Gemini Deep Research 代理。

你可以使用 Gemini Deep Research 代理，並選擇是否要串流：

  • 輪詢 (非串流)：設定 background=True (和選用的 stream=False)。 API 會立即傳回 Interaction 物件。您可以使用 id 屬性輪詢互動，直到狀態從 in_progress 轉換為 completed 或 failed 為止。
  • 串流：設定 background=True 和 stream=True，即可在研究進行期間即時接收最新資訊。詳情請參閱「串流」。

您也可以將代理程式設為使用延遲層級，系統會自動在離峰時段排定背景工作，並提供 50% 的折扣。如要使用延遲層級，建立工作時必須將 stream 設為 False。

Python


import time
from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

interaction = client.interactions.create(
  input="Analyze competitive positioning for solar energy providers.",
  agent="deep-research-preview-04-2026",
  background=True,
  stream=False,
  service_tier="deferred"
)

print(f"Research started: {interaction.id}")

while True:
  interaction = client.interactions.get(interaction.id)
  if interaction.status == "completed":
    print(interaction.steps[-1].content[0].text)
    break
  elif interaction.status == "failed":
    print(f"Research failed: {interaction.error}")
    break
  time.sleep(10)

REST

PROJECT_ID=PROJECT_ID;
curl --max-time 3600 --keepalive-time 10 -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions" \
    -d '{
      "input": "Research the history of Google TPUs.",
      "agent": "deep-research-preview-04-2026",
      "background": true,
      "stream": false,
      "service_tier": "deferred"
    }'

API 會立即傳回 interaction_id。您可以使用這個 ID 輪詢狀態或重新連線至串流。

串流

「Deep Research」支援串流功能，可即時接收研究進度更新，包括想法摘要、文字輸出內容和生成的圖片。使用串流時，請設定 background=True 和 stream=True。

以下範例會啟動研究工作，並處理自動重新連線的串流。它會追蹤 interaction_id 和 last_event_id，因此連線中斷時，可以從中斷處繼續。


from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

interaction_id = None
last_event_id = None
is_complete = False

def process_stream(stream):
  global interaction_id, last_event_id, is_complete
  for event in stream:
    if event.event_type == "interaction.created":
      interaction_id = event.interaction.id
    if event.event_id:
      last_event_id = event.event_id
    if event.event_type == "step.delta":
      if event.delta.type == "text":
        print(event.delta.text, end="", flush=True)
      elif event.delta.type == "thought":
        print(f"Thought: {event.delta.text}", flush=True)
    elif event.event_type in ("interaction.completed", "error"):
      is_complete = True

stream = client.interactions.create(
  input="Research the history of Google TPUs.",
  agent="deep-research-preview-04-2026",
  background=True,
  stream=True,
  agent_config={"type": "deep-research", "thinking_summaries": "auto"},
)

process_stream(stream)

while not is_complete and interaction_id:
  status = client.interactions.get(interaction_id)
  if status.status != "in_progress":
    break
  stream = client.interactions.get(
    id=interaction_id, stream=True, last_event_id=last_event_id,
  )
  process_stream(stream)

重新連線至互動串流

如要復原已捨棄的串流，請使用原始 interaction_id 提交 GET 要求。API 會從工作階段開始時重播所有過去的事件，然後繼續提供即時更新。

Python


response = client.interactions.get(
  id = 'INTERACTION_ID',
  stream=True
)
for chunk in response:
  print(chunk)

REST

PROJECT_ID=PROJECT_ID;
INTERACTION_ID=INTERACTION_ID

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/interactions/${INTERACTION_ID}"

工具

Deep Research 支援多種內建和外部工具。 根據預設 (未提供工具參數時)，代理程式可存取 Google 搜尋和網址背景資訊。您可以明確指定工具，限制或擴展代理的功能。支援的工具包括：

工具 鍵 注意事項
Google 搜尋 google_search 搜尋公開網路。 (預設為啟用)。
MCP 伺服器 mcp_server 連線至遠端 MCP 伺服器，存取外部工具。
企業網頁搜尋 enterprise_web_search 透過額外的法規遵循控制項進行網頁搜尋。
Agent Search vertex_ai_search 搜尋網站資料或文件集。

以下程式碼會啟用 Google 搜尋，並停用其他工具：


interaction = client.interactions.create(
  agent="deep-research-preview-04-2026",
  input="What are the latest developments in quantum computing?",
  tools=[{"type": "google_search"}],
  background=True,
  stream=True
)

MCP 伺服器

在工具設定中提供伺服器名稱和網址。您也可以傳遞驗證憑證，並限制代理程式可呼叫的工具。

請參閱下列參考資料：

欄位 類型 必填 說明
type 字串 是 必須為 "mcp_server"。
name 字串 否 MCP 伺服器的顯示名稱。
url 字串 否 MCP 伺服器端點的完整網址。
headers 物件 否 以 HTTP 標頭形式傳送的鍵/值組合，每次向伺服器發出要求時都會傳送 (例如驗證權杖)。
allowed_tools 陣列 否 限制代理程式可呼叫伺服器中的哪些工具。

請參閱以下範例：


interaction = client.interactions.create(
  agent="deep-research-preview-04-2026",
  input="How to deploy an app to Cloud Run on Google Cloud?",
  tools=[
    {
      "type": "mcp_server",
      "name": "Google Cloud Developer Knowledge",
      "url": "https://developerknowledge.googleapis.com/mcp",
      "headers": {"Authorization": "Bearer token"},
    }
  ],
  background=True,
  stream=True
)

企業網頁搜尋功能可讓機構以安全、符合法規且最新的網路資料為基準，生成式 AI 回覆。開發人員和商家可透過這項功能將 AI 模型連上網際網路，同時確保資料隱私權或法規遵循。

請參閱以下範例：


interaction = client.interactions.create(
  agent="deep-research-preview-04-2026",
  input="Research on the latest trend on AI",
  tools=[
    {
      "type": "google_search",
      "search_type": ["enterprise_web_search"],
    }
  ],
  background=True,
  stream=True
)

多模態輸入內容

Deep Research 支援多模態輸入，包括圖片和文件 (PDF)，可讓代理程式分析視覺內容，並根據提供的輸入內容進行網路研究。

請參閱以下範例：


prompt = """
Analyze the interspecies dynamics and behavioral risks present
in the provided image of the African watering hole. Specifically, investigate
the symbiotic relationship between the avian species and the pachyderms
shown, and conduct a risk assessment for the reticulated giraffes based on
their drinking posture relative to the specific predator visible in the
foreground.
"""

interaction = client.interactions.create(
  input=[
    {"type": "text", "text": prompt},
    {
      "type": "image",
      "uri": "https://storage.googleapis.com/generativeai-downloads/images/generated_elephants_giraffes_zebras_sunset.jpg"
    }
  ],
  agent="deep-research-preview-04-2026",
  background=True,
  stream=True
)

print(f"Research started: {interaction.id}")

while True:
  interaction = client.interactions.get(interaction.id)
  if interaction.status == "completed":
    print(interaction.steps[-1].content[0].text)
    break
  elif interaction.status == "failed":
    print(f"Research failed: {interaction.error}")
    break
  time.sleep(10)

文件解讀

您可以直接將文件做為多模態輸入內容傳遞。代理程式會分析提供的文件，並根據文件內容進行研究。

請參閱以下範例：


interaction = client.interactions.create(
  agent="deep-research-preview-04-2026",
  input=[
    {"type": "text", "text": "What is this document about?"},
    {
      "type": "document",
      "uri": "https://arxiv.org/pdf/1706.03762",
      "mime_type": "application/pdf",
    },
  ],
  background=True,
  stream=True
)

可控性和格式

在提示中提供特定格式設定指令，即可引導代理程式輸出內容。您可以將報表劃分為特定章節和子章節、加入資料表，或針對不同目標對象調整語氣，例如「技術」、「高階主管」或「休閒」。

在輸入文字中明確定義輸出內容。請參閱以下範例：


prompt = """
Research the competitive landscape of EV batteries.

Format the output as a technical report with the following structure:
1. Executive Summary
2. Key Players (Must include a data table comparing capacity and chemistry)
3. Supply Chain Risks
"""

interaction = client.interactions.create(
    input=prompt,
    agent="deep-research-preview-04-2026",
    background=True,
    stream=True
)

API 參考資料

本節提供使用 Gemini Deep Research 代理的 API 參考資料。

詳情請參閱「Interactions API」。

方法：interactions.create

全名： projects.locations.interactions.create

發起新的 Deep Research 工作階段。

端點

post https://aiplatform.googleapis.com/v1beta1/{parent}/interactions

要求主體參數

要求主體參數可包含下列項目：

參數 類型 說明
agent string 這是必要旗標，指定代理程式 ID 代碼 (例如 deep-research-preview-04-2026)。
background boolean 這是必要旗標，以非同步方式執行互動。 必須設為 true。
stream boolean 選用。啟用串流功能。預設值為 false。
input array 或 string 這是必要旗標，內含使用者輸入內容的清單。僅支援單一物件。
tools array 覆寫預設工具。支援 google_search、external_data_mcp、vertex_search 等。
service_tier string 設為 deferred 即可使用延遲層級，系統會自動在離峰時段安排背景工作。

逾時和錯誤處理

與服務專員互動時，可能會發生連線逾時或系統錯誤。本節說明如何找出並解決軟性逾時和硬性失敗問題。

虛逾時

如果代理程式仍在處理要求，但 Interactions API 連線中斷，就會發生軟性逾時。代理會在背景繼續執行要求。

如要繼續工作階段並查看重播的事件，請使用 interaction_id 重新連線至串流。請參閱「重新連線至互動串流」。

硬體故障

如果代理程式或內部系統發生錯誤，導致代理程式脈絡完全終止，就會發生嚴重失敗。這類錯誤通常會傳回 HTTP 500 狀態碼。常見原因包括超過 120 分鐘的執行時間限制，或發生系統故障。

如要解決這項問題，請停止目前的工作階段，並在開始新的工作階段前修正查詢。

最佳做法

讓自主代理程式存取網路和檔案，會產生獨特的動態效果。實作專案時，請考慮下列最佳做法：

  • 提示未知內容：明確指示代理如何處理遺漏資料。舉例來說，請模型說明數據是否無法取得，而非估算數據。

  • 避免提示詞注入風險：請確保上傳的檔案來自可信來源，因為惡意檔案可能含有隱藏的文字，意圖操縱代理程式的輸出內容。

  • 避免資料外洩：要求代理程式摘要說明敏感內部資料，同時允許代理程式瀏覽公開網路時，請務必格外謹慎。

  • 驗證引用內容：雖然系統會套用企業級篩選功能，但請務必驗證回應中提供的引用內容，確保網路來源信譽良好。

限制

規劃專案時，請注意下列限制：

  • 僅支援單輪對話：僅支援單輪查詢。不支援使用 API 的 previous_interaction_id 欄位。

  • 企業級安全性：在預先發布階段，系統不支援客戶自行管理的加密金鑰 (CMEK) 和 VPC Service Controls。多區域資料落地限制正在評估中。

  • 快取：這項服務預設會啟用隱含快取。 無法關閉。

  • 資料保留：提示和生成的輸出內容會保留七天，以供標準處理。使用「以 Google 搜尋強化事實基礎」時，Google 會將提示、脈絡資訊和生成的輸出內容儲存三天，以利偵錯和測試。如果您使用「以 Google 搜尋強化事實基礎」，就無法關閉這項資訊的儲存功能。如需零資料保留，建議使用「以 Enterprise Web Search 建立基準」。

定價

Deep Research 會使用 Gemini 的進階推論功能，執行多步驟的代理研究工作。帳單包含模型用量 (權杖) 和工具執行次數 (搜尋和基本事實檢查)。

如為背景工作，您可以使用延遲層級，享有折扣優惠。

詳情請參閱這篇文章，瞭解定價相關資訊。

追蹤費用

根據預設，Gemini Deep Research Agent 會自動將is_deep_research使用者標籤套用至作業。在 Cloud de Confiance by S3NS中，標籤是輕量型的鍵/值組合，可用於整理資源，以及追蹤基礎架構的費用。

  • 自動標籤：您不需要在 API 要求中手動設定這個標籤，代理程式預設會為所有執行的工作加入 is_deep_research 標籤。

  • 帳單篩選：您可以使用 is_deep_research 帳單標籤，篩選 Deep Research 帳單報表。

  • 全面追蹤：is_deep_research帳單標籤適用於模型用量 (輸入和輸出權杖) 和工具執行 (搜尋和基礎用量)。這有助於彙整及計算非同步研究工作流程的總成本。

配額

如要因應更高的流量、並行背景工作或更繁重的研究負載，可以直接在 Cloud de Confiance 專案中申請提高 Agent Platform API 配額。

如要提高配額，請按照下列步驟操作：

  1. 在 Cloud de Confiance 控制台，前往「配額與系統限制」頁面。

    前往「Quotas and system limits」(配額與系統限制) 頁面

  2. 請確認您選取的專案是執行 Deep Research 工作負載的專案。

  3. 在篩選器搜尋框中，搜尋「Agent Platform API」(aiplatform.googleapis.com)，找出相關的代理程式和互動配額。

  4. 選取要調整的特定配額限制。

  5. 按一下 [編輯配額]。

  6. 在「Quota changes」(配額變更) 對話方塊的「New value」(新值) 欄位中，輸入要求的限制。在要求說明中提供明確的理由。 說明具體的 Deep Research 用途、背景執行需求和預期流量模式，有助於加快核准程序。

  7. 按一下 [提交要求]。

法規遵循與安全性

本節說明資料的保留和快取方式，並列出在預覽期間不支援的安全控制項。

資料保留

系統會將提示和生成的輸出內容儲存七 (7) 天，以進行標準處理。

如服務專屬條款第 19 節「生成式 AI 服務：以 Google 搜尋強化事實基礎」所述，Google 會儲存顧客提供的提示詞和脈絡資訊，以及生成的輸出內容，為期三 (3) 天，以便建立以 Google 搜尋強化事實基礎的結果和搜尋建議。儲存的資訊可能會用於偵錯和測試支援以 Google 搜尋強化事實基礎的系統。如果您使用 Google 搜尋的 Grounding 功能，就無法停用這項資訊的儲存作業。如果您需要零資料保留，建議使用企業版網頁基礎。

快取

隱含快取 預設為啟用 Deep Research，且無法關閉。

安全性控管

預先發布版不支援下列安全控制項：

  • 客戶自行管理的加密金鑰 (CMEK)
  • VPC Service Controls (VPC-SC)
  • 資料存取透明化控管機制 (AXT)
  • 資料落地設定
  • 多區域資料落地

後續步驟

參考資料

瞭解 Interactions API，與代理互動。

教學課程

如要開始使用，請前往 GitHub 查看這份 Deep Research Python 筆記本。