使用 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 代理與標準 Gemini 模型，涵蓋多項指標，包括延遲時間、輸出內容和各自最適合的用途：

主要功能

Deep Research 具備下列功能和特色：

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

如何使用 Deep Research

您可以使用 Google Gen AI SDK 或直接傳送 REST API 要求，透過全域端點 (v1beta1) 存取 Gemini Deep Research 代理。如需使用範例，請參閱 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 Gemini Enterprise 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
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 Gemini Enterprise 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

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 工作

研究工作涉及反覆搜尋和閱讀，可能需要幾分鐘才能完成。您必須將 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。

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)
      

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 會先重播工作階段開始後的所有過去事件，再繼續即時更新。

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
)

以企業適用的網路內容建立基準

Web Grounding for Enterprise 可讓組織以安全、符合法規且最新的網路資料，做為生成式 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

要求主體參數

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

逾時和錯誤處理

與代理互動時，可能會遇到連線逾時或系統錯誤。本節說明如何找出及解決虛逾時和硬失敗。

虛逾時

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

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

嚴重故障

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

如要解決這個問題，請停止目前的工作階段，並在開始新的工作階段前，先調整查詢。

最佳做法

如果授予自主代理存取網路和檔案的權限，會產生獨特的動態。實作專案時，請考量下列最佳做法：

• 提示未知資訊：明確指示代理如何處理缺少的資料。例如，指示模型在無法取得數據時，應直接說明，而非估算。

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

• 避免資料竊取：如果要求代理摘要機密內部資料，同時允許代理瀏覽公開網路，請務必格外謹慎。

• 驗證引用資料：雖然系統會套用企業級篩選機制，但仍請務必驗證回覆中提供的引用資料，確保網路來源可靠。

限制

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

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

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

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

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

定價

Deep Research 運用 Gemini 的進階推論功能，執行多步驟代理研究工作。計費項目包括模型用量 (權杖) 和工具執行 (搜尋和建立基準)。

如果是背景工作，可以使用延遲層級，享有折扣。

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

費用追蹤

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

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

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

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

配額

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

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

1. 在 Google Cloud 控制台，前往「Quotas & system limits」(配額與系統限制) 頁面。

   前往「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 搜尋建立基準」功能，則無法停用這項資訊的儲存功能。如果需要零資料保留，建議使用企業版網路基準建立。

快取

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

安全性控管

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

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

後續步驟