Créer une intégration avec un agent IA

Cette page vous explique comment créer une intégration en envoyant une requête à un agent de codage IA. Vous décrivez ce que l'intégration doit faire, et l'agent écrit l'intégration, l'importe et la publie avec l'API REST Application Integration, l'exécute et vous aide à résoudre les problèmes. Par exemple, vous créez une intégration simple de règlement des sinistres d'assurance.

L'agent obtient ses connaissances sur Application Integration à partir de trois compétences d'agent publiques dans le dépôt google/skills :

Pour obtenir les fichiers de référence de chaque compétence, consultez Compétences de l'agent Application Integration.

Avant de commencer

  1. Utilisez un projet Google Cloud dans lequel vous pouvez faire des tests en toute sécurité, et non un projet de production. La facturation doit être activée pour le projet.
  2. Configurez Application Integration dans le projet, dans une région prise en charge. La configuration d'Application Integration nécessite ses propres rôles, qui sont listés sur cette page.
  3. Installez la gcloud CLI et connectez-vous avec gcloud auth login. L'agent appelle l'API REST en votre nom, avec vos identifiants gcloud ou, s'il utilise une bibliothèque cliente, avec les Identifiants par défaut de l'application. Si l'agent utilise une bibliothèque cliente, il peut vous demander d'exécuter gcloud auth application-default login.
  4. Utilisez un agent de codage IA compatible avec les compétences d'agent.

Rôles requis

Une fois Application Integration configuré, vous devez disposer des rôles suivants pour créer et exécuter des intégrations.

Pour obtenir les autorisations nécessaires pour importer, publier et exécuter des intégrations, et afficher leurs exécutions, demandez à votre administrateur de vous accorder les rôles IAM suivants :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Pour savoir qui a besoin du rôle "Utilisateur du compte de service" et comment l'accorder, consultez Accorder le rôle "Utilisateur du compte de service" pour les comptes de service d'exécution.

Installer les compétences de l'agent

Dans votre terminal, exécutez les commandes suivantes pour installer 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

Lorsque vous y êtes invité, choisissez les agents à configurer et le champ d'application de l'installation. Si votre agent n'est pas listé, l'option universelle par défaut s'installe dans .agents/skills. Le programme d'installation peut également proposer d'autres compétences, telles que find-skills. Vous n'en avez pas besoin pour cette page. Certains agents ne chargent les compétences d'un dossier de projet qu'une fois que vous avez approuvé ce dossier. Si npx n'est pas disponible, installez Node.js, qui l'inclut. Pour mettre à jour les compétences ultérieurement, exécutez npx skills update.

Décrivez votre intégration

Démarrez votre agent dans un répertoire de travail vide et décrivez l'intégration. Soyez précis sur le déclencheur, les entrées et les sorties, les règles et l'emplacement de déploiement. Exemple :

Using the Application Integration skills, build an integration named
claims-adjudication in project PROJECT_ID, region LOCATION.

- 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.

Remplacez PROJECT_ID par l'ID de votre projet et LOCATION par la région dans laquelle vous avez configuré Application Integration.

Examiner le plan et approuver les commandes

L'agent écrit un fichier de version d'intégration, par exemple claims-adjudication.json. Il contient le déclencheur (triggerConfigs), les tâches (taskConfigs) et les variables (integrationParameters). Lisez-le avant de continuer 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.

Les compétences indiquent à l'agent d'exécuter librement des vérifications en lecture seule, comme lister les intégrations ou les exécutions, mais de vous montrer la commande ou la requête exacte et d'attendre votre approbation avant d'apporter des modifications. Cela inclut l'activation des API, la modification des stratégies IAM, ainsi que l'importation, la publication ou l'exécution d'une intégration. Si l'agent demande une approbation sans afficher la commande ou la requête exacte, demandez-lui de les afficher. Les paramètres d'autorisation de votre agent peuvent également vous demander d'approuver chaque commande, y compris celles en lecture seule. Vérifiez le projet, la région et le nom de l'intégration dans chaque commande avant de l'approuver.

Importer, publier et exécuter l'intégration

Une fois que vous avez approuvé, l'agent effectue les appels d'API Application Integration suivants :

  1. versions.upload importe le fichier JSON en tant que nouvelle version de l'intégration.
  2. versions.publish publie cette version. Une version publiée est ACTIVE, et toute version précédemment publiée est annulée.
  3. integrations.execute exécute l'intégration publiée de manière synchrone via son déclencheur d'API.

Vous pouvez également exécuter vous-même l'intégration publiée :

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/claims-adjudication:execute"

La réponse contient un executionId et les variables de sortie de l'intégration dans outputParameters.

Vérifier l'exécution et résoudre les problèmes

Une réponse positive de integrations.execute ne signifie pas toujours que chaque tâche a fonctionné comme prévu. La stratégie de nouvelle tentative d'une tâche peut permettre à l'exécution de continuer après l'échec de la tâche : avec Ignorer, l'intégration traite la tâche ayant échoué comme réussie, et avec Aucune, l'intégration peut toujours se terminer comme réussie via un autre chemin. De plus, si une requête définit doNotPropagateError sur true, les erreurs sont renvoyées dans la réponse au lieu d'un état d'erreur. Demandez à l'agent de vérifier l'exécution, par exemple :

Check execution EXECUTION_ID of 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 la méthode executions.list, filtrée par ID d'exécution :

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/claims-adjudication/executions"

L'enregistrement indique l'état d'exécution, par exemple SUCCEEDED, FAILED ou SUSPENDED, ainsi que l'état de chaque tâche. Vous pouvez également ouvrir les journaux d'exécution dans la console Google Cloud . Cloud Logging est désactivé par défaut pour les intégrations. Pour l'utiliser, consultez Afficher les journaux d'intégration dans Cloud Logging.

Pour appliquer un correctif, vous devez importer et publier une nouvelle version. Les compétences indiquent donc à l'agent de vous demander à nouveau votre approbation. Après la publication, la version précédente peut continuer à s'exécuter pendant 10 minutes maximum. Attendez donc avant de tester le correctif. La publication annule également les exécutions suspendues de la version précédente, telles que les exécutions en attente d'approbation.

Bonnes pratiques

  • Commencez en dehors de la production. Créez et testez dans un projet hors production, puis promouvez le fichier JSON examiné. Consultez la section Importer et télécharger des intégrations.
  • Utilisez un compte de service d'exécution dédié. Utilisez un compte de service dédié avec un champ d'application minimal pour chaque intégration. Consultez Définir un compte de service d'exécution.
  • Ne stockez pas de secrets dans les variables de configuration. Les variables de configuration sont stockées et exportées en texte brut. Utilisez plutôt un profil d'authentification ou la tâche d'accès Secret Manager.
  • Examinez le fichier JSON généré. Conservez-le dans le contrôle de code source et examinez les modifications avant de les importer. Les profils d'authentification ne sont pas inclus dans le fichier. Vous devez donc les configurer dans chaque projet.

Effectuer un nettoyage

Pour supprimer l'exemple d'intégration, demandez à l'agent :

Unpublish claims-adjudication, then delete every version of it.

Une fois que vous avez approuvé, l'agent appelle versions.unpublish sur la version publiée et versions.delete sur chaque version. Lorsqu'il ne reste plus de versions, l'intégration n'apparaît plus dans votre liste d'intégrations. La suppression de l'intégration elle-même nécessite un rôle tel que "Administrateur Application Integration". Le rôle "Éditeur" ne peut pas effectuer cette opération.

Étapes suivantes