Crea un'integrazione con un agente AI

Questa pagina mostra come creare un'integrazione inviando un prompt a un agente di programmazione AI. Descrivi cosa deve fare l'integrazione e l'agente la scrive, la carica e la pubblica con l'API REST di Application Integration, la esegue e ti aiuta a risolvere i problemi. Ad esempio, crei una semplice integrazione per la liquidazione delle richieste di risarcimento assicurativo.

L'agente ottiene le sue conoscenze di Application Integration da tre skill dell'agente pubbliche nel repository google/skills:

Per i file di riferimento di ogni skill, consulta Skill dell'agente di Application Integration.

Prima di iniziare

  1. Utilizza un progetto Google Cloud in cui puoi sperimentare in sicurezza, non un progetto di produzione. La fatturazione deve essere abilitata per il progetto.
  2. Configura Application Integration nel progetto, in una regione supportata. La configurazione di Application Integration richiede ruoli specifici, elencati in quella pagina.
  3. Installa gcloud CLI e accedi con gcloud auth login. L'agente chiama l'API REST per tuo conto, con le tue credenziali gcloud o, se utilizza una libreria client, con le Credenziali predefinite dell'applicazione. Se l'agente utilizza una libreria client, potrebbe chiederti di eseguire gcloud auth application-default login.
  4. Utilizza un agente di programmazione AI che supporti le competenze dell'agente.

Ruoli obbligatori

Dopo aver configurato Application Integration, devi disporre dei seguenti ruoli per creare ed eseguire le integrazioni.

Per ottenere le autorizzazioni necessarie per caricare, pubblicare ed eseguire integrazioni e visualizzarne le esecuzioni, chiedi all'amministratore di concederti i seguenti ruoli IAM:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Per sapere chi ha bisogno del ruolo Service Account User e come concederlo, consulta Concedi il ruolo Service Account User per i service account run-as.

Installa le skill dell'agente

Nel terminale, esegui i seguenti comandi per installare le tre skill:

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

Quando richiesto, scegli gli agenti da configurare e l'ambito di installazione. Se il tuo agente non è elencato, l'opzione universale predefinita viene installata in .agents/skills. L'installatore potrebbe anche offrire altre competenze, come find-skills; non sono necessarie per questa pagina. Alcuni agenti caricano le skill da una cartella di progetto solo dopo che hai considerato attendibile la cartella. Se npx non è disponibile, installa Node.js, che lo include. Per aggiornare le competenze in un secondo momento, esegui npx skills update.

Descrivi la tua integrazione

Avvia l'agente in una directory di lavoro vuota e descrivi l'integrazione. Specifica il trigger, gli input e gli output, le regole e dove eseguire il deployment. Ad esempio:

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.

Sostituisci PROJECT_ID con l'ID progetto e LOCATION con la regione in cui hai configurato Application Integration.

Esamina il piano e approva i comandi

L'agente scrive un file di versione dell'integrazione, ad esempio claims-adjudication.json. Contiene il trigger (triggerConfigs), le attività (taskConfigs) e le variabili (integrationParameters). Leggilo prima di continuare e chiedi all'agente di spiegarti tutto ciò che non ti aspetti. Ad esempio, controlla se l'agente ha attivato Cloud Logging (cloudLoggingDetails.enableCloudLogging), che può comportare costi aggiuntivi. Per disattivarlo, imposta enableCloudLogging su false e rimuovi cloudLoggingSeverity.

Le competenze indicano all'agente di eseguire liberamente controlli di sola lettura, come l'elenco di integrazioni o esecuzioni, ma di mostrare il comando o la richiesta esatti e attendere la tua approvazione prima di apportare modifiche. Ciò include l'abilitazione delle API, la modifica delle policy IAM e il caricamento, la pubblicazione o l'esecuzione di un'integrazione. Se l'agente chiede l'approvazione senza mostrare il comando o la richiesta esatti, chiedigli di mostrarli. Le impostazioni del set di autorizzazioni dell'agente potrebbero anche chiederti di approvare ogni comando, inclusi quelli di sola lettura. Controlla il progetto, la regione e il nome dell'integrazione in ogni comando prima di approvarlo.

Carica, pubblica ed esegui l'integrazione

Dopo l'approvazione, l'agente effettua le seguenti chiamate API di Application Integration:

  1. versions.upload carica il file JSON come nuova versione dell'integrazione.
  2. versions.publish pubblica la versione. Una versione pubblicata è ACTIVE e qualsiasi versione pubblicata in precedenza non è pubblicata.
  3. integrations.execute esegue l'integrazione pubblicata in modo sincrono tramite il relativo trigger API.

Puoi anche eseguire l'integrazione pubblicata autonomamente:

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 risposta contiene un executionId e le variabili di output dell'integrazione in outputParameters.

Controlla l'esecuzione e risolvi i problemi

Una risposta positiva da integrations.execute non significa sempre che ogni attività ha eseguito ciò che ti aspettavi. La strategia di ripetizione di un'attività può consentire l'esecuzione continua dopo l'errore dell'attività: con Ignora, l'integrazione tratta l'attività non riuscita come riuscita, mentre con Nessuna, l'integrazione può comunque terminare come riuscita tramite un percorso alternativo. Inoltre, se una richiesta imposta doNotPropagateError su true, gli errori vengono restituiti nella risposta anziché come stato di errore. Chiedi all'agente di controllare l'esecuzione, ad esempio:

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

L'agente legge il record di esecuzione con il metodo executions.list, filtrato in base all'ID esecuzione:

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"

Il record mostra lo stato di esecuzione, ad esempio SUCCEEDED, FAILED o SUSPENDED, e lo stato di ogni attività. Puoi anche aprire i log di esecuzione nella console Google Cloud . Cloud Logging è disabilitato per le integrazioni per impostazione predefinita. Per utilizzarlo, consulta Visualizza i log di integrazione in Cloud Logging.

L'applicazione di una correzione comporta il caricamento e la pubblicazione di una nuova versione, quindi le skill indicano all'agente di chiedere prima la tua approvazione. Dopo la pubblicazione, la versione precedente può continuare a essere eseguita per un massimo di 10 minuti, quindi attendi prima di testare la correzione. La pubblicazione annulla anche le esecuzioni sospese della versione precedente, ad esempio quelle in attesa di approvazione.

Best practice

  • Inizia al di fuori della produzione. Crea e testa in un progetto non di produzione, quindi promuovi il file JSON revisionato. Consulta Integrazioni di caricamento e download.
  • Utilizza un service account "run-as" dedicato. Utilizza un account di servizio dedicato con ambito minimo per ogni integrazione. Consulta Imposta un service account "Esegui come".
  • Non includere i secret nelle variabili di configurazione. Le variabili di configurazione vengono archiviate ed esportate in testo normale. Utilizza invece un profilo di autenticazione o l'attività di accesso a Secret Manager.
  • Esamina il file JSON generato. Conservalo nel controllo del codice sorgente ed esamina le modifiche prima di caricarle. I profili di autenticazione non sono inclusi nel file, quindi configurali in ogni progetto.

Esegui la pulizia

Per rimuovere l'integrazione di esempio, chiedi all'agente:

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

Dopo l'approvazione, l'agente effettua la chiamata agentica versions.unpublish sulla versione pubblicata e versions.delete su ogni versione. Quando non rimangono versioni, l'integrazione non viene più visualizzata nell'elenco delle integrazioni. L'eliminazione dell'integrazione stessa richiede un ruolo come Application Integration Admin; il ruolo Editor non può farlo.

Passaggi successivi