Configurer les fonctionnalités Gemini

Ce document explique comment configurer différentes fonctionnalités des modèles Gemini lorsque vous utilisez l'API Gemini Live. Vous pouvez configurer l'utilisation d'outils tels que l'appel de fonctions et l'ancrage, ainsi que les fonctionnalités audio en direct telles que le dialogue affectif et l'audio proactif.

Configurer l'utilisation des outils

Plusieurs outils sont compatibles avec différentes versions des modèles compatibles avec l'API Gemini Live, y compris :

Pour activer un outil spécifique dans les réponses renvoyées, incluez son nom dans la liste tools lorsque vous initialisez le modèle. Les sections suivantes fournissent des exemples d'utilisation de chacun des outils intégrés dans votre code.

Important : L'API Gemini ne permet pas de combiner des outils de recherche (comme googleSearch) avec des outils non liés à la recherche (comme l'appel de fonction ou l'outil retrieval du moteur RAG Gemini Enterprise Agent Platform) dans la même requête de configuration. Plusieurs outils ne sont acceptés que s'il s'agit d'outils de recherche.

Appel de fonction

Utilisez l'appel de fonction lorsque vous souhaitez que le modèle interagisse avec des systèmes ou des API externes que vous gérez. Utilisez-le pour des tâches telles que la vérification d'une base de données, l'envoi d'un e-mail ou l'interaction avec une API personnalisée. L'API Gemini Live est compatible avec les appels de fonction asynchrones. Pour en savoir plus, consultez Appel de fonction asynchrone avec l'API Gemini Live.

Le modèle génère un appel de fonction, et votre application exécute le code et renvoie les résultats au modèle.

Toutes les fonctions doivent être déclarées au début de la session en envoyant des définitions d'outils dans le message LiveConnectConfig.

Pour activer l'appel de fonction, incluez function_declarations dans la liste tools du message de configuration :

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

Pour obtenir des exemples d'utilisation de l'appel de fonction dans les instructions système, consultez l'exemple de bonnes pratiques.

Outils MCP (Model Context Protocol)

Le SDK Google Gen AI n'exécute pas automatiquement les appels d'outils MCP (Model Context Protocol) dans les sessions de l'API Gemini Live. Pour utiliser les outils MCP dans une session de l'API Gemini Live, vous pouvez utiliser l'une des approches suivantes :

  • Gérer directement les appels d'outils MCP : si vous utilisez directement le SDK Google Gen AI, votre application doit gérer la session client MCP, exécuter les appels d'outils lorsque le modèle le demande et renvoyer les résultats à l'aide de send_tool_response.
  • Utilisez l'Agent Development Kit (ADK) : utilisez la classe McpToolset dans ADK, qui fournit une intégration MCP intégrée pour l'API Gemini Live. ADK découvre automatiquement les outils de votre serveur MCP, convertit leurs schémas en déclarations de fonctions, exécute les appels d'outils MCP pendant le flux bidirectionnel et renvoie les réponses des outils au modèle.

Utiliser les outils MCP avec ADK

Vous pouvez utiliser l'ADK pour connecter les outils MCP à l'API Gemini Live en suivant les étapes ci-dessous :

  1. Installez le package google-adk avec l'extra mcp :

    pip install "google-adk[mcp]"

  2. Créez un script nommé live_mcp_example.py qui connecte McpToolset à votre service MCP à l'aide de StreamableHTTPConnectionParams et diffuse les événements à l'aide de runner.run_live().

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet Google Cloud .
    • MCP_SERVER_URL : URL de votre serveur HTTP MCP Streamable (par exemple, 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())

Utilisez l'ancrage avec la recherche Google lorsque vous souhaitez que le modèle fournisse des réponses plus précises et factuelles en les ancrant à des sources d'information vérifiables. Utilisez-le pour des tâches telles que la recherche sur le Web.

Contrairement à l'appel de fonction, l'intégration côté serveur gère automatiquement la récupération des informations.

Pour activer l'ancrage avec la recherche Google, incluez google_search dans la liste tools du message de configuration :

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

Configurer le dialogue affectif

La configuration du dialogue affectif n'est requise que pour gemini-live-2.5-flash-native-audio. Cette section ne s'applique pas à gemini-3.8-live.

Lorsque l'option Dialogue affectif est activée, le modèle tente de comprendre et de répondre en fonction du ton de voix et des expressions émotionnelles de l'utilisateur.

Pour activer le dialogue affectif, définissez enable_affective_dialog sur true dans le message de configuration :

Python

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

Configurer l'audio proactif

La configuration audio proactive n'est requise que pour gemini-live-2.5-flash-native-audio. L'audio proactif est inclus dans gemini-3.8-live.

L'audio proactif vous permet de contrôler le moment où le modèle répond. Par exemple, vous pouvez demander à Gemini de ne répondre que lorsqu'il est sollicité ou lorsque des sujets spécifiques sont abordés. Pour voir une démonstration vidéo de l'audio proactif, consultez Aperçu de l'audio natif de l'API Gemini Live.

Pour activer l'audio proactif, configurez le champ proactivity dans le message de configuration et définissez proactive_audio sur true :

Python

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

Exemple de conversation

Voici un exemple de conversation avec Gemini sur la cuisine :

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."

Cas d'utilisation courants

Lorsque vous utilisez l'audio proactif, Gemini procède comme suit :

  • Réponse avec une latence minimale : Gemini répond une fois que l'utilisateur a fini de parler, ce qui réduit les interruptions et permet à Gemini de ne pas perdre le contexte en cas d'interruption.
  • Évite les interruptions : l'audio proactif aide Gemini à éviter les interruptions dues au bruit de fond ou aux conversations externes, et empêche Gemini de répondre si des conversations externes sont introduites pendant une conversation.
  • Gère les interruptions : si l'utilisateur doit interrompre Gemini pendant une réponse, l'audio proactif permet à Gemini de réagir de manière appropriée (c'est-à-dire de gérer les interruptions appropriées), plutôt que si l'utilisateur utilise des mots de remplissage tels que euh ou hum.
  • Écoute conjointe de fichiers audio : Gemini peut écouter conjointement un fichier audio qui n'est pas la voix de l'interlocuteur, puis répondre à des questions sur ce fichier audio plus tard dans la conversation.

Facturation

Des jetons audio d'entrée sont facturés lorsque Gemini écoute une conversation.

Pour les jetons audio de sortie, vous n'êtes facturé que lorsque Gemini répond. Si Gemini ne répond pas ou reste silencieux, aucun jeton audio de sortie ne vous sera facturé.

Pour en savoir plus, consultez Tarifs d'Agent Platform.

Étapes suivantes

Pour en savoir plus sur l'utilisation de l'API Gemini Live, consultez les ressources suivantes :