O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Configurar recursos do Gemini

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 em tempo real, como diálogo afetivo e áudio proativo.

Configurar o uso de ferramentas

Várias ferramentas são compatíveis com várias versões de modelos compatíveis com a 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 nas respostas retornadas, inclua o nome dela na lista tools ao inicializar o modelo. As seções a seguir mostram exemplos de como usar cada uma das ferramentas integradas no seu código.

Importante:a API Gemini não permite combinar ferramentas de pesquisa (como googleSearch) com ferramentas que não são de pesquisa (como chamadas de função ou a ferramenta de mecanismo RAG da Gemini Enterprise Agent Platform retrieval) 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 a chamada 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 Chamada de função assíncrona com a API Gemini Live.

O modelo gera uma chamada de função, e seu aplicativo executa o código e envia os resultados de volta para o 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 a chamada 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 ver exemplos de como usar a chamada 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 as 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ê usa o SDK de IA Generativa do Google diretamente, seu aplicativo precisa gerenciar a sessão do cliente MCP, executar chamadas de ferramentas quando solicitado pelo modelo e retornar os resultados usando send_tool_response.
Use o Kit de Desenvolvimento de Agente (ADK): use a classe McpToolset no ADK, que oferece integração integrada do MCP para a API Gemini Live. O ADK descobre automaticamente as ferramentas do seu 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 volta ao modelo.

Usar ferramentas do MCP com o ADK

Você pode usar o ADK para conectar as ferramentas do MCP à API Gemini Live seguindo estas etapas:

Instale o pacote google-adk com o extra mcp:
```
pip install "google-adk[mcp]"
```

Crie um script chamado live_mcp_example.py que conecte McpToolset ao serviço MCP usando StreamableHTTPConnectionParams e transmita eventos usando runner.run_live().

Substitua:

PROJECT_ID: o ID do projeto Google Cloud .
MCP_SERVER_URL: o URL do servidor HTTP MCP do Streamable (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 o 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 para tarefas como pesquisar na Web.

Ao contrário da chamada de função, a integração do lado do servidor processa a recuperação de informações automaticamente.

Para ativar o embasamento com a Pesquisa Google, inclua google_search na lista tools da 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 a computação afetiva

A configuração de diálogo afetivo é necessária apenas para gemini-live-2.5-flash-native-audio. Esta seção não se aplica ao gemini-3.8-live.

Quando o Diálogo afetivo está ativado, 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 proativa de áudio só é necessária para gemini-live-2.5-flash-native-audio. O áudio proativo está incluído no gemini-3.8-live.

Com o áudio proativo, você controla quando o modelo responde. Por exemplo, você pode pedir para o Gemini responder apenas quando solicitado ou quando assuntos específicos forem discutidos. Para ver uma demonstração em vídeo do áudio proativo, consulte 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 seria uma conversa com o Gemini sobre culinária:

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 faz o seguinte:

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 acontecer.
Evita interrupções: o áudio proativo ajuda o Gemini a evitar interrupções causadas por ruídos de fundo ou conversas externas e impede que ele responda se uma conversa externa for iniciada durante uma conversa.
Lida com interrupções: se o usuário precisar interromper uma resposta do Gemini, o áudio proativo facilita a resposta adequada do Gemini (ou seja, as interrupções adequadas são processadas), em vez de usar palavras de preenchimento como hum ou ãh.
Ouve áudio em conjunto: o Gemini pode ouvir um arquivo de áudio que não é a voz do falante e responder a perguntas sobre ele mais tarde 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, a cobrança só é feita quando o Gemini responde. Se o Gemini não responder ou ficar em silêncio, não haverá cobrança pelos tokens de áudio de saída.

Para mais informações, consulte Preços da Agent Platform.

A seguir

Para mais informações sobre como usar a API Gemini Live, consulte:

Configurar recursos do Gemini Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Configurar o uso de ferramentas

Chamadas de função

Python

Ferramentas do Protocolo de Contexto de Modelo (MCP)

Usar ferramentas do MCP com o ADK

Embasamento com a Pesquisa Google

Python

Configurar a computação afetiva

Python

Configurar o áudio proativo

Python

Casos de uso comuns

Faturamento

A seguir

Configurar recursos do Gemini