Créer une intégration avec un agent IA et des compétences d'agent Application Integration

1. Introduction

Dans cet atelier, vous allez créer une intégration Application Integration en la décrivant à un agent IA. Vous allez installer les trois compétences d'agent Application Integration publiques à partir du dépôt google/skills, puis demander à Gemini CLI d'écrire, d'importer, de publier et d'exécuter un petit exemple d'intégration.

L'exemple sample-claims-adjudication prend une demande d'indemnisation et renvoie APPROVE, REVIEW ou DENY.

Objectifs de l'atelier

  • Configurer Application Integration dans un projet Google Cloud
  • Installez les compétences de l'agent Application Integration.
  • Demander à Gemini CLI de créer, d'importer, de publier et d'exécuter une intégration
  • Vérifiez l'exécution vous-même et demandez à l'agent de résoudre le problème.
  • Nettoyez l'exemple d'intégration.

Points abordés

  • Ce que les compétences application-integration-basics, -authoring et -troubleshooting apportent à un agent.
  • Comment examiner le fichier JSON de la version d'intégration et les commandes exécutées par l'agent avant de les approuver.
  • Comment lire un enregistrement d'exécution.

2. Configuration du projet

  1. Si vous n'avez pas encore de compte Google, vous devez en créer un.
    • Utilisez un compte personnel au lieu d'un compte professionnel ou scolaire. Les comptes professionnels et scolaires peuvent être soumis à des restrictions qui vous empêchent d'activer les API nécessaires pour cet atelier.
  2. Connectez-vous à la console Google Cloud.
  3. Activez la facturation dans la console Cloud.
    • La réalisation de cet atelier devrait coûter moins de 1 $ en ressources cloud.
    • Vous pouvez suivre les étapes à la fin de cet atelier pour supprimer les ressources afin d'éviter des frais supplémentaires.
    • Les nouveaux utilisateurs peuvent bénéficier d'un essai sans frais de 300 $.
  4. Créez un projet ou choisissez de réutiliser un projet existant.
    • Si une erreur concernant le quota de projets s'affiche, réutilisez un projet existant ou supprimez-en un pour en créer un autre.

Utilisez un nouveau projet ou un projet existant dans lequel vous pouvez faire des tests en toute sécurité, et non un projet de production. L'agent importe, publie et exécute des intégrations dans cet environnement avec vos identifiants.

3. Ouvrir l'éditeur Cloud Shell

  1. Cliquez sur ce lien pour accéder directement à l'éditeur Cloud Shell.
  2. Si vous êtes invité à autoriser une action aujourd'hui, cliquez sur Autoriser pour continuer. Cliquez pour autoriser Cloud Shell
  3. Si le terminal ne s'affiche pas en bas de l'écran, ouvrez-le :
    • Cliquez sur Afficher.
    • Cliquez sur TerminalOuvrir un nouveau terminal dans l'éditeur Cloud Shell
  4. Dans le terminal, définissez votre projet à l'aide de cette commande :
    • Format :
      gcloud config set project [PROJECT_ID]
      
    • Exemple :
      gcloud config set project lab-project-id-example
      
    • Si vous ne vous souvenez pas de l'ID de votre projet :
      • Vous pouvez lister tous les ID de vos projets à l'aide de la commande suivante :
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
        
      Définir l'ID du projet dans le terminal de l'éditeur Cloud Shell
  5. Le message suivant doit s'afficher :
    Updated property [core/project].
    
    Si vous voyez WARNING et que vous êtes invité à Do you want to continue (Y/n)?, vous avez probablement saisi un ID de projet incorrect. Appuyez sur n, puis sur Enter, et essayez d'exécuter à nouveau la commande gcloud config set project.

4. Configurer Application Integration

Application Integration est régional. Vous le configurez donc dans une région. Cet atelier utilise us-central1.

  1. Notez l'ID de votre projet. Vous devrez le coller dans une invite ultérieurement :
    gcloud config get-value project
    
  2. Activez l'API Application Integration :
    gcloud services enable integrations.googleapis.com
    
  3. Accédez à la page Application Integration dans la console Google Cloud, puis sélectionnez votre projet.
  4. Sur la page Vue d'ensemble, sélectionnez la région us-central1, puis cliquez sur Configuration rapide. Une fois la configuration terminée, la console affiche la liste Intégrations. Si vous réutilisez un projet, vérifiez que vous disposez des rôles listés dans Configurer Application Integration avant de cliquer sur Configuration rapide.

Pour en savoir plus, consultez Configurer Application Integration.

5. Installer les compétences de l'agent

Les compétences fournissent à l'agent ses connaissances sur Application Integration :

  • application-integration-basics : concepts, activation des API, provisionnement d'une région, rôles IAM et limites.
  • application-integration-authoring : écrire des versions d'intégration au format JSON, puis les importer, les publier et les exécuter.
  • application-integration-troubleshooting : diagnostiquer les exécutions ayant échoué, bloquées ou silencieuses.
  1. Créez un répertoire pour cet atelier et accédez-y :
    mkdir ~/appint-agent-lab && cd ~/appint-agent-lab
    
  2. Installez les trois compétences :
    npx skills add google/skills --skill application-integration-basics
    npx skills add google/skills --skill application-integration-authoring
    npx skills add google/skills --skill application-integration-troubleshooting
    
    Pour chaque compétence, le programme d'installation pose quelques questions. Gemini CLI est inclus dans l'option Universal (.agents/skills) par défaut. Appuyez donc sur Enter pour la conserver, choisissez Project (Projet) comme champ d'application de l'installation, puis confirmez l'installation.

Les compétences sont désormais en ~/appint-agent-lab/.agents/skills.

6. Lancer Gemini CLI

  1. Lancez la CLI Gemini à partir du répertoire de l'atelier :
    gemini
    
    Lorsque Gemini CLI vous demande si vous faites confiance à ce dossier, sélectionnez Trust folder (Faire confiance au dossier). Gemini CLI ne charge les compétences d'un dossier de projet qu'après que vous avez approuvé le dossier, puis redémarre. Si elle ne redémarre pas, ouvrez un nouveau terminal, accédez à ~/appint-agent-lab et exécutez à nouveau gemini. Vous devrez peut-être appuyer sur Enter pour accepter certains paramètres par défaut.
  2. Répertoriez les compétences que Gemini CLI peut utiliser :
    /skills
    
    Les trois compétences application-integration-* devraient s'afficher dans la liste.

7. Créer, publier et exécuter l'intégration

  1. Collez ce prompt dans Gemini CLI. Remplacez PROJECT_ID par l'ID du projet que vous avez noté dans Configurer Application Integration.
    Using the Application Integration skills, build an integration named
    sample-claims-adjudication in project PROJECT_ID, region us-central1.
    
    - Start it with an API trigger named adjudicate_claim.
    - Inputs: claimId (string), claimAmount (double), policyActive (boolean).
    - Outputs: decision (string) and reason (string).
    - Rules: if policyActive is false, return DENY. If claimAmount is 1000 or less,
      return APPROVE. Otherwise, return REVIEW. Set reason to a short explanation.
    - Save the integration version JSON in this directory so I can review it.
    - Show me every command before you run it, then upload, publish, and run it
      once with a sample claim.
    
  2. La première fois que l'agent utilise une compétence, Gemini CLI vous demande de l'activer. Autorisez-le.
  3. L'agent écrit un fichier de version d'intégration, tel que sample-claims-adjudication.json. Il contient le déclencheur (triggerConfigs), les tâches (taskConfigs) et les variables (integrationParameters). Lisez-le et demandez à l'agent de vous expliquer tout ce qui vous semble inattendu. Par exemple, vérifiez si l'agent a activé Cloud Logging (cloudLoggingDetails.enableCloudLogging), ce qui peut entraîner des frais supplémentaires. Pour la désactiver, définissez enableCloudLogging sur false et supprimez cloudLoggingSeverity.
  4. Approuvez les commandes. Gemini CLI vous demande votre autorisation avant d'exécuter chaque commande, y compris celles en lecture seule. Les compétences indiquent également à l'agent de vous montrer la commande ou la requête exacte avant de modifier quoi que ce soit, par exemple en important, en publiant ou en exécutant l'intégration. Si l'agent demande une approbation sans afficher la commande, demandez-lui de l'afficher. Vérifiez le projet, la région et le nom de l'intégration avant d'approuver, et refusez les commandes qui lisent ou modifient des intégrations qui ne vous appartiennent pas.

Une fois que vous avez approuvé, l'agent importe le fichier JSON en tant que nouvelle version (versions.upload), le publie (versions.publish) et l'exécute via le déclencheur d'API (integrations.execute). Il vous montre ensuite la décision, la raison et l'ID d'exécution.

8. Vérifier l'exécution

Exécutez vous-même l'intégration publiée et lisez son enregistrement d'exécution.

  1. Ouvrez un nouvel onglet de terminal Cloud Shell, accédez au répertoire de l'atelier, puis enregistrez l'ID de votre projet et votre région dans des variables :
    cd ~/appint-agent-lab
    export PROJECT_ID=$(gcloud config get-value project)
    export LOCATION=us-central1
    
  2. Exécutez l'intégration avec une réclamation supérieure à 1 000 :
    curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
          "triggerId": "api_trigger/adjudicate_claim",
          "inputParameters": {
            "claimId": {"stringValue": "CLM-1001"},
            "claimAmount": {"doubleValue": 2500},
            "policyActive": {"booleanValue": true}
          }
        }' \
        "https://integrations.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/integrations/sample-claims-adjudication:execute"
    
    La réponse contient un executionId et un outputParameters avec decision défini sur REVIEW.
  3. Lire l'enregistrement d'exécution. Remplacez EXECUTION_ID par l'ID executionId de la réponse :
    curl -G \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        --data-urlencode 'filter=execution_id="EXECUTION_ID"' \
        "https://integrations.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/integrations/sample-claims-adjudication/executions"
    
    Dans la réponse, executionDetails.state est SUCCEEDED, et executionDetails.executionSnapshots indique l'état de chaque tâche.

Vous pouvez également voir l'exécution dans les journaux d'exécution de la console Google Cloud.

9. Résoudre les problèmes

Une réponse réussie ne signifie pas toujours que chaque tâche a fonctionné comme prévu. Demandez à l'agent de vérifier l'exécution. Dans Gemini CLI, saisissez le prompt suivant en remplaçant EXECUTION_ID :

Check execution EXECUTION_ID of sample-claims-adjudication. Did every task
succeed? If anything failed, tell me why and propose a fix.

L'agent lit l'enregistrement d'exécution avec executions.list, filtré par l'ID d'exécution, et résume l'état de l'exécution et de chaque tâche.

Si vous rencontrez un problème dans cet atelier, vérifiez les causes courantes suivantes :

  • /skills ne liste pas les compétences Application Integration. Démarrez Gemini CLI à partir de ~/appint-agent-lab et faites confiance au dossier.
  • Un appel échoue avec l'erreur PERMISSION_DENIED. Vérifiez que vous utilisez le bon projet et que vous disposez du rôle Éditeur Application Integration (roles/integrations.integrationEditor) sur celui-ci.
  • L'exécution de l'intégration échoue avec l'erreur No integrations found for the requested trigger_id. Vérifiez que le projet et la région de la requête correspondent à l'emplacement où l'intégration est publiée, que triggerId est défini sur api_trigger/adjudicate_claim et qu'une version de l'intégration est publiée. Vous obtenez la même erreur si vous avez importé une version, mais que vous ne l'avez pas publiée.

10. Effectuer un nettoyage

  1. Dans Gemini CLI, demandez à l'agent de supprimer l'exemple d'intégration :
    Unpublish sample-claims-adjudication, then delete every version of it.
    
    Une fois que vous avez approuvé, l'agent annule la publication de la version publiée (versions.unpublish) et supprime chaque version (versions.delete). Lorsqu'il ne reste plus de version, l'intégration n'apparaît plus dans votre liste d'intégrations.Si vous avez créé un projet uniquement pour cet atelier, vous pouvez le supprimer au lieu de supprimer l'intégration. Exécutez cette commande dans l'onglet du terminal que vous avez ouvert dans Vérifier l'exécution :
    gcloud projects delete $(gcloud config get-value project)
    
  2. Saisissez /quit et appuyez sur Enter pour quitter Gemini CLI.
  3. Supprimez le répertoire de l'atelier :
    cd ~ && rm -rf ~/appint-agent-lab
    

11. Félicitations

Vous avez créé, publié, exécuté et vérifié une intégration en envoyant un prompt à un agent IA doté des compétences d'agent Application Integration.

Étape suivante