Cette page a été traduite par l'API Cloud Translation.

Des prototypes aux agents avec l'ADK

1. Présentation

Où commence le développement avec l'IA aujourd'hui ? Pour la plupart d'entre nous, cela commence souvent par une question simple : "Le modèle peut-il vraiment m'aider à résoudre le problème auquel je pense ?". C'est là que Google AI Studio entre en jeu. Vous pouvez y prototyper rapidement n'importe quoi. Je veux refaire ma cuisine et je suis sûr que Gemini peut m'aider, mais je suis ingénieur, pas entrepreneur général. Je ne sais même pas quoi demander, il y a tellement de choses à prendre en compte : les réglementations, les installations, etc. Alors, décomposons le problème et demandons à Gemini de générer une requête très détaillée pour nous, puis de générer un plan de rénovation complet et de visualiser la transformation ! Mais attendez. Comment puis-je aider les entreprises à évoluer à partir de maintenant ? Saisissez AGENTS!!!

Un agent est un programme autonome qui communique avec un modèle d'IA pour effectuer une opération basée sur un objectif à l'aide des outils et du contexte dont il dispose. Il est capable de prendre des décisions autonomes basées sur la vérité.

Agent Development Kit (ADK)

Agent Development Kit (ADK) est un framework flexible et modulaire permettant de développer et de déployer des agents IA. ADK permet de créer des applications sophistiquées en composant plusieurs instances d'agent distinctes dans un système multi-agents (MAS).

Dans ADK, un système multi-agents est une application dans laquelle différents agents, formant souvent une hiérarchie, collaborent ou se coordonnent pour atteindre un objectif plus vaste. Cette structure offre des avantages considérables, y compris une modularité, une spécialisation, une réutilisabilité et une facilité de maintenance améliorées, ainsi que la possibilité de définir des flux de contrôle structurés à l'aide d'agents de workflow dédiés.

Ce que vous allez faire

Prêt à passer de notre PROMPT de prototype à la création d'un agent ? Nous allons créer un agent pour générer le document de proposition pour le projet de rénovation de la cuisine. Au cours de cet atelier, vous allez :

Créer un agent simple pour générer un document de proposition de rénovation avec ADK
Stocker le document de proposition de rénovation généré dans un bucket Cloud Storage
Tester l'agent dans Cloud Shell et dans la sortie Web de l'agent

Conditions requises

Un navigateur tel que Chrome ou Firefox
Un projet Google Cloud avec facturation activée.

2. Avant de commencer

Créer un projet

Dans la console Google Cloud, sur la page du sélecteur de projet, sélectionnez ou créez un projet Google Cloud.
Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet .
Si vous lisez ce guide et que vous souhaitez obtenir des crédits pour vous aider à démarrer avec Google Cloud et à utiliser l'ADK, cliquez sur ce lien pour utiliser vos crédits.
Pour l'utiliser, suivez les instructionsici. Veuillez noter que ce lien n'est valable que jusqu'au 15 juillet 2025.
Cliquez sur ce lien pour activer Cloud Shell. Vous pouvez basculer entre le terminal Cloud Shell (pour exécuter des commandes cloud) et l'éditeur (pour créer des projets) en cliquant sur le bouton correspondant dans Cloud Shell.
Une fois connecté à Cloud Shell, 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

Exécutez la commande suivante dans Cloud Shell pour vérifier que la commande gcloud connaît votre projet.

gcloud config list project

Si votre projet n'est pas défini, utilisez la commande suivante pour le définir :

gcloud config set project <YOUR_PROJECT_ID>

Assurez-vous d'avoir Python 3.9 ou version ultérieure.

Consultez la documentation pour connaître les autres commandes gcloud ainsi que leur utilisation.

3. Prototype

Accédez à Google AI Studio. Commencez à saisir votre requête. Voici ma requête :

I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.

Ajustez et configurez les paramètres à droite pour obtenir une réponse optimale.

À partir de cette simple description, Gemini m'a fourni une requête incroyablement détaillée pour lancer mes travaux de rénovation ! En effet, nous utilisons Gemini pour obtenir des réponses encore plus pertinentes d'AI Studio et de nos modèles. Vous pouvez également sélectionner différents modèles à utiliser, en fonction de votre cas d'utilisation.

Nous avons choisi Gemini 2.5 Pro. Il s'agit d'un modèle Thinking, ce qui signifie que nous obtenons encore plus de jetons de sortie, dans ce cas jusqu'à 65 000 jetons, pour les analyses longues et les documents détaillés. La boîte de réflexion Gemini s'affiche lorsque vous activez Gemini 2.5 Pro, qui dispose de capacités de raisonnement natives et peut traiter les requêtes de contexte long.

Consultez l'extrait de la réponse ci-dessous :

AI Studio a analysé mes données et a produit tous ces éléments : meubles, plans de travail, crédence, revêtement de sol, évier, cohésion, palette de couleurs et sélection des matériaux. Gemini cite même ses sources !

Essayez maintenant de voir l'idée prendre vie avec un autre prompt.

Copiez ce prompt et collez-le dans l'éditeur de requêtes :

Add flat and circular light accessories above the island area for my current kitchen in the attached image.

Joignez une image de votre cuisine actuelle (ou utilisez mon exemple d'image de cuisine).
Remplacez le modèle par "Gemini 2.0 Flash Preview Image Generation" pour pouvoir générer des images.

J'ai obtenu le résultat suivant :

C'est là l'intérêt de Gemini !

Comprendre des vidéos, générer des images de manière native, ancrer des informations réelles avec la recherche Google… Certaines choses ne peuvent être créées qu'avec Gemini.

Dans AI Studio, vous pouvez prendre ce prototype, récupérer la clé API et le faire évoluer vers une application agentique complète grâce à la puissance de Vertex AI ADK.

4. Configuration d'ADK

Passons maintenant au terminal Cloud Shell que nous avons activé dans la section "Avant de commencer" :

Créer et activer un environnement virtuel (recommandé)

Depuis votre terminal Cloud Shell, créez un environnement virtuel :

python -m venv .venv

Activez l'environnement virtuel :

source .venv/bin/activate

Installer ADK

pip install google-adk

5. Structure du projet

Dans le terminal Cloud Shell, créez un répertoire racine pour vos applications agentiques à l'emplacement de votre choix dans le projet :

mkdir agentic-apps

Dans le répertoire principal, créez un dossier spécifique à notre projet actuel :

mkdir renovation-agent

Accédez à l'éditeur Cloud Shell et créez la structure de projet suivante en créant les fichiers (vides au début) :

renovation-agent/
        __init__.py
        agent.py
        requirements.txt
        .env

6. Code source

Accédez à "init.py" et mettez à jour le contenu comme suit :

from . import agent

Accédez à agent.py et mettez à jour le fichier avec le contenu suivant à partir du chemin d'accès suivant :

Dans agent.py, nous importons les dépendances nécessaires, récupérons les paramètres de configuration du fichier .env et définissons le root_agent qui génère un document de proposition et le stocke dans un bucket Cloud Storage. Pour l'étape Cloud Storage, nous utilisons un outil appelé store_pdf.

REMARQUE : Le PDF n'est actuellement PAS FORMATÉ. D'après la demande d'extraction de la communauté des développeurs, l'extrait suivant a été inclus ici [non testé]. N'hésitez pas à l'adapter dans la méthode store_pdf :

doc = SimpleDocTemplate(
        pdf_buffer,
        pagesize=letter,
        rightMargin=0.75 * inch,
        leftMargin=0.75 * inch,
        topMargin=0.75 * inch,
        bottomMargin=0.75 * inch
    )

    styles = getSampleStyleSheet()
    story = []

    # --- CUSTOM STYLES FOR HEADERS ---
    # Define a new style for section headers
    styles.add(ParagraphStyle(name='SectionHeader',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold', # Make it bolder
                              fontSize=14,               # Make it slightly larger
                              leading=16,                # Line spacing
                              spaceAfter=0.15 * inch,    # Space after the header
                              spaceBefore=0.25 * inch,   # Space before the header
                              textColor=black            # Ensure color is bright/black (default is usually black, but explicit is good)
                             ))

    # Define a style for the main document title
    styles.add(ParagraphStyle(name='DocumentTitle',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold',
                              fontSize=20,
                              leading=24,
                              spaceAfter=0.25 * inch,
                              alignment=TA_CENTER, # Center align the title
                              textColor=black
                             ))
    # ---------------------------------

    paragraphs_raw = pdf_text.split('\n\n')

    # Heuristic for the garbled line issue (as before, temporary)
    if paragraphs_raw and len(paragraphs_raw[-1]) < 50 and any(char in paragraphs_raw[-1] for char in ['io', 'og', 'al', 'op']):
         logger.warning("Detected potentially garbled last paragraph. Attempting to trim/omit.")
         paragraphs_raw[-1] = "11. Entire Agreement:\nThis proposal constitutes the entire agreement between the parties and supersedes all prior discussions and agreements."


    for i, para_text in enumerate(paragraphs_raw):
        para_text = para_text.strip()
        if not para_text:
            continue

        # Special handling for the main document title (PROPOSAL DOCUMENT)
        if i == 0 and "PROPOSAL DOCUMENT" in para_text.upper():
            p = Paragraph("PROPOSAL DOCUMENT", styles['DocumentTitle'])
            story.append(p)
            story.append(Spacer(1, 0.15 * inch)) # Add space after the title
            # Skip the rest of this initial block if it's just the title
            remaining_text_lines = para_text.splitlines()[1:]
            if remaining_text_lines:
                formatted_text = "<br/>".join(remaining_text_lines)
                p = Paragraph(formatted_text, styles['Normal'])
                story.append(p)
                story.append(Spacer(1, 0.1 * inch))
            continue # Move to the next paragraph

        # Check if the paragraph looks like a section header (e.g., starts with a number and dot or just bold text)
        # This is a heuristic and might need fine-tuning based on actual proposal content variability.
        is_section_header = False
        # Check for numbered sections (e.g., "1. Scope of Work:")
        if para_text.startswith(('1.', '2.', '3.', '4.', '5.', '6.', '7.', '8.', '9.', '10.', '11.')):
            is_section_header = True
        # Check for Exhibit headers (e.g., "Exhibit A: Cabinet Design") or Roman numeral headings
        elif para_text.startswith(('Exhibit ', 'I.', 'II.', 'III.', 'IV.', 'V.', 'VI.', 'VII.')):
            is_section_header = True
        # Check for specific known headers
        elif para_text.strip().upper() in ["IN WITNESS WHEREOF,", "EXHIBITS:"]:
            is_section_header = True


        if is_section_header:
            p = Paragraph(para_text, styles['SectionHeader'])
            story.append(p)
            # No additional Spacer here, as SectionHeader style has spaceAfter
        else:
            formatted_text = para_text.replace('\n', '<br/>')
            p = Paragraph(formatted_text, styles['Normal'])
            story.append(p)
            story.append(Spacer(1, 0.1 * inch)) # Standard space after body paragraphs

    doc.build(story)

    pdf_buffer.seek(0)

    # Upload the PDF to GCS
    storage_client = storage.Client()
    bucket = storage_client.bucket(STORAGE_BUCKET)
    blob = bucket.blob(PROPOSAL_DOCUMENT_FILE_NAME)

    blob.upload_from_file(pdf_buffer, content_type="application/pdf")

    logger.info(f"Successfully uploaded PDF to gs://{STORAGE_BUCKET}/{PROPOSAL_DOCUMENT_FILE_NAME}")

except Exception as e:
    logger.error(f"Error writing text to PDF and uploading: {e}")
    raise
finally:
    if 'pdf_buffer' in locals():
        pdf_buffer.close()
return "Successfully uploaded PDF to GCS!!"

Assurez-vous d'avoir le bucket Cloud Storage

Cela permet de stocker le document de proposition généré par l'agent. Créez-le et provisionnez l'accès pour que le système agentique que nous créons avec Vertex AI puisse y accéder. Voici comment procéder :

https://cloud.google.com/storage/docs/creating-buckets#console

Nommez votre bucket "next-demo-store". Si vous lui donnez un autre nom, n'oubliez pas de mettre à jour la valeur de STORAGE_BUCKET dans le fichier .env (à l'étape de configuration des variables d'environnement).

Pour configurer l'accès au bucket, accédez à la console Cloud Storage et à votre bucket de stockage (dans notre cas, le nom du bucket est "next-demo-storage") : https://console.cloud.google.com/storage/browser/next-demo-storage.

Accédez à Autorisations > Afficher les comptes principaux > Accorder l'accès. Sélectionnez "allUsers" comme principal et "Utilisateur des objets Storage" comme rôle.

Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.

Créer une liste de dépendances

Listez toutes les dépendances dans requirements.txt. Vous pouvez le copier depuis le dépôt.

Explication du code source du système à agent unique

Le fichier agent.py définit la structure et le comportement de notre système multi-agents de rénovation de cuisine à l'aide de l'Agent Development Kit (ADK). Découvrons les principaux composants :

Définition d'un agent

Agent racine (outil d'orchestration) : proposal_agent

L'agent racine agit en tant qu'orchestrateur de ce système à agent unique. Il reçoit la demande de rénovation initiale et détermine les outils à invoquer en fonction des besoins de la demande.

L'agent racine collecte ensuite les réponses des outils et les combine pour fournir une réponse complète à l'utilisateur. Dans ce cas, nous n'avons qu'un seul outil, "store_pdf".

7. Flux de données et concepts clés

L'utilisateur lance une requête via l'interface ADK (terminal ou interface utilisateur Web).

La demande est reçue par l'agent racine.
L'agent racine analyse la requête et la transmet à l'outil si nécessaire.
L'outil "store_pdf" est conçu pour écrire le contenu textuel rénové dans un fichier PDF, puis l'importer dans Google Cloud Storage.
La réponse est ensuite renvoyée à l'agent racine.
L'agent racine combine les réponses et fournit un résultat final à l'utilisateur.

LLM (grands modèles de langage)

Les agents s'appuient fortement sur les LLM pour générer du texte, répondre à des questions et effectuer des tâches de raisonnement. Les LLM sont le "cerveau" qui permet aux agents de comprendre les requêtes des utilisateurs et d'y répondre. Nous utilisons Gemini 2.5 dans cette application.

Google Cloud Storage

Permet de stocker les documents de proposition de rénovation générés. Vous devez créer un bucket et accorder les autorisations nécessaires aux agents pour y accéder.

Cloud Run (facultatif)

OrderingAgent utilise une fonction Cloud Run pour interagir avec AlloyDB. Cloud Run fournit un environnement sans serveur pour exécuter du code en réponse aux requêtes HTTP.

AlloyDB

Si vous utilisez OrderingAgent, vous devez configurer une base de données AlloyDB pour stocker les informations sur les commandes.

Fichier.env

Le fichier .env stocke des informations sensibles telles que les clés API, les identifiants de base de données et les noms de buckets. Il est essentiel de conserver ce fichier de manière sécurisée et de ne pas l'inclure dans votre dépôt. Il stocke également les paramètres de configuration des agents et de votre projet Google Cloud. Les fonctions root_agent ou d'assistance lisent généralement les valeurs de ce fichier. Assurez-vous que toutes les variables requises sont correctement définies dans le fichier .env. (y compris le nom du bucket Cloud Storage)

8. Configuration du modèle

La capacité de votre agent à comprendre les requêtes des utilisateurs et à générer des réponses repose sur un grand modèle de langage (LLM). Votre agent doit effectuer des appels sécurisés à ce service LLM externe, ce qui nécessite des identifiants d'authentification. Sans authentification valide, le service LLM refusera les requêtes de l'agent, qui ne pourra pas fonctionner.

Obtenez une clé API depuis Google AI Studio.
À l'étape suivante, lorsque vous configurez le fichier .env, remplacez <<your API KEY>> par la valeur de votre clé API.

9. Configurer les variables d'environnement

Configurez vos valeurs pour les paramètres dans le fichier .env du modèle dans ce dépôt. Dans mon cas, le fichier .env contient les variables suivantes :

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION = us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT = <<your project id>>
PROJECT_ID = <<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>

Remplacez les espaces réservés par vos valeurs.

10. Exécuter votre agent

Dans le terminal, accédez au répertoire parent de votre projet d'agent :

cd agentic-apps/renovation-agent

Installer toutes les dépendances

pip install -r requirements.txt

Vous pouvez exécuter la commande suivante dans votre terminal Cloud Shell pour exécuter l'agent :

adk run .

Pour l'exécuter dans une interface utilisateur Web provisionnée par ADK, vous pouvez exécuter la commande suivante :

Remarque : Vous devez exécuter cette commande en dehors du dossier de votre projet d'agent. Pour ce faire, sortez du dossier, puis exécutez la commande :

adk web

Effectuez un test avec les requêtes suivantes :

user>> 

Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.

11. Résultat

Pour la commande adk run . Le résultat est le suivant"

…

Vous pouvez vérifier si le document de proposition de rénovation a été créé dans le bucket Cloud Storage.

12. Déployer dans Cloud Run

Créez un fichier nommé Dockerfile dans le dossier racine du projet :

cd agentic-apps/renovation-agent

Copier le contenu du dépôt GitHub

https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/Dockerfile

dans ce fichier Dockerfile.

Déployez sur Cloud Run à l'aide de la commande suivante :

adk deploy cloud_run --project=abis-345004 --region=us-central1 --service_name=renovation-agent --app_name=renovation-app --with_ui .

Et voilà ! Une fois le point de terminaison déployé, il devrait s'afficher dans le terminal et être prêt à l'emploi.

13. Effectuer un nettoyage

Pour éviter que les ressources utilisées dans cet article soient facturées sur votre compte Google Cloud, procédez comme suit :

Dans la console Google Cloud, accédez à la page Gérer les ressources.
Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.

14. Félicitations

Félicitations ! Vous avez créé votre application multi-agents et interagi avec elle à l'aide d'ADK. Le système multi-agents est conçu pour simplifier le processus de rénovation de la cuisine en automatisant des tâches telles que la génération de propositions, la vérification des permis et le suivi de l'état des commandes. Chaque agent a un rôle spécifique, et l'agent racine coordonne leurs activités pour fournir une solution complète. Le système s'appuie sur des LLM, des services Google Cloud et potentiellement des API externes pour fournir ses fonctionnalités. Cliquez ici pour accéder à la documentation du produit.