Inizia a utilizzare l'API Live con ADK

Questo tutorial mostra come creare un agente e utilizzare lo streaming dell'Agent Development Kit (ADK) per attivare la comunicazione vocale e video. Installa l'ADK, configura un agente di base che utilizza la Ricerca Google ed esegui l'agente con lo strumento adk web.

Prima di iniziare

Questa guida presuppone che tu abbia esperienza nell'utilizzo di un terminale in ambienti Windows, macOS o Linux.

Configura l'ambiente e installa l'ADK

Questa sezione mostra come preparare l'ambiente locale.

  1. Crea e attiva un ambiente virtuale. L'utilizzo di un ambiente virtuale è una pratica consigliata.

    # 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. Installa l'ADK.

    pip install google-adk

Creare la struttura del progetto

Crea le directory e i file necessari per l'agente.

  1. Crea la seguente struttura di cartelle con file vuoti:

    Diagramma della struttura del progetto: la cartella adk-streaming contiene la cartella app, che contiene il file .env e la cartella google_search_agent, che contiene i file __init__.py e agent.py.

  2. Aggiungi il seguente codice al file app/google_search_agent/agent.py. Questo file definisce la logica dell'agente. Devi definire un 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. Aggiungi il codice seguente al file app/google_search_agent/__init__.py:

    from . import agent

Configurare la piattaforma

Per eseguire l'agente, configuralo in modo che utilizzi Google Cloud Vertex AI.

  1. Apri il file .env che si trova nella directory app/.

  2. Aggiungi i seguenti contenuti al file. Sostituisci PROJECT_ID con l'ID progetto Google Cloud e LOCATION con la tua posizione Google Cloud .

    GOOGLE_CLOUD_PROJECT=PROJECT_ID
GOOGLE_CLOUD_LOCATION=LOCATION
GOOGLE_GENAI_USE_VERTEXAI=True

Esegui l'agente con l'UI di sviluppo

Avvia l'interfaccia utente di sviluppo per interagire con il tuo agente.

  1. Cambia la directory attuale in app.

    cd app

  2. Imposta la variabile di ambiente SSL_CERT_FILE. Questo passaggio è necessario per i test vocali e video.

    macOS/Linux

    export SSL_CERT_FILE=$(python -m certifi)

    Windows

    $env:SSL_CERT_FILE = (python -m certifi)

  3. Esegui l'interfaccia utente per sviluppatori.

    adk web

  4. Apri l'URL fornito nel terminale, che in genere è http://localhost:8000 o http://127.0.0.1:8000.

  5. Seleziona google_search_agent.

Il seguente diagramma mostra il flusso dell'input utente all'agente, come l'agente utilizza lo strumento Ricerca Google e come l'agente restituisce una risposta:

Diagramma che mostra l'input utente'utente che va all'agente, l'agente che utilizza lo strumento Ricerca Google per ottenere informazioni e l'agente che restituisce una risposta all'utente.

Interagire con l'agente

Dopo aver avviato la UI per sviluppatori, puoi interagire con l'agente utilizzando testo, voce o video.

Utilizzare l'input di testo

Inserisci i seguenti prompt nella UI per testare le risposte basate su testo dell'agente. L'agente utilizza lo strumento google_search per ottenere le informazioni più recenti per rispondere a queste domande.

  • Che tempo fa a New York?
  • Che ore sono a New York?
  • Che tempo fa a Parigi?
  • Che ore sono a Parigi?

Utilizzare l'input vocale e video

Per utilizzare l'input vocale, ricarica il browser web e fai clic sul pulsante del microfono. Poni una domanda e ascolta la risposta in tempo reale.

Per utilizzare l'input video, ricarica il browser web e fai clic sul pulsante della fotocamera. Poni una domanda come "Che cosa vedi?" e l'agente descrive ciò che vede dall'input video.

Arresta l'interfaccia utente per sviluppatori

Per arrestare lo strumento adk web, premi Ctrl+C nel terminale in cui è in esecuzione.

Passaggi successivi