Dê habilidades reais ao seu agente de voz com tool calling

Ver no idioma original →

Autoria: Google Cloud Tech · Assistir no YouTube

Vídeo de autoria do canal indicado, não da IANIA; todos os direitos pertencem ao criador. Transcrição, resumo e tradução gerados automaticamente; o conteúdo no idioma original é preservado na versão em idioma original.

Idioma original: inglês

Vídeo original: Give your voice AI agent real abilities (tool calling) · Canal: Google Cloud Tech · 09:23 · Assistir no YouTube

Tópicos: Agentes de IA, Ferramentas de desenvolvimento com IA

Resumo

O vídeo explica como dar habilidades a um agente de voz Gemini Live por meio de tool calling sem interromper a conversa. Apresenta o ciclo de declarar ferramentas, decidir, executar e retornar, além de comparar a implementação com o SDK bruto e com ADK. Também explica duas regras para manter a experiência fluida: as ferramentas devem retornar rapidamente e políticas podem ser aplicadas em um callback antes da execução. Por fim, mostra como essas práticas preparam o agente para realizar ações mais lentas, como controlar um navegador.

Pontos-chave

• Uma ferramenta é uma ação descrita que o modelo pode solicitar, mas é o código da aplicação que a executa.
• O ciclo de tool calling tem quatro etapas: declarar, decidir, executar e retornar.
• Descrições claras ajudam o modelo a escolher a ferramenta correta.
• Com o SDK bruto do Google GenAI, o desenvolvedor implementa o ciclo; com ADK, o framework cuida desse fluxo.
• No ADK, uma função Python e sua docstring podem definir uma ferramenta.
• Ferramentas em conversas ao vivo devem retornar imediatamente para evitar que a voz do agente fique em silêncio.
• O callback before_tool_callback pode observar chamadas, bloqueá-las ou reescrever seus argumentos.
• Políticas como restrições de horário podem ser aplicadas antes que uma ferramenta seja executada.

Capítulos

Início	Capítulo	Resumo
00:00	Demonstração e visão geral	O vídeo apresenta um agente de voz que escolhe músicas e descreve os três tópicos abordados.
01:01	O ciclo de tool calling	A apresentadora explica como declarar ferramentas, receber a decisão do modelo, executar o código e retornar o resultado.
03:09	Implementações com o SDK e ADK	O vídeo compara a implementação manual com Google GenAI à definição de funções Python gerenciadas pelo ADK.
05:13	Regras para conversas ao vivo	A apresentadora recomenda ferramentas rápidas e mostra como usar before_tool_callback para aplicar políticas antes da execução.
08:22	Resumo e próximos passos	O vídeo recapitula o ciclo, as duas formas de criar ferramentas e as regras para manter a conversa fluida.

Citações

O modelo não consegue executar nada. Ele pede. O código age. — 02:05

Se o modelo chamar a ferramenta errada, não comece culpando o modelo. Comece corrigindo a descrição. — 02:36

Em uma conversa por voz, o silêncio não parece carregamento. Parece que algo quebrou. — 05:46

Mantenha as ferramentas instantâneas. Coloque as políticas no callback. — 08:22

Conceitos e entidades

• Gemini Live (ferramenta): Experiência de conversa ao vivo usada no vídeo para demonstrar um agente de voz com ferramentas.
• tool calling (conceito): Mecanismo em que o modelo solicita uma ação e o código da aplicação a executa.
• Google GenAI (ferramenta): SDK apresentado como uma forma de declarar ferramentas e implementar manualmente o ciclo de chamadas.
• ADK (ferramenta): Framework que pode extrair o esquema de uma função Python e cuidar do fluxo de execução e retorno das ferramentas.
• before_tool_callback (conceito): Ponto de verificação no ADK que permite observar, bloquear ou alterar chamadas antes de executar a ferramenta.

Tradução completa (pt-BR)

00:00 ANNIE: Oi, eu sou Annie. Hoje você vai aprender a dar habilidades a um agent do Gemini Live com tool calling, mas não a versão de solicitação e resposta que você já viu centenas de vezes. Esta é a versão ao vivo. O agent age no meio da conversa, e a conversa não é interrompida. Veja como funciona. Ei, Mira, pode tocar algo de dreampop? MIRA: Parece perfeito. [MÚSICA TOCANDO] ANNIE: Pule esta, por favor.

00:30 MIRA: Claro. Vamos encontrar outra coisa. Pulando agora. ANNIE: Ei, Mira, pode tocar algo alto? MIRA: Um pouco mais alto. Certo, vamos tentar esta. Veja se isso muda o clima do ambiente. Está gostando do rumo que está tomando? Ah, desculpe. Parece que não podemos colocar o volume tão alto agora. É horário de silêncio. Talvez algo um pouco mais suave, só para acompanhar? Posso tentar. ANNIE: Vamos aprender isso em três partes.

01:01 Parte um: o loop de tool calling. Como as habilidades realmente funcionam nos bastidores. Parte dois: a mesma habilidade escrita de duas maneiras — com o SDK puro e com o ADK. Parte três: as duas regras que determinam se um agent ao vivo parece estar ao vivo ou quebrado. Ao final deste episódio, você terá tudo o que precisa saber para criar seu próprio agent multimodal. Vamos começar pelo loop. Por conta própria, o modelo consegue produzir uma coisa —

01:32 palavras. Ele não consegue começar a tocar música. Não consegue pular uma faixa. Não consegue pausar um player. Então, você dá a ele um menu de habilidades. Pense nelas como ações que seu app pode executar. Para um DJ de rádio, as ações poderiam ser tocar uma faixa, pular e pausar. Cada ação é uma função no seu código. Ela tem um nome, uma descrição e informa ao modelo quando usá-la. Então, no meio da conversa, um loop é executado.

02:05 Quatro etapas: declarar, decidir, executar e retornar. Declarar: você envia um menu de ferramentas com a configuração da sessão. Decidir: o usuário diz “toque algo de dreampop”. Em vez de apenas responder com palavras, o modelo emite uma chamada de ferramenta chamada play_playlist, com mood dreampop. Esse é o ponto central de tool calling. O modelo não consegue executar nada. Ele pede. O código age.

02:36 Executar: seu código executa a função. Retornar: seu código envia o resultado de volta. Então, o modelo continua falando como se nada tivesse acontecido. Enquanto o código estiver na tela, repare na linha da descrição. Essa frase importa. O modelo escolhe as ferramentas lendo as descrições. Então, se o modelo chamar a ferramenta errada, não comece culpando o modelo. Comece corrigindo a descrição. Então, a conclusão da parte um: uma habilidade é uma ação descrita

03:09 mais este loop. Declarar, decidir, executar e retornar. O modelo decide; seu código age. Agora, vamos ver a mesma habilidade de duas maneiras. Primeiro, com o SDK puro. Com o Google GenAI, o menu de ferramentas é um dicionário. Você declara a função, captura a chamada de ferramenta, encaminha a execução e envia a resposta de volta. As quatro etapas ficam todas por sua conta. Agora, o jeito ADK.

03:39 A mesma habilidade é apenas uma função Python com uma docstring, dentro de uma lista de ferramentas com nossas quatro funções. Os nomes estão na tela. É só isso. O ADK lê o schema a partir da assinatura da função. Usa a docstring como descrição. Captura a chamada. Executa a função. Retorna o resultado. Com o SDK puro, escrevemos o loop nós mesmos. No ADK, o framework cuida disso.

04:12 Isso significa que adicionar uma nova habilidade é simples. Adicione uma função. Vamos fazer isso. Na tela, adicionamos set_sleep_timer. Ela recebe minutos. A docstring diz: “pare a música depois de um intervalo”. Depois, adicionamos a função à lista de ferramentas. Pode tocar algo de dreampop? MIRA: Hmm. Dreampop. [MÚSICA TOCANDO] ANNIE: Pule esta, por favor.

04:42 MIRA: Claro. Vamos encontrar outra coisa. Pulando agora. [OUTRA MÚSICA] ANNIE: Pode parar a música em 30 minutos? MIRA: Certo. Em 30 minutos, ela vai desaparecendo aos poucos. ANNIE: Mais uma conexão com o episódio anterior. O modelo não controla a interface diretamente. Ele pede uma ferramenta. Seu backend a executa. Depois, o backend envia um evento ao navegador. Esse evento informa ao app o que mudou. Começar a música, pular a faixa, atualizar a tela. A mesma arquitetura ao vivo.

05:13 Então, a conclusão da parte dois: adicionar uma capacidade é simplesmente adicionar uma função descrita. Mas, numa conversa ao vivo, a parte difícil não é adicionar a ferramenta. É manter a conversa fluida depois que a ferramenta é chamada. Então, a seguir, duas regras para deixar o tool calling ao vivo mais fluido. Regra número um: as ferramentas são síncronas. A voz dela espera por você. Numa sessão ao vivo, quando o agent chama uma ferramenta, a voz para e continua parada até seu código retornar.

05:46 Nossas ferramentas de música retornam quase instantaneamente, então você nunca ouve a pausa. Mas, se uma ferramenta for lenta, você fica em silêncio. E, numa conversa por voz, o silêncio não parece carregamento. Parece que algo quebrou. Então, a regra é: confirme o recebimento. Não espere. Dispare o comando. Retorne OK imediatamente. Deixe o trabalho de verdade acontecer em outro lugar. Toda ferramenta para um agent ao vivo precisa passar por um teste. Ela retorna instantaneamente?

06:16 Se sim, a conversa continua. Se não, parece que o agent travou. E, se o trabalho costuma ser lento, é preciso usar outro padrão. É disso que vamos tratar mais a fundo no próximo episódio. Regra número dois: há um ponto de verificação entre a decisão do modelo e a sua execução. No ADK, esse ponto de verificação é before_tool_callback. Ele vê cada chamada de ferramenta antes de ela ser executada. Você pode fazer três coisas ali.

06:47 Observar, bloquear e reescrever. Observar significa registrar todas as chamadas de ferramenta em um só lugar. Bloquear significa retornar seu próprio resultado. A ferramenta nunca é executada. Reescrever significa ajustar os argumentos. Depois, você deixa a chamada continuar. Vou mostrar o que significa bloquear. Imagine que seu app tenha uma regra de horário de silêncio. Depois da meia-noite, o agent não deve começar a tocar música alta. Então, se o modelo tentar chamar “play playlist”,

07:17 o callback a intercepta primeiro. Em vez de executar a ferramenta, retornamos nosso próprio resultado: é horário de silêncio; sugira algo mais suave. A ferramenta de playlist nunca é executada, e o agent ainda pode responder mantendo a personalidade. Ei, Mira, pode tocar algo alto? MIRA: Hmm, um pouco mais alto? Certo, vamos tentar esta. Veja se isso muda o clima do ambiente. Está gostando do rumo que está tomando? Ah, desculpe. Parece que não podemos colocar o volume tão alto agora.

07:49 É horário de silêncio. Talvez algo um pouco mais suave, só para acompanhar? Posso tentar. ANNIE: Então, no próximo episódio, o agent vai controlar um navegador de verdade. Ele clica. Digita. Espera as páginas carregarem. Esse ponto de verificação se torna muito mais importante. Ele nos ajuda a lidar com ações lentas sem congelar a conversa. E nos dá um lugar para inspecionar a ação antes que ela seja executada — antes de clicar, antes de digitar, antes de interagir com o mundo real.

08:22 Então, a conclusão da parte três: mantenha as ferramentas instantâneas. Coloque as regras no callback. Veja o que você aprendeu. Primeiro, o loop. Declarar, decidir, executar e retornar. O modelo decide. Seu código age. Segundo, duas maneiras de escrever ferramentas. O SDK puro dá controle total sobre o loop. O ADK transforma cada ferramenta em uma função Python descrita. Terceiro, as duas regras para agents ao vivo.

08:52 Mantenha todas as ferramentas instantâneas e coloque suas regras no callback. É assim que você dá habilidades a um agent de voz ao vivo sem interromper a conversa. É isso. Não se esqueça de deixar suas opiniões nos comentários. Como mencionei antes, no próximo episódio, vamos dar mais um passo. Você vai aprender a controlar um navegador de verdade por voz. A parte difícil não é apenas chamar ferramentas; é manter a conversa rápida enquanto a ação no navegador acontece em segundo plano.

09:23 Certo, vejo você no próximo episódio. Tchau. [MÚSICA TOCANDO]

Transcrição original

[00:00] ANNIE: Hi, I’m Annie. Today you will learn how to give a Gemini Live agent abilities, tool calling, but not the request response version you have seen a hundred times. This is the live version. The agent acts mid-conversation and the conversation does not break. Here is what that looks like. Hey, Mira, can you play something dreampop? MIRA: That sounds perfect. [MUSIC PLAYING] ANNIE: Skip this one please.

[00:30] MIRA: Sure. Let’s find something else. Skipping now. ANNIE: Hey, Mira, can you play something loud? MIRA: A little louder. OK, let’s try this. See if this changes the feeling in the room. Do you like where it’s going? Oh, I’m sorry. It looks like we can’t be quite so loud right now. Quiet hours. Maybe something a bit gentler, just to sort of float with? I can try that. ANNIE: We will learn this in three parts.

[01:01] Part one, the tool calling loop. How abilities actually work under the hood. Part two, the same ability written two ways– the raw SDK and the ADK way. Part three, the two rules that decide whether a live agent feels live or broken. By the end of this episode, you will have everything you need to know to build your own multi-modal agent. Let’s start with the loop. On its own, the model can produce one thing–

[01:32] words. It cannot start music. It cannot skip a track. It cannot pause a player. So you give it a menu of abilities. Think of this as actions your app can take. For a radio DJ, the actions might be play a track, skip, pause. Each action is a function in your code. It has a name, it has a description, and it tells the model when to use it. Now, mid-conversation, a loop runs.

[02:05] Four steps– declare, decide, execute, return. Declare, you send a menu of tools with a session config. Decide, the user says “play something dreampop.” Instead of only answering the words, the model emit a tool call called play_playlist, mood dreampop. That is the heart of tool calling. The model cannot run anything. It asks. The code acts.

[02:36] Execute, your code runs the function. Return, your code sends the result back. Then the model keeps talking like nothing happened. While the code is onscreen, notice the description line. That sentence matters. The model chooses tools by reading the descriptions. So if your model calls the wrong tool, do not start by blaming the model. Start by fixing the description. So part one takeaway, an ability is a described action

[03:09] plus this loop. Declare, decide, execute, return. The model decides, your code acts. Now let’s look at the same ability two ways. First, the raw SDK way. With Google GenAI, the tool menu is a dictionary. You declare the function, you catch the tool call, you dispatch it, you send the response back. The four arrows are all yours. Now the ADK way.

[03:39] The same ability is just a Python function with a docstring inside a tool list with our four functions. The names are on screen. That is the whole thing. ADK reads the schema from the function signature. It uses the docstring as the description. It catches the call. It runs the function. It returns the result. In the raw SDK, we write the loop ourselves. In ADK, the framework handles it.

[04:12] That means adding a new ability is simple. Add one function. Let’s do it. Onscreen we add set_sleep_timer. It takes minutes. The docstring says, “stop the music after a delay.” Then we drop it into the tools list. Can you play something dreampop? MIRA: Hm. Dreampop. [MUSIC PLAYING] ANNIE: Skip this one, please.

[04:42] MIRA: Sure Let’s find something else. Skipping now. [DIFFERENT MUSIC] ANNIE: Can you stop the music in 30 minutes. MIRA: OK. 30 minutes and it fades away. ANNIE: One more connection to the last episode. The model does not control the UI directly. It asks for a tool. Your backend runs it. Then the backend sends an event to the browser. That event tells the app what changed. Start the music, skip the track, update the screen. Same live architecture.

[05:13] So part two takeaway– adding a capability is just adding one described function. But in a live conversation, the hard part is not adding the tool. It is keeping the conversation smooth after the tool is called. So next, two rules for making the live tool calling feel smooth. Rule number one, tools are synchronous. Her voice waits for you. In a live session, when the agent calls a tool, her voice stops, and it stays stopped until your code returns.

[05:46] Our music tools return almost instantly, so you never hear the pause. But if a tool is slow, you get silence. And in a voice conversation, silence does not feel like loading. It feels broken. So the rule is, acknowledge. Do not wait. Fire the command. Return OK immediately. Let the real work happen somewhere else. Every tool for a live agent has to pass one test. Does it return instantly?

[06:16] If yes, the conversation stays alive. If no, the agent feels stuck. And if the work is generally slow, that needs a different pattern. That is where the next episode will go deeper. Rule number two, there is a checkpoint between the model’s decision and your execution. In ADK that checkpoint is before_tool_callback. It sees every two calls before the two rounds. You can do three things there.

[06:47] Observe, block, rewrite. Observe means you log every tool call in one place. Block means you return your own result. The tool never runs. Rewrite means you adjust the arguments. Then you let the call continue. Let me show you what block means. Imagine your app has a quiet hours rule. After midnight, the agent should not start loud music. So if the model tries to call “play playlist,”

[07:17] the callback catches it first. Instead of running the tool, we return our own result. It is quiet hours, suggest something gentler. The playlist tool never runs and the agent can still respond in character. Hey, Mira, can you play something loud? MIRA: Hm, a little louder? OK, let’s try this. See if this changes the feeling in the room. Do you like where it’s going? Oh, I’m sorry. It looks like we can’t be quite so loud right now.

[07:49] Quiet hours. Maybe something a bit gentler just to sort of float with? I can try that. ANNIE: So in the next episode, the agent controls a real browser. It clicks. It types. It waits for pages to load. So this checkpoint becomes much more important. It helps us handle slow actions without freezing the conversation. And it gives us one place to inspect the action before it runs– before it clicks, before it types, before it touches the real world.

[08:22] So part three takeaway. Keep tools instant. Put policy in the callback. Here is what you learned. First the loop. Declare, decide, execute, return. The model decides. Your code acts. Second, two ways to write tools. Raw SDK gives you full control over the loop. ADK turns each tool into a described Python function. Third, the two rules for live agents.

[08:52] Keep every tool instant and put your policy in the callback. That is how you give a live voice agent abilities without breaking the conversation. That’s it. Don’t forget to leave your thoughts in the comments. As I mentioned before, in the next episode, we will take this one step further. You will learn how to control a real browser by voice. The hard part is not just calling tools, it is keeping the conversation fast while the browser action runs in the background.

[09:23] All right, I will see you in the next episode. Bye. [MUSIC PLAYING]