Contexto de URL

Puedes usar la herramienta de contexto de URL para proporcionar URLs a Gemini como contexto adicional para tu petición. El modelo puede obtener contenido de las URLs y usarlo para informar y dar forma a su respuesta.

Esta herramienta es útil para tareas como las siguientes:

  • Extraer puntos de datos o temas de conversación clave de artículos
  • Comparar información de varios enlaces
  • Sintetizar datos de varias fuentes
  • Responder a preguntas basadas en el contenido de una o varias páginas específicas
  • Analizar contenido con fines específicos (como redactar una descripción de un puesto de trabajo o crear preguntas para un examen)

Ten en cuenta que el índice que se usa para extraer datos puede no estar actualizado, por lo que es posible que haya información obsoleta.

En esta guía se explica cómo usar la herramienta de contexto de URL en la API de Gemini en Vertex AI.

Modelos admitidos

Los siguientes modelos admiten el contexto de URL:

Usar contexto de URL

Puedes usar la herramienta de contexto de URL de dos formas principales: sola o junto con Fundamentación con la Búsqueda de Google.

Solo contexto de URL

Puedes proporcionar URLs específicas que quieras que el modelo analice directamente en tu petición:

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

Fundamentación con la Búsqueda de Google con contexto de URL

También puedes habilitar el contexto de URL y la función de fundamentación con la Búsqueda de Google mediante peticiones con o sin URLs. El modelo puede buscar primero información relevante y, después, usar la herramienta de contexto de URL para leer el contenido de los resultados de búsqueda y obtener una comprensión más profunda.

Esta función es experimental y está disponible en la versión v1beta1 de la API.

Ejemplos de peticiones:

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 obtener más información sobre cómo utilizar la Búsqueda de Google, consulta la página de descripción general.

Fundamentación web para empresas con contexto de URL

Puedes habilitar tanto el contexto de URL como Web Grounding para empresas si tienes necesidades de cumplimiento específicas o si perteneces a un sector regulado, como el de la sanidad, las finanzas o el sector público. El índice web que se usa en Web Grounding for Enterprise es más limitado que el índice estándar de Grounding con la Búsqueda de Google, ya que usa un subconjunto de lo que está disponible en la Búsqueda de Google.

Para obtener más información sobre Web Grounding for Enterprise, consulta la página Web Grounding for Enterprise.

Respuesta contextual

La respuesta del modelo se basa en el contenido que ha obtenido de las URLs. Si el modelo ha obtenido contenido de URLs, la respuesta incluirá url_context_metadata. Una respuesta de este tipo podría tener un aspecto similar al siguiente (se han omitido algunas partes para mayor brevedad):

{
  "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 obtener más información sobre este objeto, consulta la referencia de la API UrlContextMetadata.

Obtención en directo

La herramienta de contexto de URL obtiene versiones activas de páginas web para mantener tu información actualizada.

Para recuperar el contenido de las páginas web de forma eficiente, la herramienta de contexto de URL usa un proceso de dos fases diseñado para equilibrar la velocidad, el coste y el acceso a la información más actualizada:

  1. Recuperación de contenido indexado: es la primera fase. Cuando proporcionas una URL, la herramienta intenta primero obtener el contenido del índice web extenso y altamente optimizado de Google. Este método proporciona un acceso rápido a una amplia colección de páginas web rastreadas.

  2. Reserva de recuperación de datos en directo: es la segunda fase. Si el contenido de una URL determinada no está disponible en el índice (por ejemplo, si la página es muy nueva y aún no se ha indexado), la herramienta realiza automáticamente una obtención en directo. Este mecanismo de reserva puede acceder directamente a la URL y obtener la versión más reciente del contenido en tiempo real.

Comprobaciones de seguridad

El sistema realiza una comprobación de moderación de contenido en la URL para confirmar que cumple los estándares de seguridad. Si la URL que has proporcionado no supera esta comprobación, recibirás un url_retrieval_status de URL_RETRIEVAL_STATUS_UNSAFE.

Recuento de tokens

El recuento de tokens de entrada incluye el contenido obtenido de las URLs que especifiques en tu petición. En el resultado del modelo, puedes ver el recuento de tokens de tu petición y el uso de herramientas en el objeto usage_metadata. A continuación se muestra un ejemplo de resultado:

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

El precio por token depende del modelo que utilices. Para obtener más información, consulta Coste de crear y desplegar modelos de IA en Vertex AI.

Tipos de contenido admitidos y no admitidos

La herramienta de contexto de URL puede extraer contenido de URLs con los siguientes tipos de contenido:

Content Tipo
Texto text/html
application/json
text/plain
text/xml
text/css
text/javascript
text/csv
text/rtf
Imagen image/png
image/jpeg
image/bmp
image/webp
PDF application/pdf

La herramienta de contexto de URL no admite los siguientes tipos de contenido:

  • Contenido con muro de pago
  • Vídeos de YouTube (para obtener más información, consulta Información sobre los vídeos).
  • Archivos de Google Workspace, como Documentos o Hojas de cálculo de Google
  • Archivos de vídeo y audio

Limitaciones

  • La herramienta de contexto de URL puede analizar hasta 20 URLs por solicitud.
  • Para obtener los mejores resultados durante la fase experimental, usa la herramienta en páginas web estándar en lugar de contenido multimedia, como vídeos de YouTube.