Este documento mostra como configurar vários recursos dos modelos do Gemini ao usar a API Gemini Live. É possível configurar o uso de ferramentas, como chamada de função e embasamento, e recursos de áudio ao vivo, como computação afetiva e áudio proativo.
Configurar o uso de ferramentas
Várias ferramentas são compatíveis com diferentes versões de modelos com suporte à API Gemini Live, incluindo:
- Chamadas de função
- Ferramentas do Protocolo de Contexto de Modelo (MCP)
- Embasamento com a Pesquisa Google
Para ativar uma ferramenta específica para uso em respostas retornadas, inclua o nome dela na lista tools ao inicializar o modelo. As seções a seguir fornecem exemplos de como usar cada uma das ferramentas integradas no código.
Importante:a API Gemini não oferece suporte à combinação de ferramentas de pesquisa (como googleSearch) com ferramentas que não são de pesquisa (como chamadas de função ou a ferramenta retrieval do mecanismo de RAG da Gemini Enterprise Agent Platform) na mesma solicitação de configuração. Várias ferramentas só são compatíveis quando todas são ferramentas de pesquisa.
Chamadas de função
Use chamadas de função quando quiser que o modelo interaja com sistemas ou APIs externos que você gerencia. Use isso para tarefas como verificar um banco de dados, enviar um e-mail ou interagir com uma API personalizada. A API Gemini Live oferece suporte a chamadas de função assíncronas. Para mais informações, consulte Chamadas de função assíncronas com a API Gemini Live.
O modelo gera uma chamada de função, e o aplicativo executa o código e envia os resultados de volta ao modelo.
Todas as funções precisam ser declaradas no início da sessão enviando definições de ferramentas como parte da mensagem LiveConnectConfig.
Para ativar as chamadas de função, inclua function_declarations na lista tools na mensagem de configuração:
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 exemplos de uso de chamadas de função em instruções do sistema, consulte o exemplo de práticas recomendadas.
Ferramentas do Protocolo de Contexto de Modelo (MCP)
O SDK de IA generativa do Google não executa automaticamente chamadas de ferramentas do Protocolo de Contexto de Modelo (MCP) em sessões da API Gemini Live. Para usar ferramentas do MCP em uma sessão da API Gemini Live, use uma das seguintes abordagens:
- Gerenciar chamadas de ferramentas do MCP diretamente: se você usar o SDK de IA generativa do Google
diretamente, o aplicativo precisará gerenciar a sessão do cliente do MCP, executar chamadas de ferramentas quando solicitado pelo modelo e retornar os resultados usando
send_tool_response. - Usar o Kit de Desenvolvimento de Agente (ADK): use a
McpToolsetclasse no ADK, que oferece integração do MCP integrada para a API Gemini Live. O ADK descobre automaticamente as ferramentas do servidor MCP, converte os esquemas delas em declarações de função, executa chamadas de ferramentas do MCP durante o fluxo bidirecional e envia as respostas de ferramentas de volta ao modelo.
Usar ferramentas do MCP com o ADK
Você pode usar o ADK para conectar ferramentas do MCP à API Gemini Live seguindo estas etapas:
Instale o pacote
google-adkcom o extramcp:pip install "google-adk[mcp]"Crie um script chamado
live_mcp_example.pyque conectaMcpToolsetao serviço do MCP usandoStreamableHTTPConnectionParamse transmite eventos usandorunner.run_live().Substitua:
PROJECT_ID: o ID do Cloud de Confiance by S3NS projeto.MCP_SERVER_URL: o URL do servidor MCP HTTP transmissível (por exemplo,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())
Embasamento com a Pesquisa Google
Use Embasamento com a Pesquisa Google quando quiser que o modelo forneça respostas mais precisas e factuais, ancorando-as em fontes de informações verificáveis. Use isso para tarefas como pesquisar na Web.
Ao contrário das chamadas de função, a integração do lado do servidor processa a recuperação de informações automaticamente.
Para ativar o recurso de Embasamento com a Pesquisa Google, inclua google_search na lista tools na mensagem de configuração:
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())
Configurar o diálogo afetivo
A configuração do diálogo afetivo só é necessária para gemini-live-2.5-flash-native-audio. Esta seção não se aplica a gemini-3.8-live.
Quando a computação afetiva está ativada, o modelo tenta entender e responder com base no tom de voz e nas expressões emocionais do usuário.
Para ativar o diálogo afetivo, defina enable_affective_dialog como true na mensagem de configuração:
Python
config = LiveConnectConfig( response_modalities=["AUDIO"], enable_affective_dialog=True, )
Configurar o áudio proativo
A configuração de áudio proativo só é necessária para gemini-live-2.5-flash-native-audio. O áudio proativo está incluído em gemini-3.8-live.
O áudio proativo permite controlar quando o modelo responde. Por exemplo, você pode pedir ao Gemini para responder apenas quando solicitado ou quando temas específicos forem discutidos. Para ver uma demonstração em vídeo do áudio proativo, consulte a prévia do áudio nativo da API Gemini Live.
Para ativar o áudio proativo, configure o campo proactivity na mensagem de configuração e defina proactive_audio como true:
Python
config = LiveConnectConfig( response_modalities=["AUDIO"], proactivity=ProactivityConfig(proactive_audio=True), )
Exemplo de conversa
Confira um exemplo de como uma conversa com o Gemini sobre culinária pode ser:
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 comuns
Ao usar o áudio proativo, o Gemini funciona da seguinte maneira:
- Responde com latência mínima: o Gemini responde depois que o usuário termina de falar, reduzindo interrupções e ajudando o Gemini a não perder o contexto se uma interrupção ocorrer.
- Evita interrupções: o áudio proativo ajuda o Gemini a evitar interrupções de ruídos de fundo ou conversas externas e impede que o Gemini responda se conversas externas forem introduzidas durante uma conversa.
- Processa interrupções: se o usuário precisar interromper durante uma resposta do Gemini, o áudio proativo facilita o backchannel adequado do Gemini (ou seja, interrupções adequadas são processadas), em vez de um usuário usar palavras desnecessárias, como umm ou uhh.
- Ouve o áudio: o Gemini pode ouvir um arquivo de áudio que não seja a voz do locutor e, posteriormente, responder a perguntas sobre esse arquivo de áudio na conversa.
Faturamento
Enquanto o Gemini ouve uma conversa, os tokens de áudio de entrada são cobrados.
Para tokens de áudio de saída, você só será cobrado quando o Gemini responder. Se o Gemini não responder ou ficar em silêncio, não haverá cobrança dos tokens de áudio de saída.
Para mais informações, consulte os preços da Agent Platform.
A seguir
Para mais informações sobre como usar a API Gemini Live, consulte: