URL context

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á al contenido de esas páginas (siempre y cuando no se trate de un tipo de URL que se indique en la sección de limitaciones) para fundamentar 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, informes o publicaciones de blog precisos.
  • Analizar código y documentos: Indica un repositorio de GitHub o 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-2.5-flash"

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-2.5-flash",
    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-2.5-flash: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 Contexto de URL usa un proceso de recuperación de dos pasos para equilibrar la velocidad, el costo y el acceso a datos nuevos. 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.

Puedes combinar la herramienta de contexto de URL con otras herramientas para crear flujos de trabajo más potentes.

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 relevante en línea y, luego, usar la herramienta de contexto de URL para comprender mejor las páginas que encuentra. Este enfoque es eficaz para las instrucciones que requieren tanto una búsqueda amplia como 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-2.5-flash"

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-2.5-flash",
    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-2.5-flash: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

Cómo comprender la respuesta

Cuando el modelo usa la herramienta de contexto de URL, la respuesta incluye un objeto url_context_metadata. Este objeto enumera las URLs desde las que el modelo recuperó contenido y el estado de cada intento de recuperación, lo que resulta ú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 referencia de la API de UrlContextMetadata.

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, recibirá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 objeto usage_metadata del resultado del modelo. 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 se use. Consulta la página de precios para obtener más detalles.

Modelos compatibles

Prácticas recomendadas

  • Proporciona URLs específicas: Para obtener los mejores resultados, proporciona URLs directas al contenido que quieres que analice el modelo. El modelo solo recuperará contenido de las URLs que proporciones, no de los vínculos anidados.
  • Verifica la accesibilidad: Comprueba que las URLs que proporciones no dirijan a páginas que requieran un acceso o 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

  • Precios: El contenido recuperado de las URLs se considera como tokens de entrada. El límite de frecuencia y el precio se basan en el modelo que se usa. Consulta las páginas de límites de frecuencia y precios para obtener más detalles.
  • 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.

Tipos de contenido admitidos y no admitidos

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

  • 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)

No se admiten los siguientes tipos de contenido:

  • Contenido pago
  • Videos de YouTube (consulta la comprensión de video para obtener información sobre cómo procesar URLs de YouTube)
  • Archivos de Google Workspace, como documentos u hojas de cálculo de Google
  • Archivos de audio y video

¿Qué sigue?