L'agente Gemini Deep Research è un agente AI gestito progettato per pianificare, eseguire e sintetizzare workflow di ricerca complessi e articolati in più fasi. Basato su Gemini, l'agente naviga in diversi scenari informativi, tra cui il web pubblico e i dati aziendali privati, per generare report completi e citati che accelerano il processo decisionale informato.
Questa pagina descrive come utilizzare l'agente Gemini Deep Research, incluse le sue funzionalità e limitazioni principali, come avviare un'attività di ricerca e come gestire i timeout e la gestione degli errori.
Quando utilizzare Deep Research
Deep Research è un agente, non solo un modello. È più adatta ai workload che consentono un approccio di analisi asincrono anziché una chat a bassa latenza.
Quando pianifichi il tuo progetto, tieni presente i seguenti punti di forza di Deep Research:
Processo iterativo: anziché generare risposte istantanee come i modelli di chat standard, Deep Research segue un flusso di lavoro metodico e in più passaggi: Pianificazione > Ricerca multiorigine > Iterazione > Output.
Carichi di lavoro avanzati: Deep Research è progettato specificamente per gestire attività complesse come la due diligence, l'analisi di mercato e il panorama competitivo.
Ampia base di dati: l'agente Gemini Deep Research può ragionare su varie origini dati contemporaneamente. Ciò include server MCP remoti, conoscenze istituzionali interne e contesto diretto da file o cartelle caricati.
Report curati: produce report completi e citati che possono includere immagini pronte per la presentazione. Questi includono grafici finanziari, infografiche in linea e matrici di posizionamento sul mercato, che vengono generate utilizzando HTML e un modello di immagine.
Elevata manovrabilità: puoi personalizzare notevolmente l'output finale direttamente nel prompt. Ciò include l'impostazione di un tono specifico (ad esempio, tecnico o esecutivo), la definizione di formati rigidi o la richiesta di tabelle di dati strutturati.
La tabella seguente confronta l'agente Gemini Deep Research con i modelli Gemini standard in base a diverse metriche, tra cui latenza, output e l'utilizzo migliore per ciascun modello:
| Funzionalità | Modelli Gemini standard | Agente Gemini Deep Research |
|---|---|---|
| Latenza | Secondi | Minuti |
| Processo | Genera → Output | Pianifica → Ricerca multi-origine → Itera → Output |
| Output | Testo e codice in stile conversazionale | Report dettagliati e citati con grafici e immagini in linea |
| Ideale per | Chatbot, estrazione di informazioni, riepilogo | Analisi di mercato, ricerca approfondita, panorama competitivo |
Funzionalità chiave
Deep Research offre le seguenti funzionalità e capacità:
- Basarsi su più fonti, tra cui:
- Server MCP remoti
- Grounding con Agent Search
- Grounding con la Ricerca Google o Grounding web per l'enterprise, che sono supportati da rigorosi standard di privacy e filtraggio adatti ai carichi di lavoro aziendali
- Caricamenti in linea di file e cartelle (ad esempio PDF e fogli di lavoro), che ti consentono di inserire il contesto direttamente nel flusso di lavoro di ricerca e ottenere citazioni
- Output di immagini e grafici: genera report dettagliati contenenti asset pronti per la presentazione, come infografiche in linea, grafici a matrice di posizionamento sul mercato e grafici del rendimento finanziario
- Citazioni in linea
Come usare Deep Research
Puoi accedere all'agente Gemini Deep Research utilizzando l'endpoint globale (v1beta1) utilizzando l'SDK Google Gen AI o richieste API REST dirette. Per un esempio di utilizzo, consulta il notebook Introduzione all'agente Gemini Deep Research su GitHub.
Prima di iniziare
- Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.-
Make sure that you have the following role or roles on the project: roles/aiplatform.user, roles/serviceusage.serviceUsageConsumer
Check for the roles
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
-
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.
- 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
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
- Click Grant access.
-
In the New principals field, enter your user identifier. This is typically the email address for a Google Account.
- Click Select a role, then search for the role.
- To grant additional roles, click Add another role and add each additional role.
- 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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.-
Make sure that you have the following role or roles on the project: roles/aiplatform.user, roles/serviceusage.serviceUsageConsumer
Check for the roles
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
-
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.
- 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
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
- Click Grant access.
-
In the New principals field, enter your user identifier. This is typically the email address for a Google Account.
- Click Select a role, then search for the role.
- To grant additional roles, click Add another role and add each additional role.
- Click Save.
-
Avviare un'attività di Deep Research
Le attività di ricerca comportano la ricerca e la lettura iterative e possono richiedere diversi minuti per essere completate. Devi eseguire l'agente Gemini Deep Research in modo asincrono impostando
background su True.
Puoi utilizzare l'agente Gemini Deep Research con o senza streaming:
- Polling (non in streaming): imposta
background=True(e facoltativamentestream=False). L'API restituisce immediatamente un oggettoInteraction. Puoi utilizzare la proprietàidper eseguire il polling dell'interazione finché lo stato non passa dain_progressacompletedofailed. - Streaming: imposta
background=Trueestream=Trueper ricevere aggiornamenti in tempo reale man mano che la ricerca procede. Per saperne di più, consulta Streaming.
Puoi anche configurare l'agente in modo che utilizzi il livello
differito,
che pianifica automaticamente i job in background per le ore non di punta a una tariffa scontata del 50%. Per utilizzare il livello differito, stream deve essere impostato su False durante la creazione dell'attività.
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"
}'L'API restituisce immediatamente un interaction_id. Puoi utilizzare questo ID per eseguire il polling
dello stato o riconnetterti a un flusso.
Streaming
Deep Research supporta lo streaming per ricevere aggiornamenti in tempo reale
sui progressi della ricerca, inclusi riepiloghi dei pensieri, output di testo e
immagini generate. Quando utilizzi lo streaming, imposta background=True e stream=True.
L'esempio seguente avvia un'attività di ricerca ed elabora lo stream
con la riconnessione automatica. Traccia interaction_id e
last_event_id in modo che, se la connessione si interrompe, possa riprendere da dove
si era interrotta.
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)
Riconnettiti al flusso di interazioni
Per recuperare un flusso interrotto, invia una richiesta GET utilizzando l'interaction_id originale. L'API riprodurrà tutti gli eventi passati dall'inizio della
sessione prima di continuare con gli aggiornamenti in tempo reale.
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}"Strumenti
Deep Research supporta più strumenti integrati ed esterni. Per impostazione predefinita (quando non viene fornito alcun parametro tools), l'agente ha accesso a Ricerca Google e Contesto URL. Puoi specificare esplicitamente gli strumenti per limitare o estendere le funzionalità dell'agente. Gli strumenti supportati includono:
| Strumento | Chiave | Nota |
|---|---|---|
| Ricerca Google | google_search
|
Cercare sul web pubblico. Abilitato per impostazione predefinita. |
| Server MCP | mcp_server
|
Connettiti ai server MCP remoti per l'accesso a strumenti esterni. |
| Ricerca web enterprise | enterprise_web_search
|
Ricerca web con controlli di conformità aggiuntivi. |
| Agent Search | vertex_ai_search
|
Cerca nei dati del tuo sito web o nei tuoi set di documenti. |
Ricerca Google
Quanto segue consente di utilizzare la Ricerca Google come unico strumento:
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
)
Server MCP
Fornisci il nome e l'URL del server nella configurazione degli strumenti. Puoi anche trasmettere le credenziali di autenticazione e limitare gli strumenti che l'agente può chiamare.
Consulta il seguente riferimento:
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
type |
string | Sì | Deve essere "mcp_server". |
name |
string | No | Un nome visualizzato per il server MCP. |
url
|
string | No | L'URL completo dell'endpoint del server MCP. |
headers
|
oggetto | No | Coppie chiave-valore inviate come intestazioni HTTP con ogni richiesta al server (ad esempio, token di autenticazione). |
allowed_tools
|
matrice | No | Limita gli strumenti del server che l'agente può chiamare. |
Vedi il seguente esempio:
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
)
Ricerca web enterprise
La ricerca web aziendale consente alle organizzazioni di basare le risposte dell'AI generativa su dati web sicuri, conformi e aggiornati. Consente a sviluppatori e aziende di connettere i modelli di AI a internet senza compromettere la privacy dei dati o la conformità legale.
Vedi il seguente esempio:
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
)
Input multimodali
Deep Research supporta input multimodali, tra cui immagini e documenti (PDF), consentendo all'agente di analizzare i contenuti visivi e condurre ricerche basate sul web contestualizzate dagli input forniti.
Vedi il seguente esempio:
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)
Document understanding
Puoi passare i documenti direttamente come input multimodale. L'agente analizza i documenti forniti e conduce ricerche basate sui loro contenuti.
Vedi il seguente esempio:
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
)
Controllabilità e formattazione
Puoi indirizzare l'output dell'agente fornendo istruzioni di formattazione specifiche nel prompt. In questo modo puoi strutturare i report in sezioni e sottosezioni specifiche, includere tabelle di dati o modificare il tono per diversi segmenti di pubblico, ad esempio "tecnico", "dirigenziale" o "informale".
Definisci esplicitamente l'output nel testo di input. Vedi il seguente esempio:
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
)
Riferimento API
Questa sezione fornisce informazioni di riferimento sull'API per l'utilizzo dell'agente Gemini Deep Research.
Per saperne di più, consulta l'API Interactions.
Metodo: interactions.create
Nome completo: projects.locations.interactions.create
Avvia una nuova sessione di Deep Research.
Endpoint
post
https:
Parametri del corpo della richiesta
I parametri del corpo della richiesta possono includere quanto segue:
| Parametro | Tipo | Descrizione |
|---|---|---|
agent
|
string
|
Obbligatorio. Specifica il codice ID agente (ad esempio
deep-research-preview-04-2026). |
background
|
boolean
|
Obbligatorio. Esegue l'interazione in modo asincrono.
Deve essere impostato su true. |
stream |
boolean |
Facoltativo. Consente lo streaming. Il valore predefinito è false. |
input
|
array o string
|
Obbligatorio. Un elenco contenente input utente. È supportato un solo oggetto. |
tools
|
array
|
Sostituisce gli strumenti predefiniti. Supporta
google_search, external_data_mcp,
vertex_search e così via. |
service_tier
|
string
|
Imposta deferred per utilizzare il
livello differito,
che pianifica automaticamente i job in background per
le ore non di punta. |
Timeout e gestione degli errori
Quando interagisci con un agente, potresti riscontrare timeout di connessione o errori di sistema. Questa sezione spiega come identificare e risolvere i timeout soft e gli errori irreversibili.
Timeout flessibili
Si verifica un timeout flessibile quando la connessione all'API Interactions viene interrotta mentre l'agente sta ancora elaborando una richiesta. L'agente continua a eseguire la richiesta in background.
Per riprendere la sessione e visualizzare gli eventi riprodotti, riconnettiti allo stream utilizzando
il tuo interaction_id. Consulta la sezione Riconnettersi al flusso di interazione.
Errori permanenti
Un errore irreversibile si verifica quando un errore dell'agente o del sistema interno termina
completamente il contesto dell'agente. Questi errori in genere restituiscono un codice di stato HTTP 500. Le cause comuni includono il superamento del limite di esecuzione di 120 minuti o
un errore di sistema.
Per risolvere questo problema, interrompi la sessione corrente e perfeziona la query prima di avviare una nuova sessione.
Best practice
Concedere a un agente autonomo l'accesso al web e ai tuoi file introduce dinamiche uniche. Quando implementi il tuo progetto, tieni presente le seguenti best practice:
Richiedi informazioni per gli sconosciuti: istruisci esplicitamente l'agente su come gestire i dati mancanti. Ad esempio, chiedi di indicare se una cifra non è disponibile anziché stimarla.
Evita i rischi di prompt injection: assicurati che i file caricati provengano da fonti attendibili, poiché i file dannosi potrebbero contenere testo nascosto progettato per manipolare l'output di un agente.
Evita l'esfiltrazione di dati: fai molta attenzione quando chiedi all'agente di riassumere dati interni sensibili e contemporaneamente di accedere alla navigazione sul web pubblico.
Verifica delle citazioni: anche se viene applicato il filtro di livello aziendale, verifica sempre le citazioni fornite nella risposta per assicurarti che le fonti web siano affidabili.
Limitazioni
Quando pianifichi il progetto, tieni presenti le seguenti limitazioni:
Solo singolo turno: sono supportate solo le query a singolo turno. L'utilizzo del campo
previous_interaction_iddell'API non è supportato.Sicurezza aziendale: durante l'anteprima, le chiavi di crittografia gestite dal cliente (CMEK) e i Controlli di servizio VPC non sono supportati. I vincoli di residenza dei dati multiregionali sono in fase di valutazione.
Memorizzazione nella cache: la memorizzazione nella cache implicita è attivata per impostazione predefinita per questo servizio. Non può essere disattivato.
Conservazione dei dati: i prompt e l'output generato vengono memorizzati per sette giorni per l'elaborazione standard. Quando utilizzi il Grounding con la Ricerca Google, Google archivia i prompt, le informazioni contestuali e l'output generato per tre giorni per il debug e i test. Se utilizzi Grounding con la Ricerca Google, non puoi disattivare l'archiviazione di queste informazioni. Se hai bisogno di una conservazione dei dati pari a zero, ti consigliamo di utilizzare Grounding con la ricerca web aziendale.
Prezzi
Deep Research utilizza le funzionalità di ragionamento avanzato di Gemini per eseguire attività di ricerca agentica in più passaggi. La fatturazione comprende l'utilizzo del modello (token) e l'esecuzione degli strumenti (ricerca e grounding).
Per i job in background, puoi utilizzare il livello differito per ottenere uno sconto.
Per saperne di più, consulta i prezzi.
Monitoraggio dei costi
Per impostazione predefinita, l'agente Gemini Deep Research applica automaticamente l'etichetta utente is_deep_research alle sue operazioni. In Google Cloud, le etichette sono
coppie chiave-valore leggere utilizzate per organizzare le risorse e monitorare i costi
nell'infrastruttura.
Etichettatura automatica: non è necessario configurare manualmente questa etichetta nelle richieste API; l'agente include l'etichetta
is_deep_researchper impostazione predefinita per tutte le attività eseguite.Filtro di fatturazione: i report di fatturazione di Deep Research sono filtrabili utilizzando l'etichetta di fatturazione
is_deep_research.Monitoraggio completo: l'etichetta di fatturazione
is_deep_researchsi applica sia all'utilizzo del modello (token di input e output) sia all'esecuzione dello strumento (utilizzo della ricerca e del grounding). Ciò ti aiuta ad aggregare e calcolare il costo totale dei flussi di lavoro di ricerca asincroni.
Quota
Per gestire un traffico più elevato, attività in background simultanee o carichi di ricerca più pesanti, puoi richiedere un aumento della quota per l'API Agent Platform direttamente nel tuo Google Cloud progetto.
Per aumentare la quota:
Nella console Google Cloud , vai alla pagina Quote e limiti di sistema.
Assicurati di aver selezionato il progetto corretto che esegue i tuoi carichi di lavoro di Deep Research.
Nella casella di ricerca dei filtri, cerca API Agent Platform (
aiplatform.googleapis.com) per trovare le quote di agenti e interazioni pertinenti.Seleziona il limite di quota specifico che devi modificare.
Fai clic su Modifica quote.
Nella finestra di dialogo Modifiche alla quota, inserisci il limite richiesto nel campo Nuovo valore. Fornisci una motivazione chiara nella descrizione della richiesta. Se menzioni il tuo caso d'uso specifico di Deep Research, le esigenze di esecuzione in background e i pattern di traffico previsti, puoi contribuire ad accelerare la procedura di approvazione.
Fai clic su Invia richiesta.
Sicurezza e conformità
Questa sezione spiega come vengono conservati e memorizzati nella cache i dati ed elenca i controlli di sicurezza non supportati durante l'anteprima.
Conservazione dei dati
I prompt e l'output generato vengono archiviati per sette (7) giorni per l'elaborazione standard.
Come descritto nella Sezione 19 "Servizi di AI generativa: fondatezza con la Ricerca Google" dei Termini specifici dei servizi, Google memorizza i prompt e le informazioni contestuali che i clienti possono fornire, nonché l'output generato per tre (3) giorni allo scopo di creare risultati fondati e suggerimenti di ricerca. Queste informazioni memorizzate possono essere utilizzate per il debug e il test dei sistemi che supportano la fondatezza con la Ricerca Google. Non è possibile disattivare l'archiviazione di queste informazioni se utilizzi Grounding con la Ricerca Google. Se non vuoi conservare i dati, ti consigliamo di utilizzare Web Grounding for Enterprise.
Memorizzazione nella cache
La memorizzazione implicita nella cache è abilitata per impostazione predefinita per Deep Research e non può essere disattivata.
Controlli di sicurezza
I seguenti controlli di sicurezza non sono supportati durante l'anteprima:
- Chiavi di crittografia gestite dal cliente (CMEK)
- Controlli di servizio VPC (VPC-SC)
- Access Transparency (AXT)
- Residenza dei dati
- Residenza dei dati multiregionale
Passaggi successivi
Riferimento API Interactions
Scopri di più sull'API Interactions, che ti consente di interagire con un agente.
Notebook: Introduction to Gemini Deep Research Agent
Inizia a utilizzare questo notebook Python di Deep Research su GitHub.