Atelier sur l'agent d'IA de bout en bout

1. Objectifs de l'atelier

Full Stack Vibe de l'agent IA

Bienvenue ! Vous allez acquérir une nouvelle compétence essentielle en développement de logiciels : comment guider efficacement l'intelligence artificielle pour créer, tester et déployer des logiciels de qualité. L'IA générative n'est pas un "pilote automatique", mais un copilote puissant qui a besoin d'un réalisateur compétent.

Cet atelier fournit une méthodologie structurée et reproductible pour collaborer avec l'IA à chaque étape du cycle de développement logiciel (SDLC) professionnel. Vous passerez du statut de rédacteur de code ligne par ligne à celui de directeur technique, c'est-à-dire un architecte avec une vision et un entrepreneur général qui utilise l'IA pour exécuter cette vision avec précision. 🚀

À la fin de ce tutoriel, vous aurez :

• Traduction d'une idée générale en architecture cloud à l'aide de l'IA.
• Génération d'un backend Python complet avec des requêtes ciblées et spécifiques.
• Utilisé l'IA comme assistant en programmation pour déboguer et corriger du code.
• Délégation de la création de tests unitaires, y compris des mocks, à l'IA.

Générez une infrastructure as code (IaC) prête pour la production avec Terraform.

Création d'un pipeline CI/CD complet dans GitHub Actions à l'aide d'une seule requête.

Surveillez et gérez votre application en production à l'aide d'outils opérationnels basés sur l'IA.

Vous repartirez non seulement avec une application fonctionnelle, mais aussi avec un plan pour le développement augmenté par l'IA. C'est parti !

2. Conditions préalables et configuration

Avant de commencer, préparons votre environnement. Il s'agit d'une étape cruciale pour garantir une expérience fluide lors de l'atelier.

Créer un compte GCP et associer votre facturation

Pour alimenter nos agents d'IA, nous avons besoin de deux éléments : un projet Google Cloud pour fournir la base et une clé API Gemini pour accéder aux puissants modèles de Google.

Étape 1 : Activez le compte de facturation

• Réclamez votre compte de facturation avec un crédit de 5 $, dont vous aurez besoin pour votre déploiement. Assurez-vous d'utiliser votre compte Gmail.

Aucune carte de crédit ni aucun paiement ne sont nécessaires : vous recevrez 5 € de crédits sans frais. Cela prend moins de deux minutes. Il vous suffit de saisir votre nom et d'accepter les crédits.

Étape 2 : Créer un projet GCP

• Accédez à la console Google Cloud et créez un projet.

• Accédez à la console Google Cloud et créez un projet.
• Ouvrez le panneau de gauche, cliquez sur Billing et vérifiez si le compte de facturation est associé à ce compte GCP.

Si cette page s'affiche, cochez la case manage billing account, choisissez l'essai Google Cloud One et associez-le.

Étape 3 : Générez votre clé API Gemini

Avant de pouvoir sécuriser une clé, vous devez en avoir une.

• Accédez à Google AI Studio : https://aistudio.google.com/.
• Connectez-vous avec votre compte Gmail.
• Cliquez sur le bouton Obtenir une clé API, généralement situé dans le volet de navigation de gauche ou en haut à droite.
• Dans la boîte de dialogue Clés API, cliquez sur "Créer une clé API dans un nouveau projet".
• Choisissez le nouveau projet que vous avez créé et pour lequel un compte de facturation est configuré.
• Une clé API sera générée pour vous. Copiez immédiatement cette clé et stockez-la temporairement dans un endroit sûr (comme un gestionnaire de mots de passe ou une note sécurisée). Il s'agit de la valeur que vous utiliserez dans les étapes suivantes.

Authentification GitHub

Ouvrez Cloud Shell en accédant à la console Google Cloud, puis cliquez sur le bouton "Activer Cloud Shell" en haut à droite.

Étape 1 : Ouvrez Cloud Shell

👉 Cliquez sur "Activer Cloud Shell" en haut de la console Google Cloud (icône en forme de terminal en haut du volet Cloud Shell),

👉 Cliquez sur le bouton "Ouvrir l'éditeur" (icône en forme de dossier ouvert avec un crayon). L'éditeur de code Cloud Shell s'ouvre dans la fenêtre. Un explorateur de fichiers s'affiche sur la gauche.

👉 Trouvez votre ID de projet Google Cloud :

• Ouvrez la console Google Cloud : https://console.cloud.google.com
• Sélectionnez le projet que vous souhaitez utiliser pour cet atelier dans le menu déroulant en haut de la page.
• L'ID de votre projet est affiché dans la fiche "Informations sur le projet" du tableau de bord.

👉 Ouvrez le terminal dans l'IDE cloud.

👉💻 Dans le terminal, vérifiez que vous êtes déjà authentifié et que le projet est défini sur votre ID de projet à l'aide de la commande suivante :

gcloud auth list

Étape 2 : S'authentifier auprès de GitHub et dupliquer le dépôt

S'authentifier avec GitHub :

👉💻

gh auth login

copier le code sur la page de validation de la connexion

Fork et clonez le dépôt : 👉💻

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

3. Architecture : de l'idée au plan avec Cloud Assist

Tout grand projet commence par une vision claire. Nous allons utiliser notre copilote d'IA, Cloud Assist, pour concevoir l'architecture de notre application.

Actions

• Ouvrez la console Google Cloud : https://console.cloud.google.com
• En haut à droite, cliquez sur "Ouvrir le chat Cloud Assist".

Activer Cloud Assist

• Cliquez sur Get Gemini Assist, puis sur Enable Cloud Assist at no cost.
• Et commencez à discuter !

 Fournissez la requête détaillée suivante à Cloud Assist :

Saisissez votre idée

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.

Obtenir le plan de votre application

• Cliquez sur "Modifier la conception de l'application" pour afficher le diagramme. Cliquez sur le panneau en haut à droite "<> Obtenir le code" pour télécharger le code Terraform.
• Cloud Assist génère un schéma d'architecture. Voici notre plan visuel.

Point clé à retenir : l'IA excelle dans la conception de systèmes de haut niveau. Il peut traduire instantanément des exigences en langage clair en une architecture visuelle professionnelle.

4. Développement : compiler l'ADK avec la CLI Gemini

Configuration initiale

Assurez-vous d'utiliser la CLI Gemini pour forker le dépôt et préparer l'espace de travail :

Configuration de l'environnement

Accédez à Cloud Shell, puis cliquez sur le bouton "Ouvrir le terminal".

1. Copiez le modèle d'environnement :

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

Afficher le fichier caché dans l'éditeur si vous ne trouvez pas .env

• Cliquez sur Afficher dans la barre de menu supérieure.
• Sélectionnez Afficher/Masquer les fichiers cachés.

Modifier le fichier .env 2. Remplacez les valeurs suivantes dans .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

Par exemple, si votre ID de projet est testproject, vous devez saisir GOOGLE_CLOUD_PROJECT_ID=testproject et GENMEDIA_BUCKET=testproject-bucket.

Scripts de configuration

Accédez à 00_Starting_Here. Ouvrez un nouveau terminal (pas dans la CLI Gemini).

cd ~/storygen-learning/00_Starting_Here

Exécutez la configuration complète :

./setup-complete.sh

Les résultats de la configuration devraient s'afficher dans le terminal.

Créer votre premier agent

Accédez à 01a_First_Agent_Ready. Utilisons la CLI Gemini pour créer l'agent ADK :

cd ~/storygen-learning/01a_First_Agent_Ready

Ouvrir la CLI Gemini

gemini

Dans la fenêtre Gamini CLI, essayez l'invite suivante :

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

Une fois terminé, désactivez le terminal de la CLI Gemini avec Control+C.

—————————————— Facultatif, vous pouvez passer directement à la section Solution——————————————–

Valider votre modification dans ADK Web

cd ~/storygen-learning/01a_First_Agent_Ready/backend

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

adk web --port 8080

Lancer le site Web

cd ~/storygen-learning/01a_First_Agent_Ready

./start.sh

Si votre modification ne fonctionne pas, vous devriez voir des erreurs dans l'interface utilisateur Web de l'ADK et sur le site Web.

—————————————— Solution à partir d'ici ——————————————–

Solution

Mettez fin au processus précédent avec Control+C ou ouvrez un autre terminal :

cd ~/storygen-learning/01b_First_Agent_Done

Lancer le site Web :

./start.sh

Le site Web s'affiche :

Essayez l'UI de l'ADK : ouvrez un autre terminal :

cd ~/storygen-learning/01b_First_Agent_Done/backend

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

adk web --port 8080

L'interface utilisateur de l'ADK s'affiche, ce qui vous permet de poser des questions à l'agent.

Avant de passer à la section suivante, appuyez sur Ctrl+C pour mettre fin au processus.

5. Développement : créer votre agent personnalisé avec Imagen

Générer l'outil Imagen (second agent)

cd ~/storygen-learning/02a_Image_Agent_Ready

Utilisez la CLI Gemini pour créer l'agent de génération d'images :

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

"

—————————————— Facultatif, vous pouvez passer directement à la section Solution——————————————–

Valider votre modification dans ADK Web

cd ~/storygen-learning/02a_Image_Agent_Ready/backend

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

adk web --port 8080

Lancer le site Web

cd ~/storygen-learning/02a_Second_Agent_Ready

./start.sh

Si votre modification ne fonctionne pas, vous devriez voir des erreurs dans l'interface utilisateur Web de l'ADK et sur le site Web.

—————————————- Solution Starting Here ——————————————–

Solution

Mettez fin au processus précédent avec Control+C ou ouvrez un autre terminal :

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

Lancer le site Web :

./start.sh

Le site Web s'affiche :

Essayez l'UI de l'ADK : ouvrez un autre terminal :

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

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

adk web --port 8080

L'interface utilisateur de l'ADK s'affiche, et vous pouvez y poser des questions à l'agent :

Avant de passer à la section suivante, appuyez sur Ctrl+C pour mettre fin au processus.

6. Tests : évaluation de l'agent

Notre application fonctionne, mais nous avons besoin d'un filet de sécurité automatisé de tests. C'est une tâche idéale à déléguer à notre copilote IA.

Actions

cd ~/storygen-learning/03a_Agent_Evaluation_Ready/backend

Utilisez la CLI Gemini pour écrire des tests complets :

Ouvrir la CLI Gemini

gemini

Dans la fenêtre Gamini CLI, essayez l'invite suivante :

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.

—————————————— Facultatif, vous pouvez passer directement à la section Solution——————————————–

Pour afficher l'évaluation :

./run_adk_web_persistent.sh

Accédez à l'onglet eval de l'interface utilisateur ADK.

Vous devriez voir l'interface utilisateur Web de l'ADK avec des fonctionnalités de test persistantes.

Point clé à retenir : l'IA est un partenaire puissant pour automatiser l'assurance qualité. Il peut gérer le code récurrent de l'écriture de tests, ce qui vous permet de vous concentrer sur la création de fonctionnalités.

—————————————— Solution à partir d'ici ——————————————–

Solution

• Accédez au dossier de la solution :

cd ~/storygen-learning/03b_Agent_Evaluation_Done/backend

• Ouvrir l'interface utilisateur Web de l'ADK

./run_adk_web_persistent.sh

Vous pouvez consulter les scénarios de test dans l'onglet Eval :

Ajustez les métriques ici :

Affichez le résultat de l'exécution de l'évaluation ici :

7. Infrastructure as Code (IaC) : créer un environnement dans le cloud

Notre code est testé, mais il a besoin d'un emplacement prêt pour la production. Nous allons utiliser l'Infrastructure as Code pour définir notre environnement.

Actions

cd ~/storygen-learning/04a_Manual_Deployment_Ready

Utilisez la CLI Gemini pour créer un fichier Dockerfile pour le backend : ouvrez la CLI Gemini.

Gemini

Dans la CLI Gemini, essayez le prompt suivant :

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.

Solution :

cd ~/storygen-learning/04b_Manual_Deployment_Done

Exécutez la commande suivante :

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

./02-build-images.sh

./03-deploy-infrastructure.sh

Vous devriez voir les résultats du déploiement et la création de l'infrastructure.

8. Automatisation (CI/CD) : la chaîne de montage numérique

Le déploiement manuel de notre application est lent et risqué. Demandons à notre IA d'écrire un pipeline CI/CD complet à l'aide de GitHub Actions.

Actions

cd ~/storygen-learning/05a_CICD_Pipeline_Ready

Utilisez Gemini CLI pour créer votre pipeline CI/CD avec GitHub :

Ouvrir la CLI Gemini

Gemini

Dans la CLI Gemini, essayez le prompt suivant :

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.

—————————————— Solution à partir d'ici ——————————————–

Solution :

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

Revenez au dossier 06_Final_Solution et exécutez le script :

cd ~/storygen-learning/06_Final_Solution/

./setup-cicd-complete.sh

Vous devriez voir que la configuration du pipeline CI/CD est terminée.

Déclenchez le workflow : validez et transférez votre code vers la branche principale. Notez que vous devez configurer votre adresse e-mail et votre nom GitHub pour autoriser l'accès.

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

Accédez à l'onglet "Actions" de votre dépôt GitHub pour suivre l'exécution de votre déploiement automatisé.

Point clé à retenir : l'intégralité du pipeline CI/CD, un élément complexe et essentiel de DevOps, peut être générée par l'IA.

9. Opérations : la tour de contrôle de l'IA

Nous sommes en direct ! Mais le chemin n'est pas terminé. C'est le "jour 2", celui des opérations. Revenons à Cloud Assist pour gérer notre application en cours d'exécution.

Actions

1. Accédez à votre service Cloud Run dans la console Google Cloud. Interagissez avec votre application en direct pour générer du trafic et des journaux.
2. Ouvrez le volet Cloud Assist et utilisez-le comme copilote opérationnel avec des requêtes comme celles-ci :

Analyse des journaux :

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

Ajustement des performances :

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?

Optimisation des coûts :

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

Point clé à retenir : Le cycle de vie du développement logiciel de l'IA est une boucle continue. Le même copilote d'IA qui a contribué à créer l'application est un partenaire indispensable pour la surveiller, la dépanner et l'optimiser en production.