Contesto URL

Lo strumento Contesto URL ti consente di fornire un contesto aggiuntivo ai modelli sotto forma di URL. Se includi gli URL nella richiesta, il modello accederà ai contenuti di queste pagine (purché non si tratti di un tipo di URL elencato nella sezione delle limitazioni) per informare e migliorare la sua risposta.

Lo strumento Contesto URL è utile per attività come le seguenti:

• Estrarre dati: estrai informazioni specifiche come prezzi, nomi o risultati chiave da più URL.
• Confrontare documenti: analizza più report, articoli o PDF per identificare le differenze e monitorare le tendenze.
• Sintetizzare e creare contenuti: combina le informazioni di più URL di origine per generare riepiloghi, post di blog o report accurati.
• Analizzare codice e documenti: indica un repository GitHub o una documentazione tecnica per spiegare il codice, generare istruzioni di configurazione o rispondere alle domande.

L'esempio seguente mostra come confrontare due ricette di siti web diversi.

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

url1 = "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"
url2 = "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",
    tools=[{"type": "url_context"}]
)

# Print the model's text response and its source annotations
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "url_citation":
                            print(f"  - {annotation.title}: {annotation.url}")

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.5-flash",
    input: "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
    tools: [{ type: "url_context" }]
  });

  // Print the model's text response and its source annotations
  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'url_citation') {
                console.log(`  - ${annotation.title}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

await main();

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "model": "gemini-3.5-flash",
      "input": "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
      "tools": [{"type": "url_context"}]
  }'

Come funziona

Lo strumento Contesto URL utilizza una procedura di recupero in due passaggi per bilanciare velocità, costi e accesso ai dati aggiornati. Quando fornisci un URL, lo strumento tenta innanzitutto di recuperare i contenuti da una cache di indici interni. Questa funge da cache altamente ottimizzata. Se un URL non è disponibile nell'indice (ad esempio, se si tratta di una pagina molto recente), lo strumento esegue automaticamente il fallback per eseguire un recupero in tempo reale. In questo modo, l'URL viene acceduto direttamente per recuperare i relativi contenuti in tempo reale.

Combinazione con altri strumenti

Puoi combinare lo strumento Contesto URL con altri strumenti per creare workflow più efficaci.

I modelli Gemini 3 supportano la combinazione di strumenti integrati (come Contesto URL) con strumenti personalizzati (chiamata di funzioni). Scopri di più nella pagina delle combinazioni di strumenti.

Grounding con la ricerca

Se sono attivi sia Contesto URL sia Grounding con la Ricerca Google, il modello può utilizzare le sue funzionalità di ricerca per trovare informazioni pertinenti online e poi utilizzare lo strumento Contesto URL per comprendere meglio le pagine che trova. Questo approccio è efficace per i prompt che richiedono sia una ricerca ampia sia un'analisi approfondita di pagine specifiche.

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
    tools=[
        {"type": "url_context"},
        {"type": "google_search"}
    ]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.5-flash",
    input: "Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
    tools: [
      { type: "url_context" },
      { type: "google_search" }
    ]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') console.log(contentBlock.text);
      }
    }
  }
}

await main();

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "model": "gemini-3.5-flash",
      "input": "Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
      "tools": [
          {"type": "url_context"},
          {"type": "google_search"}
      ]
  }'

Comprendere la risposta

Quando il modello utilizza lo strumento Contesto URL, la risposta di testo include annotazioni url_citation in linea nel blocco di contenuti di testo. Ogni annotazione collega un segmento del testo di risposta (tramite start_index e end_index) all'URL di origine da cui è stato derivato. Questo è il modo principale per visualizzare le citazioni nella tua applicazione. Per scoprire come estrarle, consulta l'esempio principale riportato sopra.

La risposta include anche un passaggio url_context_result con metadati su ogni tentativo di recupero dell'URL (stato, URL recuperato). Questo è utile principalmente per il debug.

Assegni assicurati

Il sistema esegue un controllo di moderazione dei contenuti sugli URL per verificare che soddisfino gli standard di sicurezza. Se un URL non supera questo controllo, il passaggio corrispondente url_context_result mostrerà uno status di "unsafe".

Conteggio dei token

I contenuti recuperati dagli URL specificati nel prompt vengono conteggiati come parte dei token di input. Puoi visualizzare il conteggio dei token nell'oggetto usage dell'interazione. Di seguito è riportato un esempio:

'usage': {
  'output_tokens': 45,
  'input_tokens': 27,
  'input_tokens_details': [{'modality': 'TEXT', 'token_count': 27}],
  'thoughts_tokens': 31,
  'tool_use_input_tokens': 10309,
  'tool_use_input_tokens_details': [{'modality': 'TEXT', 'token_count': 10309}],
  'total_tokens': 10412
}

Il prezzo per token dipende dal modello utilizzato. Per maggiori dettagli, consulta la pagina dei prezzi.

Modelli supportati

Best practice

• Fornisci URL specifici: per ottenere risultati ottimali, fornisci URL diretti ai contenuti che vuoi che il modello analizzi. Il modello recupererà solo i contenuti degli URL che fornisci, non quelli dei link nidificati.
• Verifica l'accessibilità: verifica che gli URL forniti non rimandino a pagine che richiedono l'accesso o che siano protette da paywall.
• Utilizza l'URL completo: fornisci l'URL completo, incluso il protocollo (ad es. https://www.google.com anziché solo google.com).

Limitazioni

• Limite delle richieste: lo strumento può elaborare fino a 20 URL per richiesta.
• Dimensioni dei contenuti dell'URL: la dimensione massima dei contenuti recuperati da un singolo URL è di 34 MB.
• Accessibilità pubblica: gli URL devono essere accessibili pubblicamente sul web. Gli indirizzi localhost (ad es. localhost, 127.0.0.1), le reti private e i servizi di tunneling (ad es. ngrok, pinggy) non sono supportati.
• Solo API Gemini: il contesto URL è disponibile solo nell'API Gemini, non tramite la piattaforma agentica Gemini Enterprise.

Tipi di contenuti supportati e non supportati

Lo strumento può estrarre contenuti da URL con i seguenti tipi di contenuti:

• Testo (text/html, application/json, text/plain, text/xml, text/css, text/javascript , text/csv, text/rtf)
• Immagine (image/png, image/jpeg, image/bmp, image/webp)
• PDF (application/pdf)

I seguenti tipi di contenuti non sono supportati:

• Contenuti protetti da paywall
• Video di YouTube (per scoprire come elaborare gli URL di YouTube, consulta la sezione Comprensione dei video)
• File di Google Workspace come Documenti o Fogli Google
• File video e audio