Configurare le funzionalità di Gemini

Questo documento mostra come configurare varie funzionalità dei modelli Gemini quando utilizzi l'API Gemini Live. Puoi configurare l'utilizzo degli strumenti, come la chiamata di funzioni e il grounding, e le funzionalità audio live, come il dialogo empatico e l'audio proattivo.

Configurare l'utilizzo degli strumenti

Diversi strumenti sono compatibili con varie versioni dei modelli supportati dall'API Gemini Live, tra cui:

Per attivare un determinato strumento per l'utilizzo nelle risposte restituite, includi il nome dello strumento nell'elenco tools quando inizializzi il modello. Le sezioni seguenti forniscono esempi di come utilizzare ciascuno degli strumenti integrati nel codice.

Importante: l'API Gemini non supporta la combinazione di strumenti di ricerca (come googleSearch) con strumenti non di ricerca (come la chiamata di funzioni o lo strumento retrieval del motore RAG di Gemini Enterprise Agent Platform) nella stessa richiesta di configurazione. Sono supportati più strumenti solo se sono tutti strumenti di ricerca.

Chiamata di funzione

Utilizza la chiamata di funzioni quando vuoi che il modello interagisca con sistemi o API esterni che gestisci. Utilizza questa funzionalità per attività come il controllo di un database, l'invio di un'email o l'interazione con un'API personalizzata. L'API Gemini Live supporta la chiamata di funzioni asincrona. Per saperne di più, consulta Chiamata di funzioni asincrona con l'API Gemini Live.

Il modello genera una chiamata di funzione e l'applicazione esegue il codice e invia i risultati al modello.

Tutte le funzioni devono essere dichiarate all'inizio della sessione inviando le definizioni degli strumenti come parte del messaggio LiveConnectConfig.

Per attivare la chiamata di funzioni, includi function_declarations nell'elenco tools nel messaggio di configurazione:

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

Per esempi di utilizzo della chiamata di funzioni nelle istruzioni di sistema, consulta l' esempio di best practice.

Strumenti Model Context Protocol (MCP)

L'SDK Google Gen AI non esegue automaticamente le chiamate degli strumenti Model Context Protocol (MCP) nelle sessioni dell'API Gemini Live. Per utilizzare gli strumenti MCP in una sessione dell'API Gemini Live, puoi utilizzare uno dei seguenti approcci:

  • Gestisci direttamente le chiamate degli strumenti MCP: se utilizzi direttamente l'SDK Google Gen AI , l'applicazione deve gestire la sessione del client MCP, eseguire le chiamate degli strumenti quando richieste dal modello e restituire i risultati utilizzando send_tool_response.
  • Utilizza l'Agent Development Kit (ADK): utilizza la McpToolset classe in ADK, che fornisce l'integrazione MCP integrata per l'API Gemini Live. ADK rileva automaticamente gli strumenti dal server MCP, converte i relativi schemi in dichiarazioni di funzioni, esegue le chiamate degli strumenti MCP durante lo stream bidirezionale e invia le risposte degli strumenti al modello.

Utilizzare gli strumenti MCP con ADK

Puoi utilizzare ADK per collegare gli strumenti MCP all'API Gemini Live seguendo questi passaggi:

  1. Installa il pacchetto google-adk con l'extra mcp:

    pip install "google-adk[mcp]"

  2. Crea uno script denominato live_mcp_example.py che connette McpToolset al tuo servizio MCP utilizzando StreamableHTTPConnectionParams e trasmette gli eventi utilizzando runner.run_live().

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo Google Cloud ID progetto.
    • MCP_SERVER_URL: l'URL del server MCP HTTP Streamable (ad esempio, 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())

Utilizza Grounding con la Ricerca Google quando vuoi che il modello fornisca risposte più accurate e oggettive ancorandole a fonti di informazioni verificabili. Utilizza questa funzionalità per attività come la ricerca sul web.

A differenza della chiamata di funzioni, l'integrazione lato server gestisce automaticamente il recupero delle informazioni.

Per attivare Grounding con la Ricerca Google, includi google_search nell'elenco tools nel messaggio di configurazione:

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

Configurare il dialogo empatico

La configurazione del dialogo empatico è obbligatoria solo per gemini-live-2.5-flash-native-audio. Questa sezione non si applica a gemini-3.8-live.

Quando il dialogo empatico è attivato, il modello tenta di comprendere e rispondere in base al tono di voce e alle espressioni emotive dell'utente.

Per attivare il dialogo empatico, imposta enable_affective_dialog su true nel messaggio di configurazione:

Python

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

Configurare l'audio proattivo

La configurazione dell'audio proattivo è obbligatoria solo per gemini-live-2.5-flash-native-audio. L'audio proattivo è incluso in gemini-3.8-live.

L'audio proattivo ti consente di controllare quando il modello risponde. Ad esempio, puoi chiedere a Gemini di rispondere solo quando viene richiesto o quando vengono discussi argomenti specifici. Per vedere una dimostrazione video dell'audio proattivo, consulta Gemini LiveAPI Native Audio Preview.

Per attivare l'audio proattivo, configura il campo proactivity nel messaggio di configurazione e imposta proactive_audio su true:

Python

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

Esempio di conversazione

Di seguito è riportato un esempio di come potrebbe essere una conversazione con Gemini sulla cucina:

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

Casi d'uso comuni

Quando utilizzi l'audio proattivo, Gemini si comporta nel seguente modo:

  • Risponde con una latenza minima: Gemini risponde dopo che l'utente ha finito di parlare, riducendo le interruzioni e aiutando Gemini a non perdere il contesto in caso di interruzione.
  • Evita le interruzioni: l'audio proattivo aiuta Gemini a evitare le interruzioni dovute al rumore di sottofondo o alle chiacchiere esterne e impedisce a Gemini di rispondere se vengono introdotte chiacchiere esterne durante una conversazione.
  • Gestisce le interruzioni: se l'utente deve interrompere una risposta di Gemini, l'audio proattivo facilita la gestione appropriata del canale di comunicazione secondario da parte di Gemini (ovvero le interruzioni appropriate vengono gestite), anziché se un utente utilizza intercalari come umm o uhh.
  • Ascolta l'audio: Gemini può ascoltare un file audio diverso dalla voce dell'utente e rispondere alle domande su quel file audio in un secondo momento della conversazione.

Fatturazione

Mentre Gemini ascolta una conversazione, vengono addebitati i token audio di input.

Per i token audio di output, ti viene addebitato un costo solo quando Gemini risponde. Se Gemini non risponde o rimane in silenzio, non vengono addebitati i token audio di output.

Per saperne di più, consulta i prezzi di Agent Platform.

Passaggi successivi

Per saperne di più sull'utilizzo dell'API Gemini Live, consulta: