Fundamentación con la Búsqueda de Google

La Fundamentación con la Búsqueda de Google conecta el modelo de Gemini con el contenido web en tiempo real y funciona con todos los idiomas disponibles. Esto permite que Gemini proporcione respuestas más precisas y cite fuentes verificables más allá de su fecha límite de conocimiento.

La fundamentación te ayuda a crear aplicaciones que pueden hacer lo siguiente:

• Aumentar la exactitud fáctica: Reduce las alucinaciones del modelo basando las respuestas en información del mundo real.
• Acceder a información en tiempo real: Responde preguntas sobre eventos y temas recientes.

• Proporcionar citas: Genera confianza en los usuarios mostrando las fuentes de las afirmaciones del modelo.

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Who won the euro 2024?",
    tools=[{"type": "google_search"}]
)

# Print the model's text response
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Who won the euro 2024?",
    tools: [{ type: "google_search" }]
});

const modelStep = interaction.steps.find(s => s.type === 'model_output');
if (modelStep) {
  for (const contentBlock of modelStep.content) {
    if (contentBlock.type === 'text') console.log(contentBlock.text);
  }
}

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Who won the euro 2024?",
    "tools": [{"type": "google_search"}]
  }'

Cómo funciona la fundamentación con la Búsqueda de Google

Cuando habilitas la herramienta google_search, el modelo controla todo el flujo de trabajo de búsqueda, procesamiento y citación de información de forma automática.

1. Instrucción del usuario: Tu aplicación envía una instrucción del usuario a la API de Gemini con la herramienta google_search habilitada.
2. Análisis de instrucciones: El modelo analiza la instrucción y determina si una Búsqueda de Google puede mejorar la respuesta.
3. Búsqueda de Google: Si es necesario, el modelo genera automáticamente una o varias búsquedas y las ejecuta.
4. Procesamiento de resultados de la búsqueda: El modelo procesa los resultados de la búsqueda, sintetiza la información y formula una respuesta.
5. Respuesta fundamentada: La API muestra una respuesta final y fácil de usar que se basa en los resultados de la búsqueda. Esta respuesta incluye la respuesta de texto del modelo con annotations intercaladas que contienen las citas, así como los pasos google_search_call y google_search_result con las búsquedas y las sugerencias de búsqueda.

Información sobre la respuesta de fundamentación

Cuando una respuesta se fundamenta correctamente, el resultado de texto del modelo incluye annotations intercaladas directamente en el bloque de contenido de texto. Estas anotaciones proporcionan información de citas que vincula partes de la respuesta a sus fuentes.

{
  "steps": [
    {
      "type": "thought",
      "summary": [
        {
          "type": "text",
          "text": "The user is asking for the winner of Euro 2024. I need to search for the result of the Euro 2024 final."
        }
      ],
      "signature": "CoMDAXLI2nynRYojJIy6B1Jh9os2crpWLfB0..."
    },
    {
      "type": "google_search_call",
      "arguments": {
        "queries": ["UEFA Euro 2024 winner"]
      }
    },
    {
      "type": "google_search_result",
      "call_id": "search_001",
      "result": [
        {
          "search_suggestions": "<!-- HTML and CSS for the search widget -->"
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title.",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://www.aljazeera.com/sports/euro-2024-final",
              "title": "aljazeera.com",
              "start_index": 0,
              "end_index": 56
            },
            {
              "type": "url_citation",
              "url": "https://www.uefa.com/euro2024/news/spain-wins-euro-2024",
              "title": "uefa.com",
              "start_index": 57,
              "end_index": 124
            }
          ]
        }
      ]
    }
  ]
}

Los campos clave de la respuesta son los siguientes:

• google_search_call : Contiene las queries que ejecutó el modelo.
• google_search_result : Contiene search_suggestions, un fragmento de HTML para renderizar sugerencias de búsqueda en tu IU. Los requisitos de uso completos se detallan en las Condiciones del Servicio.
• text con annotations : La respuesta sintetizada del modelo con citas intercaladas. Cada anotación url_citation vincula un segmento de texto (definido por start_index y end_index) a una URL de origen. Esta es la clave para crear citas intercaladas.

La Fundamentación con la Búsqueda de Google también se puede usar en combinación con la herramienta de contexto de URL para fundamentar las respuestas en datos web públicos y en las URLs específicas que proporciones.

Atribución de fuentes con citas intercaladas

La API muestra anotaciones url_citation intercaladas en el bloque de contenido de texto, lo que te brinda control total sobre la forma en que muestras las fuentes en tu interfaz de usuario. Cada anotación incluye start_index y end_index para identificar qué parte del texto cita. A continuación, te mostramos cómo extraerlas y mostrarlas.

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nCitations:")
                    for annotation in content_block.annotations:
                        if annotation.type == "url_citation":
                            cited_text = content_block.text[annotation.start_index:annotation.end_index]
                            print(f"  [{annotation.title}]({annotation.url})")
                            print(f"    Cited text: \"{cited_text}\"")

for (const step of interaction.steps) {
  if (step.type === 'model_output') {
    for (const contentBlock of step.content) {
      if (contentBlock.type === 'text') {
        console.log(contentBlock.text);
        if (contentBlock.annotations) {
          console.log("\nCitations:");
          for (const annotation of contentBlock.annotations) {
            if (annotation.type === 'url_citation') {
              const citedText = contentBlock.text.slice(annotation.startIndex, annotation.endIndex);
              console.log(`  [${annotation.title}](${annotation.url})`);
              console.log(`    Cited text: "${citedText}"`);
            }
          }
        }
      }
    }
  }
}

El resultado mostrará el texto seguido de sus citas:

Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title.

Citations:
  [aljazeera.com](https://www.aljazeera.com/sports/euro-2024-final)
    Cited text: "Spain won Euro 2024, defeating England 2-1 in the final."
  [uefa.com](https://www.uefa.com/euro2024/news/spain-wins-euro-2024)
    Cited text: "This victory marks Spain's record fourth European Championship title."

Precios

Cuando usas la Fundamentación con la Búsqueda de Google con Gemini 3, se factura a tu proyecto cada búsqueda que el modelo decide ejecutar. Si el modelo decide ejecutar varias búsquedas para responder a una sola instrucción (por ejemplo, buscar "UEFA Euro 2024 winner" y "Spain vs England Euro 2024 final score" en la misma llamada a la API), esto cuenta como dos usos facturables de la herramienta para esa solicitud. Para fines de facturación, ignoramos las búsquedas web vacías cuando contamos las búsquedas únicas. Este modelo de facturación solo se aplica a los modelos de Gemini 3. Cuando usas la fundamentación de búsqueda con modelos de Gemini 2.5 o anteriores, se factura a tu proyecto por instrucción.

Para obtener información detallada sobre los precios, consulta la página de precios de la API de Gemini.

Modelos compatibles

Puedes encontrar las capacidades completas en la página de resumen del modelo.

Combinaciones de herramientas compatibles

Puedes usar la Fundamentación con la Búsqueda de Google con otras herramientas, como la ejecución de código y el contexto de URL, para potenciar casos de uso más complejos.

Los modelos de Gemini 3 admiten la combinación de herramientas integradas (como la Fundamentación con la Búsqueda de Google) con herramientas personalizadas (llamada a función). Obtén más información en la página de combinaciones de herramientas.

¿Qué sigue?

• Obtén información sobre otras herramientas disponibles, como la llamada a función.
• Obtén información para aumentar las instrucciones con URLs específicas mediante la herramienta de contexto de URL.