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 articolati in più fasi. Basato su Gemini, l'agente naviga in diversi ambienti di informazioni, tra cui il web pubblico e i dati aziendali privati, per generare report completi e citati che accelerano il processo decisionale informato.

Questa pagina spiega 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ù adatto per i 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 da più fonti > Iterazione > Output.

• Workload avanzati: Deep Research è progettato specificamente per gestire attività complesse come due diligence, analisi dei dati di mercato e analisi della concorrenza.

• Grounding dei dati esteso: 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 accurati: genera report completi e citati che possono includere immagini pronte per la presentazione. Questi includono grafici finanziari, infografiche incorporate e matrici di posizionamento sul mercato, generati utilizzando HTML e un modello di immagine.

• Elevata controllabilità: 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 rigorosi o la richiesta di tabelle di dati strutturati.

La seguente tabella mette a confronto l'agente Gemini Deep Research con i modelli Gemini standard in base a diverse metriche, tra cui latenza, output e i casi d'uso migliori per ciascuno:

Funzionalità chiave

Deep Research offre le seguenti caratteristiche e funzionalità:

• Grounding su più fonti, tra cui:
  • Server MCP remoti
  • Grounding con Agent Search
  • Grounding con la Ricerca Google o Web Grounding for Enterprise, che sono supportati da rigorosi standard di privacy e filtro adatti ai workload aziendali
  • Caricamenti di file e cartelle in linea (come PDF e fogli di lavoro), che ti consentono di inserire il contesto direttamente nel flusso di lavoro di ricerca e di 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 di performance finanziaria.
• Citazioni in linea

Come usare Deep Research

Puoi accedere all'agente Gemini Deep Research utilizzando l'endpoint globale (v1beta1) tramite 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

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

2. Verify that billing is enabled for your Cloud de Confiance project.

3. Enable the 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

4. 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 Cloud de Confiance 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 Cloud de Confiance 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 identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

   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.

Avvia un'attività di Deep Research

Le attività di ricerca comportano ricerche e letture 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 facoltativamente stream=False). L'API restituisce immediatamente un oggetto Interaction. Puoi utilizzare la proprietà id per eseguire il polling dell'interazione finché lo stato non passa da in_progress a completed o failed.
• Streaming: imposta background=True e stream=True per 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 con una tariffa scontata del 50%. Per utilizzare il livello differito, stream deve essere impostato su False durante la creazione dell'attività.

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

L'API restituisce immediatamente un interaction_id. Puoi utilizzare questo ID per eseguire il polling dello stato o riconnetterti a uno stream.

Streaming

Deep Research supporta lo streaming per ricevere aggiornamenti in tempo reale sull'avanzamento della ricerca, inclusi riepiloghi dei pensieri, output di testo e immagini create dall'AI. Quando utilizzi lo streaming, imposta background=True e stream=True.

L'esempio seguente avvia un'attività di ricerca ed elabora lo stream con riconnessione automatica. Tiene traccia di 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 allo stream di interazione

Per recuperare uno stream 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.

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}"

Strumenti

Deep Research supporta più strumenti integrati ed esterni. Per impostazione predefinita (quando non viene fornito alcun parametro tools), l'agente ha accesso alla Ricerca Google e al contesto dell'URL. Puoi specificare esplicitamente gli strumenti per limitare o estendere le funzionalità dell'agente. Gli strumenti supportati includono:

Ricerca Google

Il seguente esempio abilita 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 passare le credenziali di autenticazione e limitare gli strumenti che l'agente può chiamare.

Consulta il seguente riferimento:

Vedi l'esempio che segue:

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

Enterprise Web Search consente alle organizzazioni di fondare 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 l'esempio che segue:

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 l'esempio che segue:

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 l'esempio che segue:

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", "esecutivo" o "informale".

Definisci l'output in modo esplicito nel testo di input. Vedi l'esempio che segue:

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:

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 flessibili e gli errori irreversibili.

Timeout flessibili

Un timeout flessibile si verifica quando la connessione all'API Interactions si interrompe 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 Riconnettiti allo stream di interazione.

Errori irreversibili

Un errore grave si verifica quando un errore dell'agente o del sistema interno termina completamente il contesto dell'agente. In genere, questi errori 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 errore, 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:

• Prompt per le incognite: indica esplicitamente all'agente come gestire i dati mancanti. Ad esempio, chiedi di indicare se un dato non è disponibile anziché stimarlo.

• 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: presta estrema attenzione quando chiedi all'agente di riassumere dati interni sensibili e, al contempo, gli concedi l'accesso per navigare sul web pubblico.

• Verifica le citazioni: anche se viene applicato un filtro di livello enterprise, verifica sempre le citazioni fornite nella risposta per assicurarti che le fonti web siano affidabili.

Limitazioni

Tieni presenti le seguenti limitazioni durante la pianificazione del progetto:

• Solo single-turn: sono supportate solo le query single-turn. 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 è abilitata per impostazione predefinita per questo servizio. Non può essere disattivata.

• Conservazione dei dati: i prompt e l'output generato vengono archiviati 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 il 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 Deep Research di Gemini applica automaticamente l'etichetta utente is_deep_research alle sue operazioni. In Cloud de Confiance by S3NS, 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_research per impostazione predefinita per tutte le attività eseguite.

• Filtro di fatturazione: i report sulla 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 di ricerca e grounding). In questo modo, puoi aggregare e calcolare il costo totale dei tuoi workflow 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 all'interno del tuo progetto Cloud de Confiance .

Per aumentare la quota:

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

   Vai a Quote e limiti di sistema

2. Assicurati di aver selezionato il progetto corretto in cui sono in esecuzione i tuoi workload di Deep Research.

3. Nella casella di ricerca del filtro, cerca API Agent Platform (aiplatform.googleapis.com) per trovare le quote pertinenti per l'agente e l'interazione.

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

5. Fai clic su Modifica quote.

6. Nella finestra di dialogo Modifiche alla quota, nel campo Nuovo valore, inserisci il limite richiesto. Fornisci una motivazione chiara nella descrizione della richiesta. Menzionare il tuo caso d'uso specifico di Deep Research, le esigenze di esecuzione in background e i pattern di traffico previsti può 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 descritto nella Sezione 19 "Servizi di AI generativa: grounding 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 il grounding con la Ricerca Google. Non è possibile disattivare la memorizzazione di queste informazioni se utilizzi il grounding con la Ricerca Google. Se hai bisogno di una conservazione dei dati pari a zero, ti consigliamo di utilizzare Web Grounding for Enterprise.

Memorizzazione nella cache

La memorizzazione nella cache implicita è 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