Contexto de la URL

Puedes usar la herramienta de contexto de URL para proporcionar a Gemini URLs como contexto adicional para tu instrucción. Luego, el modelo puede recuperar contenido de las URLs y usarlo para fundamentar y dar forma a su respuesta.

Esta herramienta es útil para tareas como las siguientes:

  • Extraer puntos de datos o temas clave de los artículos
  • Comparar información en varios vínculos
  • Sintetizar datos de varias fuentes
  • Responder preguntas basadas en el contenido de una o varias páginas específicas
  • Analizar contenido para fines específicos (como escribir una descripción de trabajo o crear preguntas de prueba)

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

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

Modelos compatibles

Los siguientes modelos proporcionan compatibilidad con el contexto de URL:

Usar el contexto de la URL

Puedes usar la herramienta de contexto de URL de dos maneras principales: por sí sola o en conjunto con Fundamentación con la Búsqueda de Google.

Solo el contexto de la URL

Puedes proporcionar URLs específicas que deseas que el modelo analice directamente en tu instrucció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 fundamentación con la Búsqueda de Google, usando instrucciones con o sin URLs. Es posible que el modelo primero busque información relevante y, luego, use la herramienta de contexto de URL para leer el contenido de los resultados de la 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 instrucciones:

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 detalles sobre la Fundamentación con la Búsqueda de Google, consulta la página de descripción general.

Fundamentación web para empresas con contexto de URL

Puedes habilitar el contexto de URL y la fundamentación web para Enterprise si tienes necesidades de cumplimiento específicas o si trabajas en una industria regulada, como la salud, las finanzas o el sector público. El índice web que se usa en la fundamentación web para empresas es más limitado que el índice estándar de la fundamentación con la Búsqueda de Google, ya que utiliza un subconjunto de lo que está disponible en la Búsqueda de Google.

Para obtener más detalles sobre la fundamentación web para empresas, consulta la página Fundamentación web para empresas.

Respuesta contextual

La respuesta del modelo se basa en el contenido que recuperó de las URLs. Si el modelo recuperó contenido de URLs, la respuesta incluirá url_context_metadata. Una respuesta de este tipo podría verse de la siguiente manera (se omitieron partes de la respuesta 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 de UrlContextMetadata.

Recuperación en vivo

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

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

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

  2. Respaldo de recuperación en vivo: Esta es la segunda etapa. 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 indexó), la herramienta realiza automáticamente una recuperación en vivo. Este mecanismo de resguardo puede acceder directamente a la URL y recuperar la versión más reciente del contenido en tiempo real.

Verificaciones de seguridad

El sistema realiza una verificación de moderación de contenido en la URL para confirmar que cumple con los estándares de seguridad. Si la URL que proporcionaste no pasa esta verificación, obtendrás un url_retrieval_status de URL_RETRIEVAL_STATUS_UNSAFE.

Recuento de tokens

El recuento de tokens de entrada incluye el contenido recuperado de las URLs que especificas en tu instrucción. En el resultado del modelo, puedes ver el recuento de tokens de tu instrucción y el uso de herramientas en el objeto usage_metadata. El siguiente es 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 uses. Para obtener más información, consulta Costo de crear y, luego, implementar 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:

Contenido 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
  • Videos de YouTube (para obtener más información, consulta Comprensión de videos).
  • Archivos de Google Workspace, como Documentos de Google u Hojas de cálculo de Google
  • Archivos de audio y video

Limitaciones

  • La herramienta de contexto de URL consume hasta 20 URLs por solicitud para el análisis.
  • Para obtener mejores resultados durante la fase experimental, usa la herramienta en páginas web estándar en lugar de contenido multimedia, como videos de YouTube.