Crea un'integrazione con un agente AI e le skill dell'agente di Application Integration

1. Introduzione

In questo lab creerai un'integrazione di Application Integration descrivendola a un agente AI. Installa le tre skill dell'agente di Application Integration pubbliche dal repository google/skills, quindi chiedi a Gemini CLI di scrivere, caricare, pubblicare ed eseguire una piccola integrazione di esempio.

L'esempio sample-claims-adjudication accetta una richiesta di risarcimento assicurativo e restituisce APPROVE, REVIEW o DENY.

In questo lab proverai a:

  • Configurare Application Integration in un progetto Google Cloud.
  • Installa le skill dell'agente di Application Integration.
  • Chiedi a Gemini CLI di creare, caricare, pubblicare ed eseguire un'integrazione.
  • Controlla l'esecuzione e chiedi all'agente di risolvere i problemi.
  • Esegui la pulizia dell'integrazione di esempio.

Obiettivi didattici

  • Cosa offrono a un agente le skill application-integration-basics, -authoring e -troubleshooting.
  • Come esaminare il file JSON della versione dell'integrazione e i comandi eseguiti dall'agente prima di approvarli.
  • Come leggere un record di esecuzione.

2. Configurazione del progetto

  1. Se non hai ancora un Account Google, devi crearne uno.
    • Utilizza un account personale anziché un account di lavoro o della scuola. Gli account di lavoro e della scuola potrebbero avere restrizioni che impediscono di abilitare le API necessarie per questo lab.
  2. Accedi alla console Google Cloud.
  3. Abilita la fatturazione nella console Cloud.
    • Il completamento di questo lab dovrebbe costare meno di 1 $in risorse cloud.
    • Puoi seguire i passaggi alla fine di questo lab per eliminare le risorse ed evitare ulteriori addebiti.
    • I nuovi utenti sono idonei alla prova senza costi di 300 $.
  4. Crea un nuovo progetto o scegli di riutilizzare un progetto esistente.
    • Se visualizzi un errore relativo alla quota di progetti, riutilizza un progetto esistente o eliminalo per crearne uno nuovo.

Utilizza un nuovo progetto o un progetto esistente in cui puoi sperimentare in sicurezza, non un progetto di produzione. L'agente carica, pubblica ed esegue le integrazioni al suo interno con le tue credenziali.

3. Apri editor di Cloud Shell

  1. Fai clic su questo link per andare direttamente all'editor di Cloud Shell
  2. Se ti viene richiesto di concedere l'autorizzazione in qualsiasi momento oggi, fai clic su Autorizza per continuare. Fai clic per autorizzare Cloud Shell
  3. Se il terminale non viene visualizzato nella parte inferiore dello schermo, aprilo:
    • Fai clic su Visualizza.
    • Fai clic su TerminaleApri un nuovo terminale nell'editor di Cloud Shell
  4. Nel terminale, imposta il progetto con questo comando:
    • Formato:
      gcloud config set project [PROJECT_ID]
      
    • Esempio:
      gcloud config set project lab-project-id-example
      
    • Se non ricordi l'ID progetto:
      • Puoi elencare tutti gli ID progetto con:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
        
      Imposta l'ID progetto nel terminale dell'editor di Cloud Shell
  5. Dovresti vedere questo messaggio:
    Updated property [core/project].
    
    Se vedi un WARNING e ti viene chiesto Do you want to continue (Y/n)?, è probabile che tu abbia inserito l'ID progetto in modo errato. Premi n, premi Enter e prova a eseguire di nuovo il comando gcloud config set project.

4. Configura Application Integration

Application Integration è un servizio regionale, quindi lo configuri in una regione. Questo lab utilizza us-central1.

  1. Prendi nota dell'ID progetto, che dovrai incollare in un prompt in un secondo momento:
    gcloud config get-value project
    
  2. Abilita l'API Application Integration:
    gcloud services enable integrations.googleapis.com
    
  3. Vai alla pagina Application Integration nella console Google Cloud e seleziona il tuo progetto.
  4. Nella pagina Panoramica, seleziona la regione us-central1 e fai clic su Configurazione rapida. Al termine della configurazione, la console mostra l'elenco Integrazioni. Se riutilizzi un progetto, verifica di disporre dei ruoli elencati in Configura Application Integration prima di fare clic su Configurazione rapida.

Per saperne di più, consulta Configura Application Integration.

5. Installa le skill dell'agente

Le skill forniscono all'agente le conoscenze di Application Integration:

  • application-integration-basics: concetti, abilitazione delle API, provisioning di una regione, ruoli IAM e limiti.
  • application-integration-authoring: scrittura delle versioni di integrazione in formato JSON, caricamento, pubblicazione ed esecuzione.
  • application-integration-troubleshooting: diagnosi delle esecuzioni non riuscite, bloccate o silenziose.
  1. Crea una directory per questo lab e vai alla directory:
    mkdir ~/appint-agent-lab && cd ~/appint-agent-lab
    
  2. Installa 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
    
    Per ogni skill, l'installatore pone alcune domande. Gemini CLI è incluso nell'opzione predefinita Universal (.agents/skills), quindi premi Enter per mantenerlo, scegli Project come ambito di installazione e conferma l'installazione.

Le skill sono ora in ~/appint-agent-lab/.agents/skills.

6. Avvia Gemini CLI

  1. Avvia Gemini CLI dalla directory del lab:
    gemini
    
    Quando Gemini CLI ti chiede se consideri attendibile questa cartella, scegli Considera attendibile la cartella. Gemini CLI carica le skill da una cartella di progetto solo dopo che hai considerato attendibile la cartella, quindi si riavvia. Se non si riavvia, apri un nuovo terminale, vai a ~/appint-agent-lab ed esegui di nuovo gemini. Potresti dover premere Enter per accettare alcune impostazioni predefinite.
  2. Elenca le skill che Gemini CLI può utilizzare:
    /skills
    
    Dovresti vedere le tre skill application-integration-* nell'elenco.

7. Crea, pubblica ed esegui l'integrazione

  1. Incolla questo prompt in Gemini CLI. Sostituisci PROJECT_ID con l'ID progetto che hai annotato in Configura 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 prima volta che l'agente utilizza una skill, Gemini CLI ti chiede di attivarla. Consenti.
  3. L'agente scrive un file della versione di integrazione, ad esempio sample-claims-adjudication.json. Contiene il trigger (triggerConfigs), le attività (taskConfigs) e le variabili (integrationParameters). Leggilo 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 disattivarla, imposta enableCloudLogging su false e rimuovi cloudLoggingSeverity.
  4. Approva i comandi. Gemini CLI chiede conferma prima di eseguire ogni comando, inclusi quelli di sola lettura. Le skill indicano inoltre all'agente di mostrarti il comando o la richiesta esatta prima di apportare modifiche, ad esempio caricare, pubblicare o eseguire l'integrazione. Se l'agente chiede l'approvazione senza mostrare il comando, chiedigli di mostrarlo. Controlla il progetto, la regione e il nome dell'integrazione prima di approvare e rifiuta i comandi che leggono o modificano integrazioni che non sono tue.

Dopo la tua approvazione, l'agente carica il file JSON come nuova versione (versions.upload), lo pubblica (versions.publish) e lo esegue tramite il trigger API (integrations.execute). Poi ti mostra la decisione, il motivo e l'ID esecuzione.

8. Verifica l'esecuzione

Eseguire l'integrazione pubblicata e leggere il relativo record di esecuzione.

  1. Apri una nuova scheda del terminale Cloud Shell, vai alla directory del lab e salva l'ID progetto e la regione nelle variabili:
    cd ~/appint-agent-lab
    export PROJECT_ID=$(gcloud config get-value project)
    export LOCATION=us-central1
    
  2. Esegui l'integrazione con una rivendicazione superiore a 1000:
    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 risposta contiene un executionId e outputParameters con decision impostato su REVIEW.
  3. Leggi il record di esecuzione. Sostituisci EXECUTION_ID con executionId della risposta:
    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"
    
    Nella risposta, executionDetails.state è SUCCEEDED e executionDetails.executionSnapshots mostra lo stato di ogni attività.

Puoi anche visualizzare l'esecuzione nei log di esecuzione nella console Google Cloud.

9. Risoluzione dei problemi

Una risposta positiva non significa sempre che ogni attività ha eseguito ciò che ti aspettavi. Chiedi all'agente di controllare l'esecuzione. In Gemini CLI, inserisci questo prompt, sostituendo 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'agente legge il record di esecuzione con executions.list, filtrato in base all'ID esecuzione, e riassume lo stato dell'esecuzione e di ogni attività.

Se qualcosa va storto in questo lab, controlla queste cause comuni:

  • /skills non elenca le skill di Application Integration. Avvia Gemini CLI da ~/appint-agent-lab e considera attendibile la cartella.
  • Una chiamata non riesce con PERMISSION_DENIED. Verifica di utilizzare il progetto corretto e di disporre del ruolo Application Integration Editor (roles/integrations.integrationEditor).
  • L'esecuzione dell'integrazione non riesce con No integrations found for the requested trigger_id. Verifica che il progetto e la regione nella richiesta corrispondano alla posizione in cui è pubblicata l'integrazione, che triggerId sia api_trigger/adjudicate_claim e che sia pubblicata una versione dell'integrazione. Riceverai lo stesso errore se hai caricato una versione, ma non l'hai pubblicata.

10. Esegui la pulizia

  1. In Gemini CLI, chiedi all'agente di rimuovere l'integrazione di esempio:
    Unpublish sample-claims-adjudication, then delete every version of it.
    
    Dopo l'approvazione, l'agente annulla la pubblicazione della versione pubblicata (versions.unpublish) ed elimina ogni versione (versions.delete). Quando non rimangono versioni, l'integrazione non viene più visualizzata nell'elenco delle integrazioni.Se hai creato un progetto solo per questo lab, puoi eliminare il progetto anziché rimuovere l'integrazione. Esegui questo comando nella scheda del terminale che hai aperto in Verifica l'esecuzione:
    gcloud projects delete $(gcloud config get-value project)
    
  2. Digita /quit e premi Enter per uscire da Gemini CLI.
  3. Elimina la directory del lab:
    cd ~ && rm -rf ~/appint-agent-lab
    

11. Complimenti

Hai creato, pubblicato, eseguito e controllato un'integrazione inviando un prompt a un agente AI con le skill dell'agente di Application Integration.

Passaggi successivi