L'agente Gemini Deep Research è un agente AI gestito progettato per pianificare, eseguire e sintetizzare workflow di ricerca complessi e in più passaggi. Basato su Gemini, l'agente naviga in diversi paesaggi 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 illustra 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 workflow metodico e in più passaggi: Pianifica > 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 l'analisi della concorrenza.
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 raffinati: 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 generati 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 seguente tabella confronta l'agente Gemini Deep Research con i modelli Gemini standard in base a diverse metriche, tra cui latenza, output e l'utilizzo migliore di ciascuno:
| 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à:
- Basato su più fonti, tra cui:
- Server MCP remoti
- Grounding con Agent Search
- Grounding con la Ricerca Google o Web Grounding for Enterprise, che si basano su rigorosi standard di privacy e filtraggio adatti ai carichi di lavoro aziendali
- Caricamenti incorporati 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 la Introduzione al notebook Gemini Deep Research Pro 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 workload.
-
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.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. 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.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. 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.
Devi utilizzare la modalità di esecuzione in background e streaming. Per farlo, imposta i campi background e stream su True nella configurazione della risposta quando esegui l'agente. L'API restituisce immediatamente un oggetto Interaction parziale. Puoi utilizzare la proprietà id per recuperare
un'interazione per il sondaggio. Lo stato dell'interazione passerà da
in_progress a completed o failed.
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=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)
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": true
}'L'API restituisce immediatamente un interaction_id. Questo ID è necessario per
riconnettersi allo stream.
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. Devi impostare 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
era stata 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 interazione
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
|
Ricerca 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 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
)
Sterzabilità 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 e cognome: 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
|
Obbligatorio. Consente lo streaming. Deve essere impostato su true. |
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. |
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 temporanei e gli errori irreversibili.
Timeout flessibili
Un timeout temporaneo si verifica 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 attuale 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 sconosciute: fornisci istruzioni esplicite all'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, in quanto 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 allo stesso tempo di accedere alla navigazione sul web pubblico.
Verifica le 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 disattivata.
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 memorizza 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 svolgere attività di ricerca agentica in più fasi. La fatturazione comprende l'utilizzo del modello (token) e l'esecuzione dello strumento (ricerca e grounding).
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 devi 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). In questo modo, puoi aggregare e calcolare il costo totale dei tuoi 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 progetto Google Cloud .
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 pertinenti per agenti e interazioni.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 tuoi 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 indicato 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 l'API Interactions, che ti consente di interagire con un agente.
Notebook: Introduction to Gemini Deep Research Agent
Inizia a utilizzare questo notebook Python Deep Research su GitHub.