Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 extrair conteúdo dos URLs e usá-lo para informar e moldar a resposta.

Essa ferramenta é útil para tarefas como as seguintes:

Extrair pontos de dados ou tópicos principais de artigos
Comparar informações em vários links
Sintetizar 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)

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

Este guia explica como usar a ferramenta de contexto de URL na API Gemini na plataforma de agentes do Gemini Enterprise.

Modelos compatíveis

Os seguintes modelos oferecem suporte ao contexto de URL:

Usar o 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-3.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-3.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-3.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 com 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, em seguida, usar a ferramenta de contexto de URL para ler o conteúdo dos resultados da pesquisa para uma compreensão mais detalhada.

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-3.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-3.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-3.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 visão geral página.

Embasamento na Web para empresas com contexto de URL

Você pode ativar o contexto de URL e o embasamento na Web para empresas se tiver necessidades de conformidade específicas 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 da Pesquisa padrão do embasamento com a Pesquisa Google, porque 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 extraído dos URLs. Se o modelo extraiu conteúdo de URLs, a resposta vai incluir url_context_metadata. Uma resposta como essa pode ser parecida com a seguinte (partes da resposta foram omitidas para maior clareza):

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata":
      {
          "url_metadata":
          [
            {
              "retrieved_url": "https://cloud.google.com/gemini-enterprise-agent-platform/models/capabilities/code-execution",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "https://cloud.google.com/gemini-enterprise-agent-platform/models/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 UrlContextMetadata referência da API.

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 extrair o conteúdo da página da Web com eficiência, a ferramenta de contexto de URL usa um processo de duas etapas projetado para equilibrar velocidade, custo e acesso às informações mais atuais:

Extração de conteúdo indexado: esta é a primeira etapa. Quando você fornece um URL, a ferramenta primeiro tenta extrair o conteúdo do Google's índice da Web extenso e altamente otimizado. Esse método oferece acesso rápido a uma vasta coleção de páginas da Web rastreadas.
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 realizar uma busca em tempo real automaticamente. Esse mecanismo de fallback pode acessar o URL diretamente e extrair a versão mais recente do conteúdo em tempo real.

Verificações de segurança

O sistema realiza 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 falhar 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 extraído dos URLs especificados no comando. Na saída do modelo, é possível conferir a contagem de tokens do 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 plataforma de agentes do Gemini Enterprise.

Tipos de conteúdo aceitos e não aceitos

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 oferece suporte aos 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 o Documentos Google ou o 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 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.

Contexto do URL Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Modelos compatíveis

Usar o contexto de URL

Somente contexto de URL

Python

JavaScript

REST

Embasamento com a Pesquisa Google com contexto de URL

Python

JavaScript

REST

Embasamento na Web para empresas com contexto de URL

Resposta contextual

Busca em tempo real

Verificações de segurança

Contagem de tokens

Tipos de conteúdo aceitos e não aceitos

Limitações

Contexto do URL