Contexto de URL

Puedes usar la herramienta de contexto de URL para proporcionarle 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 de conversación clave de artículos
  • Comparar información de 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 puesto o crear preguntas de prueba)

Ten en cuenta que el índice que se usa para extraer datos puede no estar actualizado, por lo que parte de la información puede estar desactualizada.

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

Modelos compatibles

Los siguientes modelos proporcionan compatibilidad con el contexto de URL:

Haz clic para expandir los modelos compatibles

Usa el contexto de URL

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

Solo el contexto de URL

Puedes proporcionar URLs específicas que quieras 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

API de GenerateContent

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)

API de Interactions

from google import genai

client = genai.Client(
    enterprise=True,
    project="GOOGLE_CLOUD_PROJECT",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Compare recipes from YOUR_URL1 and YOUR_URL2",
    tools=[{"type": "url_context"}],
)

print(interaction.output_text)

# Get URLs retrieved for context
for step in interaction.steps:
    if step.type == "url_context_result":
        for res in step.result:
            print(f"URL: {res.url} (Status: {res.status})")

JavaScript

API de GenerateContent

# 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_ENTERPRISE=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();

API de Interactions

# 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_ENTERPRISE=True
import { GoogleGenAI } from "@google/genai";

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

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Compare recipes from YOUR_URL1 and YOUR_URL2",
    tools: [{ type: "url_context" }],
  });

  console.log(interaction.output_text);

  for (const step of interaction.steps) {
    if (step.type === "url_context_result") {
      console.log(step.result);
    }
  }
}

await main();

REST

API de GenerateContent

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • GOOGLE_CLOUD_PROJECT: El ID del proyecto.
  • YOUR_URL1: Es la primera URL de la que se recuperará el contexto.
  • YOUR_URL2: Es la segunda URL de la que se recuperará el contexto.

Método HTTP y URL:

POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent

Cuerpo JSON de la solicitud:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Compare recipes from YOUR_URL1 and YOUR_URL2"
        }
      ]
    }
  ],
  "tools": [
    {
      "url_context": {}
    }
  ]
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent"

PowerShell

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent" | Select-Object -Expand Content

API de Interactions

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • GOOGLE_CLOUD_PROJECT: El ID del proyecto.
  • YOUR_URL1: Es la primera URL de la que se recuperará el contexto.
  • YOUR_URL2: Es la segunda URL de la que se recuperará el contexto.

Método HTTP y URL:

POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions

Cuerpo JSON de la solicitud:

{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Compare recipes from YOUR_URL1 and YOUR_URL2"
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "url_context"
    }
  ]
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions"

PowerShell

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions" | Select-Object -Expand Content

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. El modelo puede buscar primero información relevante y, luego, usar la herramienta de contexto de URL para leer el contenido de los resultados de la búsqueda y obtener una comprensión más detallada.

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

API de GenerateContent

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)

API de Interactions

from google import genai

client = genai.Client(
    enterprise=True,
    project="GOOGLE_CLOUD_PROJECT",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Give me a three day event schedule based on YOUR_URL. Also let me know what needs to be taken care of considering weather and commute.",
    tools=[
        {"type": "url_context"},
        {"type": "google_search"},
    ],
)

print(interaction.output_text)

# Get URLs retrieved for context
for step in interaction.steps:
    if step.type == "url_context_result":
        for res in step.result:
            print(f"URL: {res.url} (Status: {res.status})")

JavaScript

API de GenerateContent

# 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_ENTERPRISE=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();

API de Interactions

# 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_ENTERPRISE=True
import { GoogleGenAI } from "@google/genai";

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

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Give me a three day event schedule based on YOUR_URL. Also let me know what needs to be taken care of considering weather and commute.",
    tools: [
      { type: "url_context" },
      { type: "google_search" },
    ],
  });

  console.log(interaction.output_text);

  for (const step of interaction.steps) {
    if (step.type === "url_context_result") {
      console.log(step.result);
    }
  }
}

await main();

REST

API de GenerateContent

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • GOOGLE_CLOUD_PROJECT: El ID del proyecto.
  • YOUR_URL: Es la URL desde la que se recuperará el contexto.

Método HTTP y URL:

POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent

Cuerpo JSON de la solicitud:

{
  "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": {}
    }
  ]
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent"

PowerShell

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent" | Select-Object -Expand Content

API de Interactions

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • GOOGLE_CLOUD_PROJECT: El ID del proyecto.
  • YOUR_URL: Es la URL desde la que se recuperará el contexto.

Método HTTP y URL:

POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions

Cuerpo JSON de la solicitud:

{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "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": [
    {
      "type": "url_context"
    },
    {
      "type": "google_search"
    }
  ]
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions"

PowerShell

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions" | Select-Object -Expand Content

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 Empresas si tienes necesidades de cumplimiento específicas o estás 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 usa 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 las URLs, la respuesta incluirá url_context_metadata. Una respuesta de este tipo podría ser similar a la siguiente (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/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 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 en vivo de las páginas web para mantener tu información actualizada.

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

  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 gran colección de páginas web rastreadas.

  2. Resguardo 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 tiempo real. Este mecanismo de resguardo puede acceder directamente a la URL y recuperar la versión más reciente del contenido en tiempo real.

Controles de seguridad

El sistema realiza una verificación de moderación de contenido en la URL para confirmar que cumpla con los estándares de seguridad. Si la URL que proporcionaste no pasa esta verificación, recibirá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 para el uso de instrucciones y herramientas en el objeto usage_metadata. A continuación, se muestra un resultado de ejemplo:

'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 Gemini Enterprise Agent Platform.

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 o 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 los mejores resultados durante la fase experimental, usa la herramienta en páginas web estándar, en lugar de contenido multimedia, como videos de YouTube.