Utilizzare l'agente Deep Research di Gemini

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:
  • 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

  1. 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.
  2. 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

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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 the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. 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 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 another role and add each additional role.
    7. Click Save.
  6. 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

  7. Verify that billing is enabled for your Google Cloud project.

  8. 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 the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  9. 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 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 another role and add each additional role.
    7. 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.

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 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
)

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://aiplatform.googleapis.com/v1beta1/{parent}/interactions

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_id dell'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_research per 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_research si 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:

  1. Nella console Google Cloud , vai alla pagina Quote e limiti di sistema.

    Vai a Quote e limiti di sistema

  2. Assicurati di aver selezionato il progetto corretto che esegue i tuoi carichi di lavoro di Deep Research.

  3. Nella casella di ricerca dei filtri, cerca API Agent Platform (aiplatform.googleapis.com) per trovare le quote pertinenti per agenti e interazioni.

  4. Seleziona il limite di quota specifico che devi modificare.

  5. Fai clic su Modifica quote.

  6. 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.

  7. 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

Scopri l'API Interactions, che ti consente di interagire con un agente.

Tutorial

Inizia a utilizzare questo notebook Python Deep Research su GitHub.