Ferramentas integradas para a API Live

Este guia mostra como usar as ferramentas integradas disponíveis com a API Live para melhorar as interações do modelo. Neste guia, abordamos os seguintes tópicos:

  • Chamada de função:descreve como definir funções personalizadas que o modelo pode chamar para interagir com sistemas externos.
  • Execução de código:explica como ativar o modelo para gerar e executar código Python em tarefas computacionais.
  • Embasamento com a Pesquisa Google:mostra como conectar o modelo à Pesquisa Google para receber respostas com base em informações públicas em tempo real.
  • Embasamento com o mecanismo de RAG da Vertex AI:detalhes sobre como embasar respostas do modelo usando suas próprias fontes de dados particulares.
  • Áudio nativo:aborda recursos avançados de áudio, incluindo respostas proativas e compreensão de pistas emocionais.

Para ativar uma ferramenta, inclua-a na lista tools ao inicializar o modelo. A tabela a seguir oferece uma comparação de alto nível das ferramentas disponíveis.

Ferramenta Descrição Caso de uso
Chamadas de função Permite que o modelo chame funções externas definidas por você. O modelo retorna o nome da função e os argumentos a serem usados. Integração com APIs, bancos de dados ou outros serviços externos, por exemplo, para verificar a previsão do tempo ou reservar um voo.
Execução de código Permite que o modelo gere e execute código Python em um ambiente isolado para realizar cálculos ou tarefas. Resolver problemas de matemática, fazer análise de dados ou qualquer tarefa que possa ser realizada com um pequeno script Python.
Embasamento com a Pesquisa Google Conecta o modelo à Pesquisa Google para embasar as respostas em informações públicas e atualizadas da Web. Essa é uma forma de embasamento. Responder a perguntas sobre eventos ou temas recentes em que as informações atuais são importantes.
Embasamento com o mecanismo de RAG da Vertex AI Conecta o modelo às suas fontes de dados particulares ou selecionadas usando a Geração Aumentada de Recuperação (RAG). Criar um chatbot que responda a perguntas com base na documentação interna ou nos manuais de produtos da sua empresa.

Modelos compatíveis

É possível usar a API Live com os seguintes modelos:

Versão do modelo Nível de disponibilidade
gemini-live-2.5-flash Disponibilidade geral particular*
gemini-live-2.5-flash-preview-native-audio Pré-lançamento público

* Para solicitar acesso, entre em contato com o representante da sua Conta do Google.

Chamadas de função

Use a chamada de função para criar uma descrição de uma função e transmita essa descrição para o modelo em uma solicitação. A resposta do modelo inclui o nome de uma função que corresponde à descrição e os argumentos para chamá-la.

Declare todas as funções 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:

Python

import asyncio
from google import genai
from google.genai import types

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-live-2.5-flash"

# Simple function definitions
turn_on_the_lights = {"name": "turn_on_the_lights"}
turn_off_the_lights = {"name": "turn_off_the_lights"}

tools = [{"function_declarations": [turn_on_the_lights, turn_off_the_lights]}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Turn on the lights please"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            elif chunk.tool_call:
                function_responses = []
                for fc in tool_call.function_calls:
                    function_response = types.FunctionResponse(
                        name=fc.name,
                        response={ "result": "ok" } # simple, hard-coded function response
                    )
                    function_responses.append(function_response)

                await session.send_tool_response(function_responses=function_responses)


if __name__ == "__main__":
    asyncio.run(main())

Python

Execução de código

É possível usar a execução de código com a API Live para gerar e executar código Python diretamente. Para ativar a execução de código nas suas respostas, inclua code_execution na lista tools:

Python

import asyncio
from google import genai
from google.genai import types


client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-live-2.5-flash"

tools = [{'code_execution': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "Compute the largest prime palindrome under 100000."
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)
            
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                      if part.executable_code is not None:
                        print(part.executable_code.code)

                      if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

if __name__ == "__main__":
    asyncio.run(main())

Você pode usar o Fundamentação com a Pesquisa Google com a API Live incluindo google_search na lista tools:

Python

import asyncio
from google import genai
from google.genai import types

client = genai.Client(
    vertexai=True,
    project=GOOGLE_CLOUD_PROJECT,
    location=GOOGLE_CLOUD_LOCATION,
)
model = "gemini-live-2.5-flash"


tools = [{'google_search': {}}]
config = {"response_modalities": ["TEXT"], "tools": tools}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        prompt = "When did the last Brazil vs. Argentina soccer match happen?"
        await session.send_client_content(turns={"parts": [{"text": prompt}]})

        async for chunk in session.receive():
            if chunk.server_content:
                if chunk.text is not None:
                    print(chunk.text)

                # The model might generate and execute Python code to use Search
                model_turn = chunk.server_content.model_turn
                if model_turn:
                    for part in model_turn.parts:
                        if part.executable_code is not None:
                        print(part.executable_code.code)

                        if part.code_execution_result is not None:
                        print(part.code_execution_result.output)

if __name__ == "__main__":
    asyncio.run(main())

Embasamento com o mecanismo RAG da Vertex AI (prévia)

É possível embasar as respostas do modelo nas suas fontes de dados particulares conectando a API em tempo real ao mecanismo RAG da Vertex AI. Para ativar o embasamento com o mecanismo de RAG da Vertex AI, configure a ferramenta retrieval com os detalhes do VertexRagStore:

Python

from google import genai
from google.genai import types
from google.genai.types import (Content, LiveConnectConfig, HttpOptions, Modality, Part)
from IPython import display

PROJECT_ID=YOUR_PROJECT_ID
LOCATION=YOUR_LOCATION
TEXT_INPUT=YOUR_TEXT_INPUT
MODEL_NAME="gemini-live-2.5-flash"

client = genai.Client(
   vertexai=True,
   project=PROJECT_ID,
   location=LOCATION,
)

rag_store=types.VertexRagStore(
   rag_resources=[
       types.VertexRagStoreRagResource(
           rag_corpus=  # Use memory corpus if you want to store context.
       )
   ],
   # Set `store_context` to true to allow Live API sink context into your memory corpus.
   store_context=True
)

async with client.aio.live.connect(
   model=MODEL_NAME,
   config=LiveConnectConfig(response_modalities=[Modality.TEXT],
                            tools=[types.Tool(
                                retrieval=types.Retrieval(
                                    vertex_rag_store=rag_store))]),
) as session:
   text_input=TEXT_INPUT
   print("> ", text_input, "\n")
   await session.send_client_content(
       turns=Content(role="user", parts=[Part(text=text_input)])
   )

   async for message in session.receive():
       if message.text:
           display.display(display.Markdown(message.text))
           continue

Para mais informações, consulte Usar o mecanismo de RAG da Vertex AI na API Gemini Live.

(Prévia pública) Áudio nativo

O Gemini 2.5 Flash com a API Live introduz recursos de áudio nativos, aprimorando os recursos padrão da API Live. O áudio nativo oferece interações de voz mais ricas e naturais com 30 vozes em HD em 24 idiomas. Ele também inclui dois novos recursos exclusivos do áudio nativo: Áudio proativo e Diálogo afetivo.

Usar o áudio proativo

Com o áudio proativo, o modelo responde apenas quando é relevante. Quando ativado, o modelo gera transcrições de texto e respostas de áudio de forma proativa, mas apenas para consultas direcionadas ao dispositivo. Consultas que não são direcionadas a dispositivos são ignoradas.

Para usar o Proactive Audio, 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),
)

Usar a computação afetiva

O diálogo afetivo permite que os modelos que usam áudio nativo da API Live entendam melhor e respondam adequadamente às expressões emocionais dos usuários, levando a conversas mais sutis.

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

Mais informações

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