1. Introduzione
In questo codelab, creerai il tuo primo agente AI passo dopo passo utilizzando l'Agent Development Kit (ADK) e Gemini di Google. Creerai un agente di scrittura di blog di base che pianifica e scrive contenuti, mostrando i concetti fondamentali di ragionamento e azione.
In questo lab proverai a:
- Configura l'ambiente di sviluppo per l'ADK.
- Crea un sistema multi-agente con un pianificatore e un writer.
- Esegui l'agente localmente e interagisci con lui tramite l'interfaccia utente web ADK.
Che cosa ti serve
- Un browser web come Chrome.
- Python 3.10 o versioni successive installato sulla macchina.
- Una chiave API di Google AI Studio.
Questo codelab è rivolto a sviluppatori di tutti i livelli, inclusi i principianti.
Durata stimata: 30 minuti.
2. Guida visiva: che cosa sono gli agenti AI?
Prima di iniziare a creare, vediamo rapidamente cosa sono gli agenti AI e i pattern comuni che seguono.
Che cos'è un agente AI?
Al livello più semplice, un agente è un software che non si limita a rispondere, ma può decidere e agire. Anziché generare una singola risposta come un chatbot tradizionale, esamina la tua richiesta, determina i passaggi da seguire, chiama un'API, esegue il codice, esamina il risultato e poi decide cosa fare.
Una delle spiegazioni più chiare proviene dall'articolo di ricerca ReAct: Synergizing Reasoning and Acting in Language Models. L'idea alla base di questo articolo è semplice ma potente: i modelli linguistici non devono solo generare testo in una sola volta. Possono ragionare passo dopo passo, intraprendere un'azione come chiamare uno strumento o un'API, osservare il risultato e poi decidere cosa fare dopo.
Questo ciclo di ragionamento, azione, osservazione e aggiustamento è alla base del funzionamento dei moderni agenti di AI. E corrisponde alla definizione di Google Cloud: sistemi con ragionamento, pianificazione e memoria, con autonomia sufficiente per adattarsi e prendere decisioni per conto dell'utente.
Tre pattern di comportamento degli agenti
Non tutti gli agenti si comportano allo stesso modo. Un modo utile per pensarci è suddividerli in tre ampi schemi:
- Agenti sequenziali: vengono eseguiti passo dopo passo come una catena di montaggio: passaggio 1, poi passaggio 2, poi passaggio 3. Sono prevedibili, ma rigidi.
- Agenti reattivi: prendono decisioni in tempo reale. Analizzano lo stato attuale e si chiedono: "Cosa devo fare dopo?". Magari una volta utilizzano lo strumento A e la volta successiva lo strumento B. Sono flessibili, ma non pianificano in anticipo.
- Agenti deliberativi o di pianificazione: questi si fermano per abbozzare un piano, quindi lo eseguono. Pensa alla prenotazione di un viaggio: non acquisti un volo a caso, scegli le date, gli hotel, ordini i passaggi e poi li segui.
Quale di questi è quello "giusto"? Dipende dal problema. Per flussi semplici e prevedibili, la sequenza è sufficiente. Per attività dinamiche, la reazione funziona meglio. Per obiettivi in più passaggi con dipendenze, sono necessari agenti di pianificazione.
In questo lab, creeremo un agente deliberativo/di pianificazione che prima crea una struttura e poi scrive il post del blog.
3. Prima di iniziare
Crea un account e un progetto Google Cloud
Per eseguire il deployment dell'agente su Google Cloud Run più avanti in questo lab, devi disporre di un account Google Cloud e di un progetto con la fatturazione abilitata.
- Accedi alla console Google Cloud. Crea un nuovo progetto o riutilizzane uno esistente. Se non hai ancora un Account Google, devi crearne uno.
- Successivamente, dovrai attivare la fatturazione in Cloud Console per utilizzare le risorse cloud. L'esecuzione di questo codelab dovrebbe costare meno di pochi centesimi. I nuovi utenti di Google Cloud potrebbero anche avere diritto al programma prova senza costi di 300$.
- Prendi nota dell'ID progetto (un nome univoco tra tutti i progetti Google Cloud). Ti servirà per configurare e implementare l'agente.
Ottieni una chiave API Google AI Studio
Per utilizzare i modelli Gemini, devi avere una chiave API da Google AI Studio.
- Vai a Google AI Studio.
- Fai clic su Ottieni chiave API.
- Crea una nuova chiave o utilizzane una esistente. Copia la chiave per utilizzarla in un secondo momento.
4. Crea la struttura del progetto dell'agente di scrittura di blog
In questo passaggio, configurerai la directory e i file per ospitare il codice dell'agente di scrittura di blog sul tuo computer locale.
1. Crea il workspace dell'agente di scrittura di blog
Apri il terminale ed esegui i seguenti comandi per creare una directory dedicata all'agente di scrittura del blog e accedervi:
mkdir bloggeragent
cd bloggeragent
2. Inizializza i file dell'agente
Il framework Google ADK carica i workflow degli agenti direttamente dalla directory del progetto. Crea i file necessari direttamente nella radice di bloggeragent:
touch requirements.txt .env __init__.py agent.py
5. Installa le dipendenze e configura l'ambiente
In questo passaggio configurerai un ambiente virtuale Python, installerai il framework Google ADK e configurerai le variabili di ambiente per autenticare l'agente del blog con il modello Gemini.
1. Configura i requisiti dell'agente
Apri il file requirements.txt nella directory bloggeragent e specifica i pacchetti necessari per l'agente di scrittura del blog aggiungendo quanto segue:
google-adk==2.2.0
python-dotenv
2. Crea un ambiente virtuale per l'agente
Dalla directory bloggeragent, crea e attiva un ambiente virtuale Python per isolare i pacchetti dell'agente:
python3 -m venv .venv
source .venv/bin/activate
3. Installa il framework ADK
Installa le dipendenze definite in requirements.txt per dotare il tuo spazio di lavoro locale di Google ADK:
pip install -r requirements.txt
4. Configurare le credenziali API dell'agente
Apri il file .env che hai creato nella radice del progetto e aggiungi la chiave API Gemini:
GOOGLE_API_KEY=your_api_key
Sostituisci your_api_key con la chiave che hai copiato da Google AI Studio.
6. Crea lo strumento di scrittura di blog multi-agente
In questo passaggio, implementerai il workflow principale del sistema dell'agente di scrittura di blog.
Invece di un semplice chatbot con un solo prompt, creerai un complesso sistema multi-agente che utilizza cicli di autocorrezione e verifica della struttura per scrivere post tecnici di alta qualità. Questo segue il pattern Deliberativo/Pianificazione di cui abbiamo parlato in precedenza.
Panoramica dell'architettura
Ecco come interagiscono gli agenti specializzati nel tuo sistema:
Configura init.py
Apri __init__.py nell'editor di testo e aggiungi la seguente importazione per esporre il flusso di lavoro dell'agente al runner:
from . import agent
Scrivi il flusso di lavoro dell'agente di scrittura del blog
Apri agent.py nell'editor di codice e aggiungi il seguente codice che definisce Planner, Writer, Validation Checkers e l'agente Blogger principale:
import os
import sys
from pathlib import Path
import datetime
from dotenv import load_dotenv
from google.adk.agents import Agent, LoopAgent
from google.adk.tools import agent_tool
# env config
load_dotenv()
MODEL = os.getenv("MODEL", "gemini-flash-latest")
# Sub-Agent: Planner
blog_planner = Agent(
name="BlogPlanner",
model=MODEL,
description="Creates a practical, skimmable outline in Markdown.",
instruction="""
You are a technical content strategist. Produce a clear Markdown outline with:
- Title
- Short intro
- 4–6 main sections (each with 2–3 bullets)
- Conclusion
If `codebase_context` exists in state, weave in specific sections/snippets.
Return only the outline in Markdown.
""",
output_key="blog_outline",
)
class OutlineValidationChecker(Agent):
def __init__(self):
super().__init__(
name="OutlineValidationChecker",
model=MODEL,
description="Validates that the outline is usable.",
instruction="""
Check the outline in state `blog_outline`. If it has a title, intro, 4–6 sections, and a conclusion, respond exactly "ok".
Otherwise respond exactly "retry" and list missing pieces.
""",
output_key="validation_result",
)
robust_blog_planner = LoopAgent(
name="RobustBlogPlanner",
description="Retries planning if validation fails.",
sub_agents=[blog_planner, OutlineValidationChecker()],
max_iterations=3,
)
# Sub-Agent: Writer
blog_writer = Agent(
name="BlogWriter",
model=MODEL,
description="Writes a technical blog post from the outline.",
instruction="""
Write a complete Markdown article from the outline in `blog_outline`.
Guidelines:
- Audience: software engineers; skip basics and focus on practical insight.
- Explain both the 'how' and 'why'.
- Include concise code snippets when helpful.
- Follow the outline's structure (H2/H3).
- Output only the final article in Markdown (no fence around the whole post).
""",
output_key="blog_post",
)
class BlogPostValidationChecker(Agent):
def __init__(self):
super().__init__(
name="BlogPostValidationChecker",
model=MODEL,
description="Validates the final post.",
instruction="""
Check `blog_post` for: intro, clear sections matching the outline, conclusion, and technical clarity.
If passes, respond "ok". Else respond "retry" with the specific fixes.
""",
output_key="validation_result",
)
robust_blog_writer = LoopAgent(
name="RobustBlogWriter",
description="Retries writing if validation fails.",
sub_agents=[blog_writer, BlogPostValidationChecker()],
max_iterations=3,
)
# Expose planner/writer as tools so the root agent can call them explicitly
planner_tool = agent_tool.AgentTool(agent=robust_blog_planner)
writer_tool = agent_tool.AgentTool(agent=robust_blog_writer)
# Root Agent: Plan → Write
root_agent = Agent(
name="Blogger",
model=MODEL,
description="Minimal multi-agent blogger that plans and writes.",
instruction=f"""
If the user gives a topic:
1) Call the planner tool to generate the outline.
2) Call the writer tool to produce the full draft.
3) End with 3 alternate titles and 2 tweet-length hooks.
Date: {datetime.datetime.now().strftime("%Y-%m-%d")}
""",
tools=[
planner_tool, # calls RobustBlogPlanner
writer_tool, # calls RobustBlogWriter
],
)
Informazioni sull'architettura dell'agente
Analizziamo i componenti principali del codice appena aggiunto in agent.py per capire come implementa il flusso di lavoro di pianificazione e scrittura multi-agente:
1. Il sub-agente BlogPlanner
L'agente blog_planner è responsabile della pianificazione dei contenuti. Prende l'argomento fornito dall'utente e produce una struttura in Markdown (con un titolo, un'introduzione, 4-6 sezioni e una conclusione). La struttura viene salvata nel dizionario dello stato condiviso con la chiave "blog_outline".
2. The OutlineValidationChecker
L'agente OutlineValidationChecker funge da controllo qualità. Esamina il "blog_outline" generato nello stato. Se la struttura è valida, risponde con "ok". In caso contrario, restituisce "retry" insieme a un elenco di ciò che manca.
3. The RobustBlogPlanner Loop
Per impedire all'agente di produrre brutti schemi, racchiudiamo il pianificatore e il controllo della convalida all'interno di un LoopAgent chiamato robust_blog_planner. Se la convalida non riesce e restituisce "retry", il ciclo esegue automaticamente di nuovo il pianificatore, fino a tre volte, garantendo l'autocorrezione prima di passare alla fase successiva.
4. Il sub-agente BlogWriter
Una volta finalizzato lo schema, l'agente blog_writer legge "blog_outline" dallo stato e genera l'articolo tecnico completo in Markdown, in modo che corrisponda alla struttura dello schema e lo adatti agli ingegneri software.
5. Il ciclo BlogPostValidationChecker e RobustBlogWriter
Proprio come la struttura, l'articolo finale viene convalidato dal BlogPostValidationChecker per garantire che tutte le sezioni chiave siano presenti e chiare. Lo scrittore e il revisore sono inclusi nel ciclo robust_blog_writer, il che consente di correggere automaticamente l'articolo fino a tre volte se il revisore rileva problemi.
6. Esporre i loop come strumenti
Racchiudiamo il ciclo di pianificazione (robust_blog_planner) e il ciclo di scrittura (robust_blog_writer) come strumenti (planner_tool e writer_tool) utilizzando AgentTool. In questo modo, gli altri agenti possono chiamare questi workflow complessi come se fossero semplici strumenti.
7. L'agente principale di Blogger
root_agent (denominato Blogger) orchestra l'intero flusso di lavoro. Quando riceve un argomento, le istruzioni lo guidano a:
- Chiama il numero
planner_toolper generare la bozza convalidata. - Chiama
writer_toolper scrivere la bozza in base a questa struttura. - Termina generando tre titoli alternativi e due agganci per tweet.
Questa architettura a loop multi-agente garantisce l'affidabilità rilevando e correggendo gli errori di formattazione o strutturali dell'LLM prima di mostrare l'output all'utente.
7. Esegui e testa l'agente
Ora è il momento di vedere il tuo agente in azione.
1. Avviare l'interfaccia utente web dell'ADK
Assicurati di trovarti nella directory principale del progetto bloggeragent nel terminale e che l'ambiente virtuale sia attivo (source .venv/bin/activate), quindi avvia l'interfaccia web:
adk web
2. Interagire con l'agente
- Apri il browser e vai all'indirizzo
http://127.0.0.1:8000(o alla porta che hai specificato). - Dovresti visualizzare la GUI web di ADK con l'agente
Bloggercaricato e il suo layout grafico (che mostra l'agente principale di Blogger che punta agli strumenti RobustBlogPlanner e RobustBlogWriter):
- Digita un argomento tecnico nella casella del messaggio e premi Invio. Ecco alcuni prompt di test interessanti che puoi utilizzare per valutare il tuo agente:
How to build an AI agent using planning loopsExplain the difference between REST and gRPC in microservicesA guide to using Python's asyncio for backend concurrencyWhy developers should use Docker for local database setups
- Guarda la traccia di esecuzione nella UI. Vedrai
BlogPlannercreare la struttura,OutlineValidationCheckerconvalidarla eBlogWriterscrivere la bozza finale in base alla struttura:
8. Esegui il deployment in Cloud Run
Ora che hai verificato che l'agente funzioni localmente, esegui il deployment in Google Cloud Run in modo che altri possano utilizzarlo.
Google Cloud Run è una piattaforma di computing gestita che consente di eseguire container stateless richiamabili tramite richieste web o eventi Pub/Sub.
1. Prerequisiti per il deployment
Per eseguire il deployment dell'agente di scrittura di blog su Cloud Run, devi installare e autenticare Google Cloud CLI (gcloud) sulla tua macchina locale:
- Installa Google Cloud CLI: se non l'hai installata, segui la guida all'installazione di Google Cloud CLI per il tuo sistema operativo (macOS, Windows o Linux).
- Autentica il terminale locale: una volta installato, esegui questo comando nel terminale per accedere al tuo account Google Cloud:
gcloud auth login - Verifica l'autenticazione: conferma che l'accesso al tuo account è stato eseguito correttamente e che puoi accedere alle tue risorse Google Cloud:
gcloud auth list
2. Configura il progetto Google Cloud
Imposta il progetto attivo nel terminale:
gcloud config set project <YOUR_PROJECT_ID>
Abilita i servizi Google Cloud necessari per creare e implementare l'agente containerizzato:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
Poiché il comando di deployment dell'ADK utilizza Google Cloud Build per automatizzare il processo di compilazione, devi concedere all'account di servizio Compute predefinito l'autorizzazione per utilizzare Cloud Build.
Trova il numero di progetto eseguendo:
gcloud projects describe <YOUR_PROJECT_ID> --format="value(projectNumber)"
Esegui i seguenti comandi per associare i ruoli IAM richiesti (sostituisci
- Concedi l'autorizzazione a Cloud Build per creare il container:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/cloudbuild.builds.builder"
- Concedi l'autorizzazione di accesso a Gemini Enterprise in modo che l'agente di cui è stato eseguito il deployment possa richiamare i modelli Gemini senza richiedere una chiave API:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"
3. Configura le variabili di ambiente locali
Per semplificare il comando di deployment ed evitare errori di battitura, imposta l'ID progetto come variabile di ambiente nella sessione del terminale:
export PROJECT_ID="<YOUR_PROJECT_ID>"
4. Esegui il deployment utilizzando ADK CLI
La CLI ADK fornisce un comando semplificato per il deployment dell'agente su Cloud Run.
Assicurati che l'ambiente virtuale sia attivo e di trovarti nella directory del progetto bloggeragent, poi esegui il comando di deployment:
# Deploy using ADK
adk deploy cloud_run \
--project=$PROJECT_ID \
--region=us-east1 \
--service_name=bloggeragent \
--with_ui \
. \
-- \
--set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE,MODEL=gemini-3.5-flash,GOOGLE_CLOUD_LOCATION=global
Durante il processo di deployment, nel terminale ti verranno poste le seguenti due domande:
- Conferma la creazione del repository:
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [us-east1] will be created. Do you want to continue (Y/n)?
Ye premi Invio. - Consenti accesso non autenticato:
Allow unauthenticated invocations to [bloggeragent] (y/N)?
ye premi Invio (in questo modo puoi accedere pubblicamente alla GUI web dell'ADK nel browser).
5. Accedere all'agente di cui è stato eseguito il deployment
Una volta completato il deployment, il comando restituirà un URL. Apri l'URL nel browser per accedere alla GUI web dell'ADK live e accessibile pubblicamente.
9. Esegui la pulizia
Per evitare addebiti continui al tuo account Google Cloud, elimina le risorse create durante questo codelab.
1. Elimina servizio Cloud Run
Elimina il servizio bloggeragent di cui hai eseguito il deployment:
gcloud run services delete bloggeragent --region=us-east1 --quiet
2. Elimina il repository Artifact Registry
Elimina il repository Docker creato per archiviare le immagini container create:
gcloud artifacts repositories delete cloud-run-source-deploy --location=us-east1 --quiet
3. Arrestare il server locale
Per arrestare il server ADK locale, premi CTRL+C nel terminale in cui è in esecuzione e disattiva l'ambiente virtuale:
deactivate
10. Complimenti
Complimenti! Hai creato il tuo primo agente AI utilizzando l'ADK e Gemini di Google.
Cosa hai imparato
- I concetti fondamentali degli agenti AI (ragionamento e azione).
- Come utilizzare Google ADK per creare un sistema multi-agente.
- Come eseguire e testare l'agente utilizzando l'interfaccia utente web.
Passaggi successivi
- Prova ad aggiungere strumenti al tuo agente (come la ricerca sul web o le chiamate API).
- Continua a seguirci per il video 2, in cui integreremo un server MCP.