Configura las capacidades de Gemini

En este documento, se muestra cómo configurar varias capacidades de los modelos de Gemini cuando se usa la API de Gemini Live. Puedes configurar el uso de herramientas, como la llamada a funciones y la fundamentación, y las capacidades de audio en vivo, como el diálogo afectivo y el audio proactivo.

Configura el uso de herramientas

Varias herramientas son compatibles con diferentes versiones de los modelos admitidos por la API de Gemini Live, incluidas las siguientes:

Para habilitar una herramienta en particular para su uso en las respuestas devueltas, incluye el nombre de la herramienta en la lista tools cuando inicialices el modelo. En las siguientes secciones, se proporcionan ejemplos de cómo usar cada una de las herramientas integradas en tu código.

Importante: La API de Gemini no admite la combinación de herramientas de búsqueda (como googleSearch) con herramientas que no son de búsqueda (como la llamada a funciones o la herramienta retrieval del motor de RAG de Gemini Enterprise Agent Platform) en la misma solicitud de configuración. Solo se admiten varias herramientas cuando todas son herramientas de búsqueda.

Llamada a función

Usa la llamada a función cuando quieras que el modelo interactúe con sistemas externos o APIs que administres. Úsala para tareas como verificar una base de datos, enviar un correo electrónico o interactuar con una API personalizada. La API de Gemini Live admite llamadas a funciones asíncronas. Para obtener más información, consulta Llamadas a funciones asíncronas con la API de Gemini Live.

El modelo genera una llamada a función, y tu aplicación ejecuta el código y envía los resultados al modelo.

Todas las funciones deben declararse al comienzo de la sesión enviando definiciones de herramientas como parte del mensaje LiveConnectConfig.

Para habilitar las llamadas a funciones, incluye function_declarations en la lista tools del mensaje de configuración:

Python

import asyncio

from google import genai
from google.genai.types import (
    Content,
    LiveConnectConfig,
    Part,
)

# Initialize the client.
client = genai.Client(
    enterprise=True,
    project="GOOGLE_CLOUD_PROJECT",  # Replace with your project ID
    location="LOCATION",  # Replace with your location
)

MODEL_ID = "gemini-3.8-live"


def get_current_weather(location: str) -> str:
    """Example method. Returns the current weather.

    Args:
        location: The city and state, e.g. San Francisco, CA
    """
    weather_map: dict[str, str] = {
        "Boston, MA": "snowing",
        "San Francisco, CA": "foggy",
        "Seattle, WA": "raining",
        "Austin, TX": "hot",
        "Chicago, IL": "windy",
    }
    return weather_map.get(location, "unknown")


async def main():
    config = LiveConnectConfig(
        response_modalities=["AUDIO"],
        tools=[get_current_weather],
    )

    async with client.aio.live.connect(
        model=MODEL_ID,
        config=config,
    ) as session:
        text_input = "Get the current weather in Boston."
        print(f"Input: {text_input}")

        await session.send_realtime_input(text=text_input)
        )

        async for message in session.receive():
            if message.tool_call:
                function_responses = []
                for function_call in message.tool_call.function_calls:
                    print(f"FunctionCall > {function_call}")
                    # Execute the tool and send the response back to the model.
                    result = get_current_weather(**function_call.args)
                    function_responses.append(
                        {
                            "name": function_call.name,
                            "response": {"result": result},
                            "id": function_call.id,
                        }
                    )
                if function_responses:
                    await session.send_tool_response(function_responses=function_responses)


if __name__ == "__main__":
    asyncio.run(main())

Para ver ejemplos del uso de la llamada a función en instrucciones del sistema, consulta el ejemplo de prácticas recomendadas.

Herramientas del Protocolo de contexto del modelo (MCP)

El SDK de IA generativa de Google no ejecuta automáticamente las llamadas a herramientas del Protocolo de contexto del modelo (MCP) en las sesiones de la API de Gemini Live. Para usar las herramientas de MCP en una sesión de la API de Gemini Live, puedes usar uno de los siguientes enfoques:

  • Administra las llamadas a herramientas de MCP directamente: Si usas el SDK de IA generativa de Google directamente, tu aplicación debe administrar la sesión del cliente de MCP, ejecutar llamadas a herramientas cuando lo solicite el modelo y devolver los resultados con send_tool_response.
  • Usa el Kit de desarrollo de agentes (ADK): Usa la clase McpToolset en el ADK, que proporciona integración de MCP integrada para la API de Gemini Live. El ADK descubre automáticamente las herramientas de tu servidor de MCP, convierte sus esquemas en declaraciones de funciones, ejecuta llamadas a herramientas de MCP durante el flujo bidireccional y envía las respuestas de las herramientas al modelo.

Usa herramientas de MCP con ADK

Puedes usar el ADK para conectar herramientas de MCP a la API de Gemini Live siguiendo estos pasos:

  1. Instala el paquete google-adk con el extra mcp:

    pip install "google-adk[mcp]"

  2. Crea una secuencia de comandos llamada live_mcp_example.py que conecte McpToolset a tu servicio de MCP con StreamableHTTPConnectionParams y transmita eventos con runner.run_live().

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • MCP_SERVER_URL: Es la URL de tu servidor de MCP HTTP de transmisión (por ejemplo, http://127.0.0.1:8765/mcp).
    import asyncio
import contextlib
import os

from google.adk.agents import Agent, LiveRequestQueue, RunConfig
from google.adk.agents.run_config import StreamingMode
from google.adk.runners import InMemoryRunner
from google.adk.tools.mcp_tool import McpToolset, StreamableHTTPConnectionParams
from google.genai import types

os.environ.setdefault("GOOGLE_GENAI_USE_ENTERPRISE", "TRUE")
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", "PROJECT_ID")
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "us-central1")

async def main() -> None:
  # 1. Connect to the Streamable HTTP MCP service
  mcp_toolset = McpToolset(
      connection_params=StreamableHTTPConnectionParams(
          url="MCP_SERVER_URL",
      )
  )

  # 2. Create the ADK Agent with a Gemini Live model and the MCP toolset
  agent = Agent(
      name="mcp_live_agent",
      model="gemini-3.8-live",
      instruction="You are a helpful assistant. Use the provided MCP tools when needed.",
      tools=[mcp_toolset],
  )

  runner = InMemoryRunner(agent=agent, app_name="mcp_live_demo")
  session = await runner.session_service.create_session(
      app_name="mcp_live_demo",
      user_id="user_1",
  )

  # 3. Configure bidirectional streaming and send a prompt
  live_request_queue = LiveRequestQueue()
  run_config = RunConfig(
      streaming_mode=StreamingMode.BIDI,
      response_modalities=[types.Modality.AUDIO],
      output_audio_transcription=types.AudioTranscriptionConfig(),
  )

  live_request_queue.send_content(
      types.Content(
          role="user",
          parts=[types.Part.from_text(text="What is the weather in Paris?")],
      )
  )

  # 4. Stream Live events (ADK automatically executes MCP tools)
  awaiting_post_tool_response = False
  saw_function_response = False
  has_model_output = False

  try:
    async with contextlib.aclosing(
        runner.run_live(
            user_id="user_1",
            session_id=session.id,
            live_request_queue=live_request_queue,
            run_config=run_config,
        )
    ) as live_events:
      async for event in live_events:
        for call in event.get_function_calls():
          print(f"[MCP Tool Call] {call.name}({call.args})")
          awaiting_post_tool_response = True
          saw_function_response = False
          has_model_output = False

        for resp in event.get_function_responses():
          print(f"[MCP Tool Response] {resp.name} -> {resp.response}")
          saw_function_response = True

        if event.output_transcription and event.output_transcription.text:
          if not awaiting_post_tool_response or saw_function_response:
            has_model_output = True
            awaiting_post_tool_response = False
          if event.output_transcription.finished:
            print(f"[Transcript] {event.output_transcription.text}")

        # Wait for the final response turn after tool execution completes
        if event.turn_complete:
          if awaiting_post_tool_response or not has_model_output:
            continue
          live_request_queue.close()
          break
  finally:
    await mcp_toolset.close()
    await runner.close()

if __name__ == "__main__":
  asyncio.run(main())

Usa la fundamentación con la Búsqueda de Google cuando quieras que el modelo proporcione respuestas más precisas y fácticas anclándolas a fuentes de información verificables. Úsalo para tareas como buscar en la Web.

A diferencia de la llamada a funciones, la integración del servidor controla la recuperación de información de forma automática.

Para habilitar la fundamentación con la Búsqueda de Google, incluye google_search en la lista tools del mensaje de configuración:

Python

import asyncio

from google import genai
from google.genai.types import (
    Content,
    LiveConnectConfig,
    Part,
)

# Initialize the client.
client = genai.Client(
    enterprise=True,
    project="GOOGLE_CLOUD_PROJECT",  # Replace with your project ID
    location="LOCATION",  # Replace with your location
)

MODEL_ID = "gemini-3.8-live"


async def main():
    config = LiveConnectConfig(
        response_modalities=["AUDIO"],
        tools=[{"google_search": {}}],
    )

    async with client.aio.live.connect(
        model=MODEL_ID,
        config=config,
    ) as session:
        text_input = "What is the current weather in Toronto, Canada?"
        print(f"Input: {text_input}")

        await session.send_realtime_input(text=text_input)

        async for message in session.receive():
            # Consume the messages from the model.
            # In native audio, the model response is in audio format.
            pass


if __name__ == "__main__":
    asyncio.run(main())

Configura el diálogo basado en emociones detectadas

La configuración del diálogo basado en emociones detectadas solo es necesaria para gemini-live-2.5-flash-native-audio. Esta sección no se aplica a gemini-3.8-live.

Cuando se habilita Diálogo Afectivo, el modelo intenta comprender y responder en función del tono de voz y las expresiones emocionales del usuario.

Para habilitar el diálogo basado en emociones detectadas, establece enable_affective_dialog en true en el mensaje de configuración:

Python

config = LiveConnectConfig(
    response_modalities=["AUDIO"],
    enable_affective_dialog=True,
)

Cómo configurar el audio proactivo

La configuración de audio proactiva solo es obligatoria para gemini-live-2.5-flash-native-audio. El audio proactivo se incluye en gemini-3.8-live.

El Audio proactivo te permite controlar cuándo responde el modelo. Por ejemplo, puedes pedirle a Gemini que solo responda cuando se le indique o cuando se hablen de temas específicos. Para ver una demostración en video de Audio proactivo, consulta Gemini LiveAPI Native Audio Preview.

Para habilitar el audio proactivo, configura el campo proactivity en el mensaje de configuración y establece proactive_audio en true:

Python

config = LiveConnectConfig(
    response_modalities=["AUDIO"],
    proactivity=ProactivityConfig(proactive_audio=True),
)

Ejemplo de conversación

A continuación, se muestra un ejemplo de cómo podría ser una conversación con Gemini sobre cocina:

Prompt: "You are an AI assistant in Italian cooking; only chime in when the topic is about Italian cooking."

Speaker A: "I really love cooking!" (No response from Gemini.)

Speaker B: "Oh yes, me too! My favorite is French cuisine." (No response from
Gemini.)

Speaker A: "I really like Italian food; do you know how to make a pizza?"

(Italian cooking topic triggers response from Gemini.)
Gemini Live API: "I'd be happy to help! Here's a recipe for a pizza."

Casos de uso habituales

Cuando usas Audio proactivo, Gemini funciona de la siguiente manera:

  • Responde con una latencia mínima: Gemini responde después de que el usuario termina de hablar, lo que reduce las interrupciones y ayuda a Gemini a no perder el contexto si se produce una interrupción.
  • Evita interrupciones: El Audio proactivo ayuda a Gemini a evitar interrupciones por ruido de fondo o charlas externas, y evita que Gemini responda si se introduce una charla externa durante una conversación.
  • Maneja interrupciones: Si el usuario necesita interrumpir una respuesta de Gemini, el audio proactivo facilita que Gemini haga un backchannel adecuado (es decir, se manejan las interrupciones adecuadas), en lugar de que el usuario use palabras de relleno como eh o um.
  • Escucha audio en conjunto: Gemini puede escuchar un archivo de audio en conjunto que no sea la voz del orador y, luego, responder preguntas sobre ese archivo de audio más adelante en la conversación.

Facturación

Mientras Gemini escucha una conversación, se cobran los tokens de audio de entrada.

En el caso de los tokens de audio de salida, solo se te cobrará cuando Gemini responda. Si Gemini no responde o permanece en silencio, no se te cobrarán los tokens de audio de salida.

Para obtener más información, consulta los precios de la Plataforma de agentes.

¿Qué sigue?

Para obtener más información sobre el uso de la API de Gemini Live, consulta los siguientes recursos: