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 le chiamate di funzione e la fondatezza, 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 particolare 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 RAG Engine di Gemini Enterprise Agent Platform retrieval) nella stessa richiesta di configurazione. Sono supportati più strumenti solo se sono tutti strumenti di ricerca.

Chiamata di funzione

Utilizza le chiamate di funzione quando vuoi che il modello interagisca con sistemi esterni o API che gestisci. Utilizzalo per attività come controllare un database, inviare un'email o interagire 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 la tua applicazione esegue il codice e restituisce 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 abilitare la chiamata di funzione, 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 funzione 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 agli 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 agli strumenti MCP: se utilizzi direttamente l'SDK Google Gen AI, la tua applicazione deve gestire la sessione client MCP, eseguire le chiamate agli strumenti quando richieste dal modello e restituire i risultati utilizzando send_tool_response.
  • Utilizza l'Agent Development Kit (ADK): utilizza la classe McpToolset in ADK, che fornisce l'integrazione MCP integrata per l'API Gemini Live. L'ADK rileva automaticamente gli strumenti dal server MCP, converte i relativi schemi in dichiarazioni di funzioni, esegue chiamate agli strumenti MCP durante il flusso bidirezionale e invia le risposte degli strumenti al modello.

Utilizzare gli strumenti MCP con ADK

Puoi utilizzare l'ADK per connettere 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 in streaming gli eventi utilizzando runner.run_live().

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto Google Cloud .
    • MCP_SERVER_URL: l'URL del server HTTP MCP di 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. Utilizzalo per attività come la ricerca sul web.

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

Per attivare il 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 Dialogo affettivo è 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 audio proattiva è 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 richiesto o quando vengono trattati argomenti specifici. Per vedere una dimostrazione video di Proactive Audio, guarda Anteprima audio nativa dell'API Gemini Live.

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

Conversazione di esempio

Di seguito è riportato un esempio di 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 interruzioni: l'audio proattivo aiuta Gemini a evitare interruzioni dovute a rumore di fondo o 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, Proactive Audio consente a Gemini di gestire in modo appropriato il canale secondario (ovvero le interruzioni appropriate), anziché se un utente utilizza parole di riempimento come ehm o uhm.
  • Ascolta l'audio: Gemini può ascoltare un file audio che non è la voce dell'oratore 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, l'addebito viene effettuato solo quando Gemini risponde. Se Gemini non risponde o rimane in silenzio, non vengono addebitati token audio di output.

Per saperne di più, consulta la sezione Prezzi di Agent Platform.

Passaggi successivi

Per ulteriori informazioni sull'utilizzo dell'API Gemini Live, consulta: