Contexto do URL

Você pode usar a ferramenta de contexto de URL para fornecer URLs ao Gemini como contexto adicional para seu comando. Em seguida, o modelo pode recuperar conteúdo dos URLs e usar esse conteúdo para informar e moldar a resposta.

Essa ferramenta é útil para tarefas como as seguintes:

  • Extrair pontos de dados ou pontos de discussão importantes de artigos
  • Comparar informações em vários links
  • Síntese de dados de várias fontes
  • Responder a perguntas com base no conteúdo de uma ou mais páginas específicas
  • Analisar conteúdo para fins específicos (como escrever uma descrição de vaga ou criar perguntas de teste)

O índice usado para extrair dados pode não estar atualizado, então algumas informações podem estar desatualizadas.

Neste guia, explicamos como usar a ferramenta de contexto de URL na API Gemini na Vertex AI.

Modelos compatíveis

Os seguintes modelos oferecem suporte ao contexto de URL:

Usar contexto de URL

Você pode usar a ferramenta de contexto de URL de duas maneiras principais: sozinha ou em conjunto com o Embasamento com a Pesquisa Google.

Somente contexto de URL

Você pode fornecer URLs específicos que quer que o modelo analise diretamente no comando:

Summarize this document: YOUR_URLs

Extract the key features from the product description on this page: YOUR_URLs

Python

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

client = genai.Client(http_options=HttpOptions(api_version="v1"))
model_id = "gemini-2.5-flash"

url_context_tool = Tool(
    url_context = UrlContext
)

response = client.models.generate_content(
    model=model_id,
    contents="Compare recipes from YOUR_URL1 and YOUR_URL2",
    config=GenerateContentConfig(
        tools=[url_context_tool],
        response_modalities=["TEXT"],
    )
)

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

JavaScript

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

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

const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
  apiVersion: 'v1',
});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
        "Compare recipes from YOUR_URL1 and YOUR_URL2",
    ],
    config: {
      tools: [{urlContext: {}}],
    },
  });
  console.log(response.text);
  // To get URLs retrieved for context
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-2.5-flash:generateContent \
  -d '{
      "contents": [
          {
              "role": "user",
              "parts": [
                  {"text": "Compare recipes from YOUR_URL1 and YOUR_URL2"}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          }
      ]
  }' > result.json

cat result.json

Embasamento com a Pesquisa Google e contexto de URL

Você também pode ativar o contexto de URL e o Embasamento com a Pesquisa Google usando comandos com ou sem URLs. O modelo pode primeiro pesquisar informações relevantes e depois usar a ferramenta de contexto de URL para ler o conteúdo dos resultados da pesquisa e ter um entendimento mais detalhado.

Esse recurso é experimental e está disponível na versão v1beta1 da API.

Exemplos de comandos:

Give me a three day event schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.

Recommend 3 books for beginners to read to learn more about the latest YOUR_SUBJECT.

Python

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

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-2.5-flash"

tools = []
tools.append(Tool(url_context=UrlContext))
tools.append(Tool(google_search=GoogleSearch))

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,
        response_modalities=["TEXT"],
    )
)

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

JavaScript

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

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

const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
  apiVersion: 'v1beta1',
});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
        "Give me a three day event 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 -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-2.5-flash:generateContent \
  -d '{
      "contents": [
          {
              "role": "user",
              "parts": [
                  {"text": "Give me a three day event 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

Para mais detalhes sobre o embasamento com a Pesquisa Google, consulte a página de visão geral.

Embasamento na Web para empresas com contexto de URL

É possível ativar o contexto de URL e o embasamento na Web para empresas se você tiver necessidades específicas de compliance ou estiver em um setor regulamentado como saúde, finanças ou setor público. O índice da Web usado no embasamento na Web para empresas é mais limitado do que o índice padrão do embasamento com a Pesquisa Google, já que usa um subconjunto do que está disponível na Pesquisa Google.

Para mais detalhes sobre o embasamento na Web para empresas, consulte a página Embasamento na Web para empresas.

Resposta contextual

A resposta do modelo é baseada no conteúdo recuperado dos URLs. Se o modelo tiver recuperado conteúdo de URLs, a resposta vai incluir url_context_metadata. Uma resposta desse tipo pode ser semelhante a esta (partes da resposta foram omitidas para facilitar a leitura):

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata":
      {
          "url_metadata":
          [
            {
              "retrieved_url": "https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/code-execution",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "https://cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-search",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
          ]
        }
    }
  ]
}

Para mais informações sobre esse objeto, consulte a referência da API UrlContextMetadata.

Busca em tempo real

A ferramenta de contexto de URL busca versões ativas de páginas da Web para manter suas informações atualizadas.

Para recuperar o conteúdo da página da Web de maneira eficiente, a ferramenta de contexto de URL usa um processo de duas etapas projetado para equilibrar velocidade, custo e acesso às informações mais atuais:

  1. Recuperação de conteúdo indexado: esta é a primeira etapa. Quando você fornece um URL, a ferramenta primeiro tenta buscar o conteúdo do índice da Web extenso e altamente otimizado do Google. Esse método oferece acesso rápido a uma vasta coleção de páginas da Web rastreadas.

  2. Fallback de busca em tempo real: esta é a segunda etapa. Se o conteúdo de um determinado URL não estiver disponível no índice (por exemplo, se a página for muito nova e ainda não tiver sido indexada), a ferramenta vai fazer uma busca ativa automaticamente. Esse mecanismo de substituição pode acessar diretamente o URL e recuperar a versão mais recente do conteúdo em tempo real.

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

A contagem de tokens de entrada inclui o conteúdo recuperado dos URLs especificados no comando. Na saída do modelo, é possível conferir a contagem de tokens do seu comando e o uso de ferramentas no objeto usage_metadata. 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. Para mais informações, consulte Custo de criação e implantação de modelos de IA na Vertex AI.

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

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

Conteúdo Tipo
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

A ferramenta de contexto de URL não é compatível com os seguintes tipos de conteúdo:

  • Conteúdo com paywall
  • Vídeos do YouTube. Para mais informações, consulte Entendimento de vídeo.
  • Arquivos do Google Workspace, como Documentos ou Planilhas Google
  • Arquivos de áudio e vídeo

Limitações

  • A ferramenta de contexto de URL consome até 20 URLs por solicitação para análise.
  • Para ter os melhores resultados durante a fase experimental, use a ferramenta em páginas da Web padrão, em vez de conteúdo multimídia, como vídeos do YouTube.