使用 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 模型在多項指標上的差異，包括延遲時間、輸出內容，以及最適合的用途：

主要功能

Deep Research 具備下列功能：

• 根據多個來源，包括：
  • 遠端 MCP 伺服器
  • 以 Agent Search 建立基準
  • 以 Google 搜尋強化事實基礎 或 Web Grounding for Enterprise， 這兩項功能都採用嚴格的隱私權和篩選標準，適合企業工作負載
  • 內嵌上傳檔案和資料夾 (例如 PDF 和試算表)，可直接將背景資訊帶入研究工作流程，並取得引文
• 圖片和圖表輸出內容：生成詳細報表，內含可直接用於簡報的素材資源，例如內嵌資訊圖表、市場定位矩陣圖表和財務成效圖表
• 內嵌引用資料

如何使用 Deep Research

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

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。
In the Google Cloud console, on the project selector page, select or create a Google Cloud 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
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API.
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
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 Google Cloud 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 Google Cloud console, go to the IAM page.

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

4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

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

In the Google Cloud console, on the project selector page, select or create a Google Cloud 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

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform API.

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

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 Google Cloud 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 Google Cloud console, go to the IAM page.

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

4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.

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

開始執行 Deep Research 工作

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

您必須使用背景執行和串流模式。如要這麼做，請在執行代理時，將回應設定中的 background 和 stream 欄位設為 True。API 會立即傳回部分 Interaction 物件。您可以使用 id 屬性擷取意見調查的互動。互動狀態會從 in_progress 轉換為 completed 或 failed。

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
)

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)
      

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": true
    }'

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 會從工作階段開始時重播所有過往事件，然後繼續提供即時更新。

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

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 搜尋工具，請執行下列操作：

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 伺服器

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

請參閱以下參考資料：

請參閱以下範例：

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 參考資料

本節提供 API 參考資料，說明如何使用 Gemini Deep Research 代理。

詳情請參閱「Interactions API」。

方法：interactions.create

全名： projects.locations.interactions.create

發起新的「Deep Research」工作階段。

端點

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

要求主體參數

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

逾時和錯誤處理

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

軟性逾時

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

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

硬體故障

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

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

最佳做法

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

• 提示未知內容：明確指示代理如何處理遺漏資料。舉例來說，你可以要求系統說明數據是否無法取得，而不是估算數據。

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

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

• 查證引用資訊：套用企業級篩選功能後，請務必查證回覆中提供的引用資訊，確保網路來源信譽良好。

限制

規劃專案時，請考量下列限制：

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

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

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

• 資料保留：系統會將提示和生成的輸出內容儲存七天，以進行標準處理。使用「以 Google 搜尋強化事實基礎」時，Google 會將提示詞、情境資訊和生成的輸出內容儲存三天，以利進行偵錯和測試。如果使用「以 Google 搜尋強化事實基礎」，就無法關閉這類資訊的儲存功能。如果您需要零資料保留，建議使用「以企業網路搜尋為基礎」。

定價

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

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

追蹤費用

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

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

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

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

配額

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

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

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

   前往「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 會儲存顧客提供的提示詞和脈絡資訊，以及生成輸出內容三天，以便建立以 Google 搜尋強化事實基礎的結果和搜尋建議。儲存的資訊可能會用於系統的偵錯和測試，以支援以 Google 搜尋強化事實基礎。如果您使用 Google 搜尋的基礎模型，就無法停用這項資訊的儲存功能。如果需要零資料保留，建議使用企業版網頁基礎。

快取

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

安全性控管

預先發布版不支援下列安全控管措施：

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

後續步驟