AI Agent End to End - Workshop

1. Cosa imparerai a fare

AI Agent Vibe Full Stack

Ti diamo il benvenuto. Stai per imparare la prossima competenza fondamentale nello sviluppo di software: come guidare efficacemente l'intelligenza artificiale per creare, testare e implementare software di livello di produzione. L'AI generativa non è un "pilota automatico", ma un potente copilota che ha bisogno di un regista esperto.

Questo workshop fornisce una metodologia strutturata e ripetibile per collaborare con l'AI in ogni fase del ciclo di vita dello sviluppo software (SDLC) professionale. Passerai da scrittore di codice riga per riga a direttore tecnico, un architetto con una visione e un appaltatore generale che utilizza l'AI per realizzare questa visione con precisione. 🚀

Al termine di questo tutorial avrai:

• Tradotto un'idea di alto livello in un'architettura cloud utilizzando l'AI.
• Generato un backend Python completo con prompt mirati e specifici.
• Utilizzo dell'AI come pair programmer per eseguire il debug e correggere il codice.
• Ha delegato all'AI la creazione di test delle unità, inclusi i mock.
• Infrastruttura come codice (IaC) pronta per la produzione generata con Terraform.
• Creazione di una pipeline CI/CD completa in GitHub Actions con un singolo prompt.
• Monitoraggio e gestione dell'applicazione live utilizzando strumenti operativi basati sull'AI.

Non solo avrai un'app funzionante, ma anche un modello per lo sviluppo potenziato dall'AI. Iniziamo.

2. Prerequisiti e configurazione

Prima di iniziare, prepariamo l'ambiente. Si tratta di un passaggio fondamentale per garantire un'esperienza fluida durante il workshop.

Crea un nuovo account Google Cloud e collega la fatturazione

Per alimentare i nostri agenti AI, abbiamo bisogno di due cose: un progetto Google Cloud per fornire le basi e una chiave API Gemini per accedere ai potenti modelli di Google.

Passaggio 1: attiva l'account di fatturazione

• Per richiedere il tuo account di fatturazione con un credito di 5 $, ti servirà per il deployment. Assicurati di accedere al tuo account Gmail.

Nessuna carta di credito o pagamento necessario: riceverai 5 crediti senza costi. Ci vogliono meno di due minuti: basta inserire il tuo nome e accettare i crediti.

Passaggio 2: crea un nuovo progetto GCP

• Vai alla console Google Cloud e crea un nuovo progetto.

• Apri il riquadro a sinistra, fai clic su Billing e verifica se l'account di fatturazione è collegato a questo account GCP.

Se visualizzi questa pagina, controlla manage billing account, scegli la prova di Google Cloud e collegala.

Passaggio 3: genera la chiave API Gemini

Prima di poter proteggere la chiave, devi averne una.

• Vai a Google AI Studio : https://aistudio.google.com/
• Accedi con il tuo account Gmail.
• Fai clic sul pulsante "Ottieni chiave API", di solito presente nel riquadro di navigazione a sinistra o nell'angolo in alto a destra.
• Nella finestra di dialogo "Chiavi API", fai clic su "Crea chiave API nel nuovo progetto".
• Scegli il nuovo progetto che hai creato con l'account di fatturazione configurato.
• Verrà generata una nuova chiave API. Copia immediatamente questa chiave e conservala temporaneamente in un luogo sicuro (ad esempio un software di gestione delle password o una nota protetta). Questo è il valore che utilizzerai nei passaggi successivi.

Autenticazione GitHub

Assicurati di utilizzare lo stesso account Gmail per GitHub e il tuo progetto Google Cloud.

Apri Cloud Shell andando alla console Google Cloud, facendo clic sul pulsante in alto a destra "Attiva Cloud Shell".

Passaggio 1: apri Cloud Shell

👉 Fai clic su "Attiva Cloud Shell" nella parte superiore della console Google Cloud (è l'icona a forma di terminale nella parte superiore del riquadro di Cloud Shell),

👉 Fai clic sul pulsante "Apri editor" (ha l'aspetto di una cartella aperta con una matita). Si aprirà l'editor di codice di Cloud Shell nella finestra. Sul lato sinistro vedrai un esploratore di file.

👉 Una volta aperto l'editor, apri il terminale nell'IDE cloud.

👉💻 Nel terminale, verifica di aver già eseguito l'autenticazione e che il progetto sia impostato sul tuo ID progetto utilizzando il seguente comando:

gcloud auth list

Passaggio 2: autenticati con GitHub e crea un fork

Autenticati con GitHub:

👉💻 Copia e incolla il comando nel terminale cloud:

gh auth login

• In "Dove utilizzi GitHub", scegli "GitHub.com".
• "Qual è il protocollo che preferisci per le operazioni Git su questo host?", scegli "HTTPS".
• "Autenticare Git con le tue credenziali GitHub?", scegli "Sì".
• "How would you like to authenticate GitHub CLI?" (Come vuoi autenticare l'interfaccia a riga di comando di GitHub?), scegli "Login with a web browser" (Accedi con un browser web).

Importante: non premere ancora "Invio"

Tieni presente che devi copiare e incollare il link dal terminale per aprire la pagina di autenticazione di GitHub.

copia il codice dal terminale alla pagina di verifica dell'accesso

Una volta inserito il codice, torna al terminale Cloud Shell e premi Invio per continuare.

Passaggio 4: crea un fork e clona il repository:

👉💻 Copia e incolla il comando nel terminale cloud:

gh repo fork cuppibla/storygen-learning --clone=true

3. Architettura: dall'idea al progetto con Cloud Assist

Ogni grande progetto inizia con una visione chiara. Utilizzeremo il nostro copilota AI, Cloud Assist, per progettare l'architettura della nostra app.

Azioni

• Apri la console Google Cloud: [https://console.cloud.google.com](Google Cloud Console)
• Nell'angolo in alto a destra, fai clic su "Apri chat di Cloud Assist".

Abilita Cloud Assist

• Fai clic su Get Gemini Assist, poi su Enable Cloud Assist at no cost.
• e inizia a chattare.

Fornisci il seguente prompt dettagliato a Cloud Assist:

Inserisci la tua idea

Generate a Python web application that uses AI to generate children's stories and illustrations. It has Python backend and React frontend host separately on Cloudrun. They communicate through Websocket. It needs to use a generative model for text and another for images. The generated images must be used by Imagen from Vertex AI and stored in a Google Cloud Storage bucket so that frontend can fetch from the bucket to render images. I do not want any load balancer or a database for the story text. We need a solution to store the API key.

Ottenere il progetto della tua app

• Fai clic su "Modifica design app" per visualizzare il diagramma. Fai clic sul riquadro in alto a destra "<> Get Code" (Ottieni codice) per scaricare il codice Terraform.
• Cloud Assist genererà un diagramma dell'architettura. Questo è il nostro progetto visivo.

Non è necessaria alcuna azione con questo codice. Continua a leggere per maggiori spiegazioni

Informazioni sul codice Terraform generato. Hai appena ricevuto un set completo di file Terraform da Cloud Assist. Per ora non è richiesta alcuna azione con questo codice, ma analizziamo rapidamente di cosa si tratta e perché è così potente.

Che cos'è Terraform? Terraform è uno strumento Infrastructure as Code (IaC). Immaginala come un progetto per il tuo ambiente cloud, scritto in codice. Anziché fare clic manualmente nella console Google Cloud per creare servizi, spazio di archiviazione e autorizzazioni, definisci tutte queste risorse in questi file di configurazione. Terraform legge quindi il tuo progetto e crea automaticamente l'ambiente esatto.

Dal piano visivo al codice eseguibile. Il diagramma dell'architettura fornito da Cloud Assist è il tuo piano visivo. Il codice Terraform è la versione leggibile dalla macchina dello stesso piano. È il collegamento fondamentale che trasforma un concetto di design in una realtà riproducibile e automatizzata. Definendo l'infrastruttura nel codice, puoi:

• Creazione automatica: crea in modo affidabile lo stesso ambiente più e più volte.
• Utilizza il controllo della versione: monitora le modifiche alla tua infrastruttura in Git, proprio come il codice dell'applicazione.
• Evita errori: evita gli errori manuali che possono verificarsi quando fai clic su un'interfaccia web.

Per questo workshop, non dovrai eseguire personalmente questo codice Terraform. Consideralo il progetto professionale, la "chiave di risposta" per l'infrastruttura che creerai e di cui eseguirai il deployment nei passaggi successivi.

4. Sviluppo: introduzione all'interfaccia a riga di comando di Gemini

👉💻 Nel terminale Cloud Shell, vai alla tua directory personale.

cd ~/storygen-learning

👉💻 Prova Gemini per la prima volta.

clear
gemini --model=gemini-2.5-flash

Se ti viene chiesto Do you want to connect Cloud Shell editor to Gemini CLI?, scegli NO.

👉✨ Ogni strumento Gemini ha una descrizione. Leggili subito. Nel prompt di Gemini, digita:

Nell'interfaccia a riga di comando di Gemini

/help

👉✨ L'interfaccia a riga di comando di Gemini possiede una serie di funzionalità integrate. Per esaminarli:

Nell'interfaccia a riga di comando di Gemini

/tools

Vedrai un elenco che include ReadFile, WriteFile e GoogleSearch. Queste sono le tecniche predefinite che puoi utilizzare senza dover ricorrere a un arsenale esterno.

👉✨ Il Gemini Blade può contenere la "consapevolezza tattica" (contesto) per guidare le sue azioni.

Nell'interfaccia a riga di comando di Gemini

/memory show

Al momento è vuoto, una tabula rasa.

👉✨ Innanzitutto, aggiungi una persona alla memoria dell'agente. In questo modo verrà definita la sua area di competenza:

Nell'interfaccia a riga di comando di Gemini

/memory add "I am master at python development"

Esegui di nuovo /memory show per confermare che la lama abbia assorbito queste informazioni.

👉✨ Per mostrare come fare riferimento ai file con il simbolo @, creiamo prima un file "brief della missione".

Apri un nuovo terminale ed esegui il comando seguente per creare il file della missione:

!echo "## Mission Objective: Create Imagen ADK Agent for Story Book" > mission.md

👉✨ Ora, chiedi a Gemini CLI di analizzare il briefing e di comunicare i risultati:

Nell'interfaccia a riga di comando di Gemini

Explain the contents of the file @mission.md

La tua arma principale ora è consapevole del suo obiettivo.

👉💻 Premi Ctrl+C due volte per uscire dalla Gemini CLI

Apprendimento:

Come l'interfaccia a riga di comando di Gemini ottiene i suoi superpoteri: gemini.md Prima di continuare, è importante capire come l'interfaccia a riga di comando di Gemini può essere adattata a un progetto specifico. Sebbene tu possa utilizzarlo come strumento di chat generico, la sua vera potenza deriva da un file di configurazione speciale: gemini.md.

Quando esegui il comando gemini, viene cercato automaticamente un file gemini.md nella directory corrente. Questo file funge da manuale di istruzioni specifico per il progetto per l'AI. Può definire tre aspetti fondamentali:

• Utente tipo: puoi dire all'AI chi dovrebbe essere. Ad esempio, "Sei uno sviluppatore Python esperto specializzato in Google Cloud". In questo modo, le risposte e lo stile saranno più mirati.
• Strumenti: puoi concedere l'accesso a file specifici (@file.py) o persino alle ricerche Google (@google). In questo modo, l'AI dispone del contesto necessario per rispondere alle domande sul codice del tuo progetto.
• Memoria: puoi fornire fatti o regole che l'AI deve sempre ricordare per questo progetto, il che aiuta a mantenere la coerenza.

Utilizzando un file gemini.md, trasformi il modello Gemini generico in un assistente specializzato che ha già ricevuto informazioni sugli obiettivi del tuo progetto e ha accesso alle informazioni giuste.

5. Sviluppo: creazione dell'ADK con l'interfaccia a riga di comando di Gemini

Configurazione iniziale

Assicurati di utilizzare l'interfaccia a riga di comando di Gemini per creare un fork del repository e preparare lo spazio di lavoro:

Configurazione dell'ambiente

Vai a Cloud Shell e fai clic sul pulsante "Apri terminale".

1. Copia il modello di ambiente:

   cd ~/storygen-learning
   cp ~/storygen-learning/env.template ~/storygen-learning/.env
   

Visualizzare il file nascosto nell'editor se non trovi .env

• Fai clic su Visualizza nella barra dei menu in alto.
• Seleziona Attiva/Disattiva file nascosti.

👉 Trova l'ID progetto Google Cloud:

• Apri la console Google Cloud: link
• Seleziona il progetto che vuoi utilizzare per questo workshop dal menu a discesa dei progetti nella parte superiore della pagina.
• L'ID progetto viene visualizzato nella scheda informativa del progetto nella dashboard.

👉 Trova il tuo nome utente GitHub:

• Vai su GitHub e trova il tuo nome utente GitHub.

Modifica del file .env 2. Sostituisci i seguenti valori in .env:

GOOGLE_API_KEY=[REPLACE YOUR API KEY HERE]
GOOGLE_CLOUD_PROJECT_ID=[REPLACE YOUR PROJECT ID]
GITHUB_USERNAME=[REPLACE YOUR USERNAME]
GENMEDIA_BUCKET=[REPLACE YOUR PROJECT ID]-bucket

Ad esempio, se l'ID progetto è testproject, devi inserire GOOGLE_CLOUD_PROJECT_ID=testproject e GENMEDIA_BUCKET=testproject-bucket

Script di configurazione

Vai a 00_Starting_Here Apri un nuovo terminale (non nell'interfaccia a riga di comando di Gemini)

cd ~/storygen-learning/00_Starting_Here

Esegui la configurazione completa:

./setup-complete.sh

Dovresti vedere i risultati della configurazione nel terminale

Crea il tuo primo agente

Vai a 01a_First_Agent_Ready Utilizziamo l'interfaccia a riga di comando di Gemini per creare l'agente ADK:**

cd ~/storygen-learning/01a_First_Agent_Ready

Apri l'interfaccia a riga di comando di Gemini

gemini

Nella finestra dell'interfaccia a riga di comando di Gemini, prova il prompt:

I need you to help me create a Google ADK (Agent Development Kit) agent for story generation. I'm working on a children's storybook app that generates creative stories with visual scenes.

Please create a complete `agent.py` file that implements an LlmAgent using Google's ADK framework. The agent should:

**Requirements:**
1. Use the `google.adk.agents.LlmAgent` class
2. Use the "gemini-2.5-flash" model (supports streaming)
3. Be named "story_agent"
4. Generate structured stories with exactly 4 scenes each
5. Output valid JSON with story text, main characters, and scene data
6. No tools needed (images are handled separately)

**Agent Specifications:**
- **Model:** gemini-2.5-flash
- **Name:** story_agent  
- **Description:** "Generates creative short stories and accompanying visual keyframes based on user-provided keywords and themes."
**Story Structure Required:**
- Exactly 4 scenes: Setup → Inciting Incident → Climax → Resolution
- 100-200 words total
- Simple, charming language for all audiences
- Natural keyword integration
**JSON Output Format:**

{
  "story": "Complete story text...",
  "main_characters": [
    {
      "name": "Character Name",
      "description": "VERY detailed visual description with specific colors, features, size, etc."
    }
  ],
  "scenes": [
    {
      "index": 1,
      "title": "The Setup",
      "description": "Scene action and setting WITHOUT character descriptions",
      "text": "Story text for this scene"
    }
    // ... 3 more scenes
  ]
}


**Key Instructions for the Agent:**
- Extract 1-2 main characters maximum
- Character descriptions should be extremely detailed and visual
- Scene descriptions focus on ACTION and SETTING only
- Do NOT repeat character appearance in scene descriptions
- Always respond with valid JSON

Please include a complete example in the instructions showing the exact format using keywords like "tiny robot", "lost kitten", "rainy city".

The file should start with necessary imports, define an empty tools list, include a print statement for initialization, and then create the LlmAgent with all the detailed instructions.

Can you create this agent in backend/story_agent/agent.py

Al termine, disattiva il terminale Gemini CLI con Control+C

—————————————— Facoltativo, puoi passare alla sezione Soluzione——————————————–

Ora verifica la modifica in ADK Web

cd ~/storygen-learning/01a_First_Agent_Ready/backend

source ../../.venv/bin/activate

adk web --port 8080

Per continuare, avrai bisogno di un prompt dei comandi.

Puoi aprire una nuova finestra del terminale o interrompere il server web ADK corrente premendo Ctrl+C.

Crea il sito web

cd ~/storygen-learning/01a_First_Agent_Ready

./start.sh

Se la modifica non funziona, dovresti visualizzare errori nell'interfaccia utente web e nel sito web dell'ADK.

——————————————– Soluzione a partire da qui ——————————————–

Soluzione

Termina il processo precedente con Control+C oppure puoi aprire un altro terminale:

cd ~/storygen-learning/01b_First_Agent_Done

Avviare il sito web:

./start.sh

Vedrai il sito web:

Prova la UI dell'ADK: apri un altro terminale:

cd ~/storygen-learning/01b_First_Agent_Done/backend

source ../../.venv/bin/activate

adk web --port 8080

Vedrai l'interfaccia utente dell'ADK, dove potrai porre domande all'agente.

Prima di passare alla sezione successiva, premi Ctrl+C per terminare la procedura.

6. Sviluppo: crea il tuo agente personalizzato con Imagen

Genera lo strumento Imagen (secondo agente)

cd ~/storygen-learning/02a_Image_Agent_Ready

Utilizza Gemini CLI per creare l'agente di generazione di immagini:

gemini generate "I need you to help me create a custom Google ADK (Agent Development Kit) agent for image generation. This is different from the story agent - this one handles image generation directly using the BaseAgent pattern for full control over tool execution.

Please create a complete `agent.py` file that implements a custom image generation agent. The agent should:

**Requirements:**
1. Use the `google.adk.agents.BaseAgent` class (NOT LlmAgent)
2. Be named "custom_image_agent" 
3. Directly execute the ImagenTool without LLM intermediation
4. Handle JSON input with scene descriptions and character descriptions
5. Store results in session state for retrieval by main.py
6. Use async generators and yield Events

**Key Specifications:**
- **Class Name:** CustomImageAgent (inherits from BaseAgent)
- **Agent Name:** "custom_image_agent"
- **Tool:** Uses ImagenTool for direct image generation
- **Purpose:** Bypass LLM agent limitations and directly call ImagenTool

**Input Format:**
The agent should handle JSON input like:
{
  "scene_description": "Scene action and setting",
  "character_descriptions": {
    "CharacterName": "detailed visual description"
  }
}


**Core Method:** `async def _run_async_impl(self, ctx: InvocationContext) -> AsyncGenerator[Event, None]:`
   - Extract user message from `ctx.user_content.parts`
   - Parse JSON input or fallback to plain text
   - Extract scene_description and character_descriptions
   - Build image prompt with style prefix: "Children's book cartoon illustration with bright vibrant colors, simple shapes, friendly characters."
   - Include character descriptions for consistency
   - Call `await self.imagen_tool.run()` directly
   - Store results in `ctx.session.state["image_result"]`
   - Yield Event with results


 **Session State:**
   - Store JSON results in `ctx.session.state["image_result"]`
   - Include success/error status
   - Store actual image URLs or error messages

Expected Output Structure:
- Successful results stored as JSON with image URLs
- Error results stored as JSON with error messages
- Results accessible via session state in main.py

Can you create this agent in backend/story_image_agent/agent.py

"

—————————————— Facoltativo, puoi passare alla sezione Soluzione——————————————–

Ora verifica la modifica in ADK Web

cd ~/storygen-learning/02a_Image_Agent_Ready/backend

source ../../.venv/bin/activate

adk web --port 8080

Crea il sito web

cd ~/storygen-learning/02a_Second_Agent_Ready

./start.sh

Se la modifica non funziona, dovresti visualizzare errori nell'interfaccia utente web e nel sito web dell'ADK.

——————————————- Soluzione a partire da qui ——————————————–

Soluzione

Termina il processo precedente con Control+C oppure puoi aprire un altro terminale:

# Open new terminal
cd ~/storygen-learning/02b_Image_Agent_Done

Avviare il sito web:

./start.sh

Vedrai il sito web:

Prova la UI dell'ADK: apri un altro terminale:

# Open new terminal
cd ~/storygen-learning/02b_Image_Agent_Done/backend

source ../../.venv/bin/activate

adk web --port 8080

Vedrai l'interfaccia utente dell'ADK, dove potrai porre domande all'agente:

Prima di passare alla sezione successiva, premi Ctrl+C per terminare la procedura.

Apprendimento

Il nostro primo agente era ottimo per generare testo, ma ora dobbiamo generare immagini. Per questa attività, abbiamo bisogno di un controllo più diretto. Non vogliamo che il LLM decida se creare un'immagine, ma vogliamo che lo faccia direttamente. Questo è il lavoro perfetto per un BaseAgent.

A differenza di LlmAgent dichiarativo, BaseAgent è imperativo. Ciò significa che tu, lo sviluppatore, scrivi la logica Python passo passo esatta all'interno del metodo _run_async_impl. Hai il pieno controllo del flusso di esecuzione.

Scegli un BaseAgent quando hai bisogno di:

Logica deterministica: l'agente deve seguire una sequenza di passaggi specifica e immutabile.

Esecuzione diretta dello strumento: vuoi chiamare uno strumento direttamente senza l'intervento dell'LLM.

Flussi di lavoro complessi: il processo prevede la manipolazione personalizzata dei dati, chiamate API e una logica troppo complessa per essere dedotta in modo affidabile da un LLM da un solo prompt.

Per la nostra app, utilizzeremo un BaseAgent per ricevere le descrizioni delle scene dal primo agente e chiamare direttamente lo strumento Imagen per garantire la generazione di un'immagine per ogni scena.

7. Test: valutazione dell'agente

La nostra app funziona, ma abbiamo bisogno di una rete di sicurezza automatica di test. È un'attività perfetta da delegare al nostro copilota AI.

Azioni

cd ~/storygen-learning/03a_Agent_Evaluation_Ready/backend

Utilizza l'interfaccia a riga di comando di Gemini per scrivere test completi:

Apri l'interfaccia a riga di comando di Gemini

gemini

Nella finestra dell'interfaccia a riga di comando di Gemini, prova il prompt:

I need you to create comprehensive test files for my backend/story_agent in Google ADK. I need three specific JSON files that match the testing structure used in ADK evaluation.

**Context:** 
- The story agent generates structured JSON stories with exactly 4 scenes
- It uses LlmAgent with no tools, just direct LLM responses
- Input: Keywords
- Output: JSON with story, main_characters, and scenes arrays

**Files to Create:**

### 1. `story_agent_eval.evalset.json` (Comprehensive Integration Tests)
Create a comprehensive evaluation set with:
- **eval_set_id**: "story_agent_comprehensive_evalset"
- **name**: "Story Agent Comprehensive Evaluation Set" 
- **description**: "Comprehensive evaluation scenarios for story_agent covering various keyword combinations, edge cases, and story quality metrics"


Each eval_case should include:
- Full conversation arrays with invocation_id, user_content, final_response
- Complete expected JSON responses with detailed stories, characters, and 4 scenes
- session_input with app_name "story_agent"
- All fields: story (narrative text), main_characters (with detailed visual descriptions), scenes (with index, title, description, text)

### 2. `story_generation.test.json` (Unit Tests)
Create basic generation tests with:
- **eval_set_id**: "story_agent_basic_generation_tests"
- **name**: "Story Agent Basic Generation Tests"
- **description**: "Unit tests for story_agent focusing on JSON structure compliance, scene generation, and keyword integration"

### 3. `test_config.json` (Evaluation Configuration)
Create test configuration with:
- **criteria**: response_match_score: 0.7, tool_trajectory_avg_score: 1.0
- **custom_evaluators**: 
  - json_structure_validator (validates required fields, scene count, character fields)
  - story_quality_metrics (word count 80-250, keyword integration threshold 0.8)
- **evaluation_notes**: Story agent specifics and trajectory expectations

**Important Requirements:**
1. All responses must be valid, parseable JSON
2. Stories must have exactly 4 scenes with indices 1-4
3. Each scene must have: index, title, description, text
4. Main characters must have detailed visual descriptions
5. No tool_uses expected (empty arrays) since story agent uses direct LLM
6. Word count should be 100-200 words total
7. Keywords must be naturally integrated into the narrative

Please generate all three files with realistic example stories and comprehensive test coverage matching the ADK evaluation format.

—————————————— Facoltativo, puoi passare alla sezione Soluzione——————————————–

Per visualizzare la valutazione:

./run_adk_web_persistent.sh

Vai alla scheda eval nell'interfaccia utente dell'ADK.

Dovresti visualizzare la UI web dell'ADK con funzionalità di test persistenti

Momento di apprendimento chiave: l'AI è un partner potente per l'automazione del controllo qualità. Può gestire il boilerplate della scrittura dei test, lasciandoti libero di concentrarti sulla creazione delle funzionalità.

——————————————– Soluzione a partire da qui ——————————————–

Soluzione

• Vai alla cartella della soluzione:

cd ~/storygen-learning/03b_Agent_Evaluation_Done/backend

• Apri la UI web di ADK

./run_adk_web_persistent.sh

Puoi visualizzare gli scenari di test dalla scheda Eval:

Modifica le metriche qui:

Visualizza il risultato dell'esecuzione della valutazione qui:

Apprendimento

Un agente può "funzionare" nel senso che viene eseguito senza errori, ma come facciamo a sapere se produce l'output corretto? La storia è buona? Il formato JSON è corretto? È qui che entra in gioco il framework di valutazione dell'ADK.

La valutazione dell'agente è un sistema di test automatizzato progettato per misurare la qualità e la correttezza delle risposte dell'agente. Anziché limitarsi a controllare gli errori di codice, verifica se il comportamento dell'agente soddisfa le tue aspettative. Il framework utilizza principalmente alcuni file chiave:

evalset.json: questa è la tua suite di test principale. Ogni "caso di valutazione" all'interno di questo file contiene una conversazione di esempio (ad es. un prompt utente) e la risposta ideale, "dorata", che ti aspetti che l'agente produca.

test_config.json: questo file definisce le regole per la riuscita. Qui puoi impostare criteri come:

response_match_score: quanto deve corrispondere la risposta dell'agente alla risposta "ideale"? Un punteggio di 1,0 indica che deve essere identico.

custom_evaluators: puoi creare le tue regole, ad esempio "La risposta deve essere un JSON valido" o "La storia deve contenere più di 100 parole".

Eseguendo una valutazione, puoi testare automaticamente il tuo agente in decine di scenari, assicurandoti che le modifiche al prompt o agli strumenti non interrompano accidentalmente la sua funzionalità principale. È una potente rete di sicurezza per la creazione di agenti AI pronti per la produzione.

8. Infrastructure as Code (IaC): costruire una casa nel cloud

Il nostro codice è testato, ma ha bisogno di un ambiente pronto per la produzione. Utilizzeremo "Infrastructure as Code" per definire il nostro ambiente.

Che cos'è Docker?

Docker è una piattaforma per la creazione e l'esecuzione di applicazioni in container. Pensa a un container come a un container di spedizione standardizzato per il software. Raggruppa tutto ciò che serve alla tua applicazione per essere eseguita in un unico pacchetto isolato:

• Il codice dell'applicazione
• Il runtime richiesto (ad es. la versione specifica di Python)
• Tutti gli strumenti e le librerie di sistema

Questa applicazione containerizzata può essere eseguita su qualsiasi macchina su cui è installato Docker, risolvendo il classico problema "funziona sulla mia macchina".

In questa sezione, chiederemo a Gemini di generare un Dockerfile, ovvero la ricetta o il progetto per creare l'immagine container della nostra applicazione.

Azioni

cd ~/storygen-learning/04a_Manual_Deployment_Ready

Utilizza Gemini CLI per creare un Dockerfile per il backend: apri Gemini CLI

Gemini

All'interno dell'interfaccia a riga di comando di Gemini, prova il prompt:

Create a manual deployment plan for my StoryGen app with Google Cloud Platform. I have a Next.js frontend, Python backend, and Terraform infrastructure.

Generate these deployment files:
1. **01-setup.sh** - Environment setup and authentication
2. **02-build-images.sh** - Build and push Docker images to Google Container Registry
3. **03-deploy-infrastructure.sh** - Deploy with Terraform and configure services
4. **load-env.sh** - Load environment variables for deployment

**Requirements:**
- Use Google Cloud Run for both frontend and backend
- Configure Imagen API and storage buckets
- Set up proper IAM permissions
- Use environment variables from .env file
- Include error handling and status checks

Keep scripts simple, well-commented, and production-ready for manual execution.

Soluzione:

cd ~/storygen-learning/04b_Manual_Deployment_Done

Esegui:

source ../.venv/bin/activate
./01-setup.sh

./02-build-images.sh

./03-deploy-infrastructure.sh

Dovresti vedere i risultati del deployment e la creazione dell'infrastruttura

9. Automazione (CI/CD): la catena di montaggio digitale

Il deployment manuale della nostra applicazione è un ottimo modo per comprendere le parti in movimento, ma è lento, richiede un intervento manuale e può portare a errori umani. Nello sviluppo di software professionale, l'intero processo viene automatizzato utilizzando una pratica chiamata CI/CD.

CI/CD è l'acronimo di integrazione continua e deployment continuo. È un metodo per creare, testare ed eseguire il deployment del codice automaticamente ogni volta che apporti una modifica.

• Integrazione continua (CI): questa è la fase di "compilazione e test". Non appena uno sviluppatore esegue il push di una modifica del codice in un repository condiviso (come GitHub), viene attivato un sistema automatizzato. Compila l'applicazione ed esegue tutti i test (come le valutazioni degli agenti che abbiamo creato) per assicurarsi che il nuovo codice venga integrato correttamente e non introduca bug.
• Deployment continuo (CD): questa è la fase di "rilascio". Se la fase di integrazione continua viene superata correttamente, il sistema esegue automaticamente il deployment della nuova versione testata dell'applicazione in produzione, rendendola disponibile per gli utenti.

Questa pipeline automatizzata crea una "catena di montaggio digitale" che trasferisce il codice dalla macchina di uno sviluppatore alla produzione in modo rapido, sicuro e affidabile. In questa sezione, chiederemo al nostro assistente AI di creare questa catena di montaggio per noi utilizzando GitHub Actions e Google Cloud Build.

Azioni

cd ~/storygen-learning/05a_CICD_Pipeline_Ready

Utilizza Gemini CLI per creare la pipeline CI/CD con GitHub:

Apri Gemini CLI

Gemini

All'interno dell'interfaccia a riga di comando di Gemini, prova il prompt:

Create a CI/CD pipeline for my StoryGen app using Google Cloud Build and GitHub integration.

Generate these automation files:
1. **cloudbuild.yaml** (for backend) - Automated build, test, and deploy pipeline
2. **GitHub Actions workflow** - Trigger builds on push/PR
3. **Deployment automation scripts** - Streamlined deployment process

**Requirements:**
- Auto-trigger on GitHub push to main branch
- Build and push Docker images
- Run automated tests if available
- Deploy to Google Cloud Run
- Environment-specific deployments (staging/prod)
- Notification on success/failure

Focus on fully automated deployment with minimal manual intervention. Include proper secret management and rollback capabilities.

——————————————– Soluzione a partire da qui ——————————————–

Soluzione:

cd ~/storygen-learning/06_Final_Solution/
# Copy the GitHub workflow to parent folder
cp -r 06_Final_Solution/.GitHub ../../../.GitHub

Torna alla cartella 06_Final_Solution ed esegui lo script:

cd ~/storygen-learning/06_Final_Solution/

./setup-cicd-complete.sh

Dovresti visualizzare il completamento della configurazione della pipeline CI/CD

Attiva il flusso di lavoro:esegui il commit e il push del codice in main. Tieni presente che per consentire l'autorizzazione devi configurare l'email e il nome di GitHub.

git add .
git commit -m "feat: Add backend, IaC, and CI/CD workflow"
git push origin main

Vai alla scheda "Azioni" nel repository GitHub per vedere l'esecuzione della distribuzione automatica.

10. Operazioni: la torre di controllo dell'AI

Siamo in diretta! Ma il viaggio non è ancora finito. Questo è il "giorno 2", ovvero le operazioni. Torniamo a Cloud Assist per gestire l'applicazione in esecuzione.

Azioni

1. Vai al servizio Cloud Run nella console Google Cloud. Interagisci con la tua app live per generare traffico e log.
2. Apri il riquadro Cloud Assist e utilizzalo come copilota operativo con prompt come questi:

Analisi dei log:

Summarize the errors in my Cloud Run logs for the service 'genai-backend' from the last 15 minutes.

Ottimizzazione delle prestazioni:

My Cloud Run service 'genai-backend' has high startup latency. What are common causes for a Python app and how can I investigate with Cloud Trace?

Ottimizzazione dei costi:

Analyze the costs for my 'genai-backend' service and its GCS bucket. Are there any opportunities to save money?

Momento di apprendimento chiave:il ciclo di vita dello sviluppo del software AI è un ciclo continuo. Lo stesso copilota AI che ha contribuito a creare l'applicazione è un partner indispensabile per il monitoraggio, la risoluzione dei problemi e l'ottimizzazione in produzione.