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 las llamadas a funciones y la fundamentación, y las capacidades de audio en vivo, como el diálogo basado en emociones detectadas y el audio proactivo.

Configura el uso de herramientas

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

Para habilitar una herramienta en particular para su uso en las respuestas que se muestran, 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 las llamadas a funciones o la herramienta retrieval de Gemini Enterprise Agent Platform RAG Engine) 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. Usa esta opción para tareas como consultar 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 se deben declarar 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 de cómo usar las llamadas a funciones en las 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 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 el modelo lo solicite y mostrar los resultados con send_tool_response.
  • Usa el Kit de desarrollo de agentes (ADK): Usa la McpToolset clase 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 la transmisión bidireccional y envía las respuestas de las herramientas al modelo.

Usa herramientas de MCP con el ADK

Puedes usar el ADK para conectar herramientas de MCP a la API de Gemini Live con los siguientes 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 Cloud de Confiance by S3NS proyecto de.
    • MCP_SERVER_URL: Es la URL de tu servidor de MCP HTTP transmisible (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. Usa esta opción para tareas como realizar búsquedas en la Web.

A diferencia de las llamadas 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 el diálogo basado en emociones detectadas, el modelo intenta comprender y responder según el 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,
)

Configura el audio proactivo

La configuración de audio proactivo solo es necesaria 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 solicite o cuando se hablen 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),
)

Conversación de ejemplo

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 se usa el audio proactivo, Gemini se comporta 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 las interrupciones: El audio proactivo ayuda a Gemini a evitar las interrupciones del ruido de fondo o las conversaciones externas, y evita que Gemini responda si se introducen conversaciones externas durante una conversación.
  • Controla las interrupciones: Si el usuario necesita interrumpir durante una respuesta de Gemini, el audio proactivo facilita que Gemini realice un canal secundario adecuado (es decir, se controlan las interrupciones adecuadas), en lugar de que un usuario use muletillas como umm o uhh.
  • Escucha el audio en conjunto: Gemini puede escuchar en conjunto un archivo de audio que no sea la voz del hablante 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 cobra cuando Gemini responde. 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 Agent Platform.

¿Qué sigue?

Para obtener más información sobre el uso de la API de Gemini Live, consulta lo siguiente: