Membangun integrasi dengan agen AI dan skill agen Application Integration

1. Pengantar

Di lab ini, Anda akan membangun integrasi Application Integration dengan mendeskripsikannya kepada agen AI. Anda akan menginstal tiga kemampuan agen Application Integration publik dari repositori google/skills, lalu meminta Gemini CLI untuk menulis, mengupload, memublikasikan, dan menjalankan integrasi contoh kecil.

Contoh, sample-claims-adjudication, mengambil klaim asuransi dan menampilkan APPROVE, REVIEW, atau DENY.

Yang akan Anda lakukan

  • Menyiapkan Application Integration di project Google Cloud.
  • Instal keahlian agen Application Integration.
  • Meminta Gemini CLI untuk membangun, mengupload, memublikasikan, dan menjalankan integrasi.
  • Periksa sendiri eksekusinya, dan minta agen untuk memecahkan masalahnya.
  • Membersihkan integrasi sampel.

Yang akan Anda pelajari

  • Kemampuan yang diberikan oleh keahlian application-integration-basics, -authoring, dan -troubleshooting kepada agen.
  • Cara meninjau JSON versi integrasi dan perintah yang dijalankan agen sebelum Anda menyetujuinya.
  • Cara membaca data eksekusi.

2. Penyiapan project

  1. Jika Anda belum memiliki Akun Google, Anda harus membuat Akun Google.
    • Gunakan akun pribadi, bukan akun kantor atau sekolah. Akun kantor dan sekolah mungkin memiliki batasan yang mencegah Anda mengaktifkan API yang diperlukan untuk lab ini.
  2. Login ke Konsol Google Cloud.
  3. Aktifkan penagihan di Konsol Cloud.
    • Menyelesaikan lab ini akan memerlukan biaya kurang dari $1 USD untuk resource Cloud.
    • Anda dapat mengikuti langkah-langkah di akhir lab ini untuk menghapus resource agar tidak dikenai biaya lebih lanjut.
    • Pengguna baru memenuhi syarat untuk mendapatkan Uji Coba Gratis senilai $300 USD.
  4. Buat project baru atau pilih untuk menggunakan kembali project yang sudah ada.
    • Jika Anda melihat error tentang kuota project, gunakan kembali project yang ada atau hapus project yang ada untuk membuat project baru.

Gunakan project baru, atau project yang sudah ada tempat Anda dapat bereksperimen dengan aman, bukan project produksi. Agen mengupload, memublikasikan, dan menjalankan integrasi di dalamnya dengan kredensial Anda.

3. Membuka Cloud Shell Editor

  1. Klik link ini untuk langsung membuka Cloud Shell Editor
  2. Jika diminta untuk memberikan otorisasi kapan saja hari ini, klik Authorize untuk melanjutkan. Klik untuk memberikan otorisasi pada Cloud Shell
  3. Jika terminal tidak muncul di bagian bawah layar, buka terminal:
    • Klik View
    • Klik TerminalMembuka terminal baru di Cloud Shell Editor
  4. Di terminal, tetapkan project Anda dengan perintah ini:
    • Format:
      gcloud config set project [PROJECT_ID]
      
    • Contoh:
      gcloud config set project lab-project-id-example
      
    • Jika Anda tidak dapat mengingat project ID Anda:
      • Anda dapat mencantumkan semua project ID dengan:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
        
      Menetapkan project ID di terminal Cloud Shell Editor
  5. Anda akan melihat pesan ini:
    Updated property [core/project].
    
    Jika Anda melihat WARNING dan ditanya Do you want to continue (Y/n)?, kemungkinan Anda salah memasukkan project ID. Tekan n, tekan Enter, dan coba jalankan kembali perintah gcloud config set project.

4. Menyiapkan Application Integration

Application Integration bersifat regional, jadi Anda menyiapkannya di satu region. Lab ini menggunakan us-central1.

  1. Catat project ID Anda; Anda akan menempelkannya ke prompt nanti:
    gcloud config get-value project
    
  2. Aktifkan Application Integration API:
    gcloud services enable integrations.googleapis.com
    
  3. Buka halaman Application Integration di konsol Google Cloud, lalu pilih project Anda.
  4. Di halaman Overview, pilih region us-central1 dan klik Quick setup. Setelah penyiapan selesai, konsol akan menampilkan daftar Integrations. Jika Anda menggunakan kembali project, pastikan Anda memiliki peran yang tercantum dalam Menyiapkan Application Integration sebelum mengklik Penyiapan cepat.

Untuk mempelajari lebih lanjut, lihat Menyiapkan Application Integration.

5. Menginstal keahlian agen

Keterampilan ini memberi agen pengetahuan Application Integration:

  • application-integration-basics: konsep, mengaktifkan API, menyediakan region, peran IAM, dan batas.
  • application-integration-authoring: menulis versi integrasi sebagai JSON, serta mengupload, memublikasikan, dan menjalankannya.
  • application-integration-troubleshooting: mendiagnosis operasi yang gagal, macet, atau tidak merespons.
  1. Buat direktori untuk lab ini dan buka direktori tersebut:
    mkdir ~/appint-agent-lab && cd ~/appint-agent-lab
    
  2. Instal tiga keahlian:
    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
    
    Untuk setiap skill, penginstal akan mengajukan beberapa pertanyaan. Gemini CLI disertakan dalam opsi Universal (.agents/skills) default, jadi tekan Enter untuk menyimpannya, pilih Project sebagai cakupan penginstalan, dan konfirmasi penginstalan.

Keterampilan kini tersedia dalam bahasa ~/appint-agent-lab/.agents/skills.

6. Memulai Gemini CLI

  1. Mulai Gemini CLI dari direktori lab:
    gemini
    
    Saat Gemini CLI menanyakan apakah Anda memercayai folder ini, pilih Trust folder. Gemini CLI akan memuat keterampilan dari folder project hanya setelah Anda memercayai folder tersebut, lalu memulai ulang. Jika tidak dimulai ulang, buka terminal baru, buka ~/appint-agent-lab, dan jalankan gemini lagi. Anda mungkin perlu menekan Enter untuk menerima beberapa setelan default.
  2. Mencantumkan keterampilan yang dapat digunakan Gemini CLI:
    /skills
    
    Anda akan melihat tiga keterampilan application-integration-* dalam daftar.

7. Membangun, memublikasikan, dan menjalankan integrasi

  1. Tempelkan perintah ini ke Gemini CLI. Ganti PROJECT_ID dengan project ID yang Anda catat di Menyiapkan 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. Saat agen pertama kali menggunakan keahlian, Gemini CLI akan meminta Anda untuk mengaktifkannya. Izinkan.
  3. Agen menulis file versi integrasi, seperti sample-claims-adjudication.json. File ini berisi pemicu (triggerConfigs), tugas (taskConfigs), dan variabel (integrationParameters). Baca file ini, dan minta agen untuk menjelaskan hal-hal yang tidak Anda duga. Misalnya, periksa apakah agen mengaktifkan Cloud Logging (cloudLoggingDetails.enableCloudLogging), yang dapat menambah biaya. Untuk menonaktifkannya, tetapkan enableCloudLogging ke false dan hapus cloudLoggingSeverity.
  4. Setujui perintah. Gemini CLI akan meminta izin sebelum menjalankan setiap perintah, termasuk perintah hanya baca. Keterampilan ini juga memberi tahu agen untuk menampilkan perintah atau permintaan yang tepat sebelum mengubah apa pun, seperti mengupload, memublikasikan, atau menjalankan integrasi. Jika agen meminta persetujuan tanpa menampilkan perintah, minta agen untuk menampilkan perintah. Periksa project, region, dan nama integrasi sebelum Anda menyetujui, dan tolak perintah yang membaca atau mengubah integrasi yang bukan milik Anda.

Setelah Anda menyetujui, agen akan mengupload file JSON sebagai versi baru (versions.upload), memublikasikannya (versions.publish), dan menjalankannya melalui pemicu API (integrations.execute). Kemudian, agen akan menampilkan keputusan, alasan, dan ID eksekusi.

8. Memverifikasi eksekusi

Jalankan sendiri integrasi yang dipublikasikan dan baca catatan eksekusinya.

  1. Buka tab terminal Cloud Shell baru, buka direktori lab, lalu simpan project ID dan region Anda dalam variabel:
    cd ~/appint-agent-lab
    export PROJECT_ID=$(gcloud config get-value project)
    export LOCATION=us-central1
    
  2. Jalankan integrasi dengan klaim di atas 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"
    
    Respons berisi executionId, dan outputParameters dengan decision yang ditetapkan ke REVIEW.
  3. Baca data eksekusi. Ganti EXECUTION_ID dengan executionId dari respons:
    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"
    
    Dalam respons, executionDetails.state adalah SUCCEEDED, dan executionDetails.executionSnapshots menunjukkan status setiap tugas.

Anda juga dapat melihat operasi di log eksekusi di Konsol Google Cloud.

9. Memecahkan masalah

Respons yang berhasil tidak selalu berarti bahwa setiap tugas melakukan apa yang Anda harapkan. Minta agen untuk memeriksa eksekusi. Di Gemini CLI, masukkan perintah ini, dengan mengganti EXECUTION_ID:

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

Agen membaca data eksekusi dengan executions.list, yang difilter berdasarkan ID eksekusi, dan meringkas status operasi dan setiap tugas.

Jika terjadi error di lab ini, periksa penyebab umum berikut:

  • /skills tidak mencantumkan keterampilan Application Integration. Mulai Gemini CLI dari ~/appint-agent-lab dan percayai folder tersebut.
  • Panggilan gagal dengan PERMISSION_DENIED. Pastikan Anda menggunakan project yang tepat, dan Anda memiliki peran Application Integration Editor (roles/integrations.integrationEditor) di dalamnya.
  • Menjalankan integrasi gagal dengan No integrations found for the requested trigger_id. Pastikan project dan region dalam permintaan cocok dengan tempat integrasi dipublikasikan, bahwa triggerId adalah api_trigger/adjudicate_claim, dan bahwa versi integrasi dipublikasikan. Anda akan mendapatkan error yang sama jika mengupload versi, tetapi tidak memublikasikannya.

10. Pembersihan

  1. Di Gemini CLI, minta agen untuk menghapus integrasi contoh:
    Unpublish sample-claims-adjudication, then delete every version of it.
    
    Setelah Anda menyetujui, agen akan membatalkan publikasi versi yang dipublikasikan (versions.unpublish) dan menghapus setiap versi (versions.delete). Jika tidak ada versi yang tersisa, integrasi tidak akan muncul lagi dalam daftar integrasi Anda.Jika Anda membuat project hanya untuk lab ini, Anda dapat menghapus project, bukan menghapus integrasi. Jalankan perintah ini di tab terminal yang Anda buka di Memverifikasi eksekusi:
    gcloud projects delete $(gcloud config get-value project)
    
  2. Ketik /quit dan tekan Enter untuk keluar dari Gemini CLI.
  3. Hapus direktori lab:
    cd ~ && rm -rf ~/appint-agent-lab
    

11. Selamat

Anda telah membangun, memublikasikan, menjalankan, dan memeriksa integrasi dengan memberikan perintah kepada agen AI menggunakan keterampilan agen Application Integration.

Langkah berikutnya