URL context

Com a ferramenta de contexto de URL, você pode fornecer mais contexto aos modelos na forma de URLs. Ao incluir URLs na sua solicitação, o modelo acessa o conteúdo dessas páginas (desde que não seja um tipo de URL listado na seção limitações) para informar e melhorar a resposta.

A ferramenta de contexto de URL é útil para tarefas como:

  • Extrair dados: extraia informações específicas, como preços, nomes ou descobertas importantes de vários URLs.
  • Comparar documentos: analise vários relatórios, artigos ou PDFs para identificar diferenças e acompanhar tendências.
  • Sintetizar e criar conteúdo: combine informações de vários URLs de origem para gerar resumos, postagens de blog ou relatórios precisos.
  • Analisar código e documentos: aponte para um repositório do GitHub ou documentação técnica para explicar o código, gerar instruções de configuração ou responder a perguntas.

O exemplo a seguir mostra como comparar duas receitas de sites diferentes.

Python

from google import genai
from google.genai.types import Tool, GenerateContentConfig

client = genai.Client()
model_id = "gemini-2.5-flash"

tools = [
  {"url_context": {}},
]

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

response = client.models.generate_content(
    model=model_id,
    contents=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",
    config=GenerateContentConfig(
        tools=tools,
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)

# For verification, you can inspect the metadata to see which URLs the model retrieved
print(response.candidates[0].url_context_metadata)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
        "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/",
    ],
    config: {
      tools: [{urlContext: {}}],
    },
  });
  console.log(response.text);

  // For verification, you can inspect the metadata to see which URLs the model retrieved
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "contents": [
          {
              "parts": [
                  {"text": "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": [
          {
              "url_context": {}
          }
      ]
  }' > result.json

cat result.json

Como funciona

A ferramenta Contexto da URL usa um processo de recuperação em duas etapas para equilibrar velocidade, custo e acesso a dados atualizados. Quando você fornece um URL, a ferramenta primeiro tenta buscar o conteúdo de um cache de índice interno. Ele funciona como um cache altamente otimizado. Se um URL não estiver disponível no índice (por exemplo, se for uma página muito nova), a ferramenta fará uma busca ativa automaticamente. Isso acessa diretamente o URL para recuperar o conteúdo em tempo real.

É possível combinar a ferramenta de contexto de URL com outras para criar fluxos de trabalho mais eficientes.

Quando o contexto do URL e o Embasamento com a Pesquisa Google estão ativados, o modelo pode usar os recursos de pesquisa para encontrar informações relevantes on-line e usar a ferramenta de contexto do URL para entender melhor as páginas encontradas. Essa abordagem é eficiente para comandos que exigem pesquisa ampla e análise detalhada de páginas específicas.

Python

from google import genai
from google.genai.types import Tool, GenerateContentConfig, GoogleSearch, UrlContext

client = genai.Client()
model_id = "gemini-2.5-flash"

tools = [
      {"url_context": {}},
      {"google_search": {}}
  ]

response = client.models.generate_content(
    model=model_id,
    contents="Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
    config=GenerateContentConfig(
        tools=tools,
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)
# get URLs retrieved for context
print(response.candidates[0].url_context_metadata)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
        "Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
    ],
    config: {
      tools: [
        {urlContext: {}},
        {googleSearch: {}}
        ],
    },
  });
  console.log(response.text);
  // To get URLs retrieved for context
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "contents": [
          {
              "parts": [
                  {"text": "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": [
          {
              "url_context": {}
          },
          {
              "google_search": {}
          }
      ]
  }' > result.json

cat result.json

Entender a resposta

Quando o modelo usa a ferramenta de contexto de URL, a resposta inclui um objeto url_context_metadata. Esse objeto lista os URLs de onde o modelo recuperou o conteúdo e o status de cada tentativa de recuperação, o que é útil para verificação e depuração.

Confira a seguir um exemplo dessa parte da resposta (algumas partes foram omitidas para facilitar a leitura):

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata": {
        "url_metadata": [
          {
            "retrieved_url": "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592",
            "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
          },
          {
            "retrieved_url": "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
            "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
          }
        ]
      }
    }
}

Para detalhes completos sobre esse objeto , consulte a referência da API UrlContextMetadata.

Verificações de segurança

O sistema faz uma verificação de moderação de conteúdo no URL para confirmar se ele atende aos padrões de segurança. Se o URL fornecido não passar nessa verificação, você vai receber um url_retrieval_status de URL_RETRIEVAL_STATUS_UNSAFE.

Contagem de tokens

O conteúdo recuperado dos URLs especificados no comando é contado como parte dos tokens de entrada. É possível conferir a contagem de tokens do comando e o uso de ferramentas no objeto usage_metadata da saída do modelo. Confira um exemplo de saída:

'usage_metadata': {
  'candidates_token_count': 45,
  'prompt_token_count': 27,
  'prompt_tokens_details': [{'modality': <MediaModality.TEXT: 'TEXT'>,
    'token_count': 27}],
  'thoughts_token_count': 31,
  'tool_use_prompt_token_count': 10309,
  'tool_use_prompt_tokens_details': [{'modality': <MediaModality.TEXT: 'TEXT'>,
    'token_count': 10309}],
  'total_token_count': 10412
  }

O preço por token depende do modelo usado. Consulte a página de preços para mais detalhes.

Modelos compatíveis

Práticas recomendadas

  • Forneça URLs específicos: para ter os melhores resultados, forneça URLs diretos do conteúdo que você quer que o modelo analise. O modelo só vai extrair conteúdo dos URLs fornecidos, não de links aninhados.
  • Verifique a acessibilidade: confira se os URLs fornecidos não levam a páginas que exigem login ou estão atrás de um paywall.
  • Use o URL completo: informe o URL completo, incluindo o protocolo (por exemplo, https://www.google.com em vez de apenas google.com).

Limitações

  • Preços: o conteúdo recuperado de URLs conta como tokens de entrada. A limitação de taxa e os preços são baseados no modelo usado. Consulte as páginas de limites de taxa e preços para mais detalhes.
  • Limite de solicitações: a ferramenta pode processar até 20 URLs por solicitação.
  • Tamanho do conteúdo do URL: o tamanho máximo do conteúdo recuperado de um único URL é de 34 MB.

Tipos de conteúdo compatíveis e incompatíveis

A ferramenta pode extrair conteúdo de URLs com os seguintes tipos de conteúdo:

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

Os seguintes tipos de conteúdo não são aceitos:

  • Conteúdo com paywall
  • Vídeos do YouTube. Consulte Entendimento de vídeo para saber como processar URLs do YouTube.
  • Arquivos do Google Workspace, como documentos ou planilhas Google
  • Arquivos de áudio e vídeo

A seguir