Começar a usar a API Live com o ADK

Neste tutorial, mostramos como criar um agente e usar o ADK Streaming (em inglês) para ativar a comunicação por voz e vídeo. Você vai instalar o ADK, configurar um agente básico que usa a Pesquisa Google e executar o agente com a ferramenta adk web.

Antes de começar

Neste guia, pressupomos que você tenha experiência no uso de um terminal em ambientes Windows, macOS ou Linux.

Configurar o ambiente e instalar o ADK

Esta seção mostra como preparar seu ambiente local.

  1. Crie e ative um ambiente virtual. Usar um ambiente virtual é uma prática recomendada.

    # Create the environment
python -m venv .venv

# Activate the environment in each new terminal
# For macOS or Linux:
source .venv/bin/activate
# For Windows CMD:
.venv\Scripts\activate.bat
# For Windows PowerShell:
.venv\Scripts\Activate.ps1

  2. Instale o ADK.

    pip install google-adk

Criar a estrutura do projeto

Crie os diretórios e arquivos necessários para seu agente.

  1. Crie a seguinte estrutura de pastas com arquivos vazios:

    Diagrama da estrutura do projeto: a pasta adk-streaming contém a pasta app, que contém o arquivo .env e a pasta google_search_agent, que contém os arquivos __init__.py e agent.py.

  2. Adicione o seguinte código ao arquivo app/google_search_agent/agent.py. Esse arquivo define a lógica do seu agente. É necessário definir um root_agent.

    from google.adk.agents import Agent
from google.adk.tools import google_search  # Import the tool

root_agent = Agent(
  # A unique name for the agent.
  name="basic_search_agent",
  # The Large Language Model (LLM) that agent will use.
  # Please fill in the latest model id that supports live from
  # https://google.github.io/adk-docs/get-started/streaming/quickstart-streaming/#supported-models
  model="...",  # for example: model="gemini-live-2.5-flash-preview-native-audio-09-2025"
  # A short description of the agent's purpose.
  description="Agent to answer questions using Google Search.",
  # Instructions to set the agent's behavior.
  instruction="You are an expert researcher. You always stick to the facts.",
  # Add google_search tool to perform grounding with Google search.
  tools=[google_search]
)

  3. Adicionar o seguinte código ao arquivo app/google_search_agent/__init__.py:

    from . import agent

Configurar a plataforma

Para executar o agente, configure-o para usar a Google Cloud Vertex AI.

  1. Abra o arquivo .env localizado no diretório app/.

  2. Adicione o seguinte conteúdo ao arquivo. Substitua PROJECT_ID pelo ID do projeto Google Cloud e LOCATION pelo local Google Cloud .

    GOOGLE_CLOUD_PROJECT=PROJECT_ID
GOOGLE_CLOUD_LOCATION=LOCATION
GOOGLE_GENAI_USE_VERTEXAI=True

Executar o agente com a UI de desenvolvimento

Inicie a interface de usuário de desenvolvimento para interagir com seu agente.

  1. Mude o diretório atual para app.

    cd app

  2. Defina a variável de ambiente SSL_CERT_FILE. Essa etapa é obrigatória para testes de voz e vídeo.

    macOS/Linux

    export SSL_CERT_FILE=$(python -m certifi)

    Windows

    $env:SSL_CERT_FILE = (python -m certifi)

  3. Execute a UI de desenvolvimento.

    adk web

  4. Abra o URL fornecido no terminal, que geralmente é http://localhost:8000 ou http://127.0.0.1:8000.

  5. Selecione google_search_agent.

O diagrama a seguir mostra como a entrada do usuário flui para o agente, como ele usa a ferramenta da Pesquisa Google e como ele retorna uma resposta:

Diagrama mostrando a entrada do usuário indo para o agente, o agente usando a ferramenta de Pesquisa Google para receber informações e o agente retornando uma resposta ao usuário.

Interagir com o agente

Depois de iniciar a UI do desenvolvedor, você pode interagir com o agente usando texto, voz ou vídeo.

Usar entrada de texto

Insira os comandos a seguir na UI para testar as respostas baseadas em texto do agente. O agente usa a ferramenta google_search para receber as informações mais recentes e responder a essas perguntas.

  • Qual é a previsão do tempo em Nova York?
  • Que horas são em Nova York?
  • Qual é a previsão do tempo para Paris?
  • Que horas são em Paris?

Usar entrada de voz e vídeo

Para usar a entrada de texto por voz, recarregue o navegador da Web e clique no botão do microfone. Faça uma pergunta e ouça a resposta em tempo real.

Para usar a entrada de vídeo, recarregue o navegador da Web e clique no botão da câmera. Pergunte algo como "O que você vê?", e o agente descreve o que aparece na entrada de vídeo.

Parar a UI de desenvolvimento

Para interromper a ferramenta adk web, pressione Ctrl+C no terminal em que ela está sendo executada.

A seguir