La herramienta de contexto de URL te permite proporcionar contexto adicional a los modelos en forma de URLs. Si incluyes URLs en tu solicitud, el modelo accederá a el contenido de esas páginas (siempre que no sea un tipo de URL que se indique en la sección de limitaciones) para informar y mejorar su respuesta.
La herramienta de contexto de URL es útil para tareas como las siguientes:
- Extraer datos: Extrae información específica, como precios, nombres o hallazgos clave de varias URLs.
- Comparar documentos: Analiza varios informes, artículos o PDFs para identificar diferencias y hacer un seguimiento de las tendencias.
- Sintetizar y crear contenido: Combina información de varias URLs de origen para generar resúmenes, entradas de blog o informes precisos.
- Analizar código y documentos: Dirige a un repositorio de GitHub o a documentación técnica para explicar el código, generar instrucciones de configuración o responder preguntas.
En el siguiente ejemplo, se muestra cómo comparar dos recetas de diferentes sitios web.
Python
from google import genai
from google.genai.types import Tool, GenerateContentConfig
client = genai.Client()
model_id = "gemini-3-flash-preview"
tools = [
{"url_context": {}},
]
url1 = "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"
url2 = "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"
response = client.models.generate_content(
model=model_id,
contents=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",
config=GenerateContentConfig(
tools=tools,
)
)
for each in response.candidates[0].content.parts:
print(each.text)
# For verification, you can inspect the metadata to see which URLs the model retrieved
print(response.candidates[0].url_context_metadata)
JavaScript
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const response = await ai.models.generateContent({
model: "gemini-3-flash-preview",
contents: [
"Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
],
config: {
tools: [{urlContext: {}}],
},
});
console.log(response.text);
// For verification, you can inspect the metadata to see which URLs the model retrieved
console.log(response.candidates[0].urlContextMetadata)
}
await main();
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"parts": [
{"text": "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"}
]
}
],
"tools": [
{
"url_context": {}
}
]
}' > result.json
cat result.json
Cómo funciona
La herramienta de contexto de URL usa un proceso de recuperación de dos pasos para equilibrar la velocidad, el costo y el acceso a datos actualizados. Cuando proporcionas una URL, la herramienta primero intenta recuperar el contenido de una caché de índice interna. Esto actúa como una caché altamente optimizada. Si una URL no está disponible en el índice (por ejemplo, si es una página muy nueva), la herramienta recurre automáticamente a realizar una recuperación en vivo. Esto accede directamente a la URL para recuperar su contenido en tiempo real.
Combinación con otras herramientas
Puedes combinar la herramienta de contexto de URL con otras herramientas para crear flujos de trabajo más potentes.
Los modelos de Gemini 3 admiten la combinación de herramientas integradas (como el contexto de URL) con herramientas personalizadas (llamadas a funciones). Obtén más información en la página de combinaciones de herramientas.
Fundamentación con la búsqueda
Cuando se habilitan el contexto de URL y la fundamentación con la Búsqueda de Google, el modelo puede usar sus capacidades de búsqueda para encontrar información pertinente en línea y, luego, usar la herramienta de contexto de URL para obtener una comprensión más detallada de las páginas que encuentra. Este enfoque es potente para las instrucciones que requieren una búsqueda amplia y un análisis profundo de páginas específicas.
Python
from google import genai
from google.genai.types import Tool, GenerateContentConfig, GoogleSearch, UrlContext
client = genai.Client()
model_id = "gemini-3-flash-preview"
tools = [
{"url_context": {}},
{"google_search": {}}
]
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,
)
)
for each in response.candidates[0].content.parts:
print(each.text)
# get URLs retrieved for context
print(response.candidates[0].url_context_metadata)
JavaScript
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const response = await ai.models.generateContent({
model: "gemini-3-flash-preview",
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: {
tools: [
{urlContext: {}},
{googleSearch: {}}
],
},
});
console.log(response.text);
// To get URLs retrieved for context
console.log(response.candidates[0].urlContextMetadata)
}
await main();
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"parts": [
{"text": "Give me three day events 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
Comprende la respuesta
Cuando el modelo usa la herramienta de contexto de URL, la respuesta incluye un objeto url_context_metadata. Este objeto muestra las URLs de las que el modelo recuperó contenido y el estado de cada intento de recuperación, lo que es útil para la verificación y la depuración.
A continuación, se muestra un ejemplo de esa parte de la respuesta (se omitieron partes de la respuesta para mayor brevedad):
{
"candidates": [
{
"content": {
"parts": [
{
"text": "... \n"
}
],
"role": "model"
},
...
"url_context_metadata": {
"url_metadata": [
{
"retrieved_url": "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592",
"url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
},
{
"retrieved_url": "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
"url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
}
]
}
}
]
}
Para obtener detalles completos sobre este objeto , consulta la
UrlContextMetadata referencia de la API.
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, obtendrás un url_retrieval_status de URL_RETRIEVAL_STATUS_UNSAFE.
Recuento de tokens
El contenido recuperado de las URLs que especificas en tu instrucción se cuenta como parte de los tokens de entrada. Puedes ver el recuento de tokens de tu instrucción y
el uso de herramientas en el usage_metadata
objeto del resultado del modelo. 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 utilizado. Consulta la página de precios para obtener más detalles.
Modelos compatibles
| Modelo | Contexto de URL |
|---|---|
| Gemini 3.1 Pro (versión preliminar) | ✔️ |
| Gemini 3.1 Flash-Lite (versión preliminar) | ✔️ |
| Gemini 3 Flash (versión preliminar) | ✔️ |
| Gemini 2.5 Pro | ✔️ |
| Gemini 2.5 Flash | ✔️ |
| Gemini 2.5 Flash-Lite | ✔️ |
Prácticas recomendadas
- Proporciona URLs específicas: Para obtener los mejores resultados, proporciona URLs directas al contenido que deseas que analice el modelo. El modelo solo recuperará contenido de las URLs que proporciones, no de los vínculos anidados.
- Verifica la accesibilidad: Verifica que las URLs que proporciones no dirijan a páginas que requieran un acceso o que estén detrás de un muro de pago.
- Usa la URL completa: Proporciona la URL completa, incluido el protocolo (p.ej., https://www.google.com en lugar de solo google.com).
Limitaciones
- Llamadas a funciones: Actualmente, no se admite el uso de herramientas (contexto de URL, fundamentación con la Búsqueda de Google, etc.) con llamadas a funciones.
- Límite de solicitudes: La herramienta puede procesar hasta 20 URLs por solicitud.
- Tamaño del contenido de la URL: El tamaño máximo del contenido recuperado de una sola URL es de 34 MB.
- Accesibilidad pública: Las URLs deben ser de acceso público en la Web. No se admiten las direcciones de localhost (p.ej., localhost, 127.0.0.1), las redes privadas ni los servicios de tunelización (p.ej., ngrok, pinggy).
- Solo la API de Gemini: El contexto de URL solo está disponible en la API de Gemini, no a través de Vertex AI.
Tipos de contenido compatibles y no compatibles
La herramienta puede extraer contenido de URLs con los siguientes tipos de contenido:
- Texto (texto/html, aplicación/json, texto/sin formato, texto/xml, texto/css, texto/javascript , texto/csv, texto/rtf)
- Imagen (imagen/png, imagen/jpeg, imagen/bmp, imagen/webp)
- PDF (aplicación/pdf)
No se admiten los siguientes tipos de contenido:
- Contenido pago
- Videos de YouTube (consulta Comprensión de videos para obtener información sobre cómo procesar URLs de YouTube)
- Archivos de Google Workspace, como Documentos o Hojas de cálculo de Google
- Archivos de audio y video
¿Qué sigue?
- Explora el libro de recetas de contexto de URL para obtener más ejemplos.