Comece a usar a API Live com o ADK

Este tutorial mostra como criar um agente e usar o Agent Development Kit (ADK) Streaming para ativar a comunicação de voz e vídeo. Instala o ADK, configura um agente básico que usa a Pesquisa Google e executa o agente com a ferramenta adk web.

Antes de começar

Este guia pressupõe que tem experiência na utilização de um terminal em ambientes Windows, macOS ou Linux.

Configure o seu ambiente e instale o ADK

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

  1. Crie e ative um ambiente virtual. A utilização de 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

Crie a estrutura do projeto

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

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

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

  2. Adicione o seguinte código ao ficheiro app/google_search_agent/agent.py. Este ficheiro define a lógica do seu agente. Tem de 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. Adicione o seguinte código ao ficheiro app/google_search_agent/__init__.py:

    from . import agent

Configure a plataforma

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

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

  2. Adicione o seguinte conteúdo ao ficheiro. Substitua PROJECT_ID pelo ID do seu Google Cloud projeto e substitua LOCATION pela sua Google Cloud localização.

    GOOGLE_CLOUD_PROJECT=PROJECT_ID
GOOGLE_CLOUD_LOCATION=LOCATION
GOOGLE_GENAI_USE_VERTEXAI=True

Execute o agente com a IU de programador

Inicie a interface do utilizador de desenvolvimento para interagir com o seu agente.

  1. Altere o seu diretório atual para app.

    cd app

  2. Defina a variável de ambiente SSL_CERT_FILE. Este passo é obrigatório para os 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 IU de desenvolvimento.

    adk web

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

  5. Selecione google_search_agent.

O diagrama seguinte mostra como a entrada do utilizador flui para o agente, como o agente usa a ferramenta de pesquisa Google e como o agente devolve uma resposta:

Diagrama que mostra a entrada do utilizador a ser enviada para o agente, o agente a usar a ferramenta de Pesquisa Google para obter informações e o agente a devolver uma resposta ao utilizador.

Interagir com o agente

Depois de iniciar a IU de programador, pode interagir com o seu agente através de texto, voz ou vídeo.

Utilize a entrada de texto

Introduza os seguintes comandos na IU para testar as respostas baseadas em texto do agente. O agente usa a ferramenta google_search para obter as informações mais recentes para responder a estas perguntas.

  • Como está o tempo em Nova Iorque?
  • Que horas são em Nova Iorque?
  • Como está o tempo em 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 de Internet 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 de Internet e clique no botão da câmara. Faça uma pergunta como "O que é que vês?" e o agente descreve o que vê a partir da entrada de vídeo.

Pare a IU de programador

Para parar a ferramenta adk web, prima Ctrl+C no terminal onde está a ser executada.

O que se segue?