Membangun integrasi dengan agen AI

Halaman ini menunjukkan cara membangun integrasi dengan memberikan perintah kepada agen coding AI. Anda menjelaskan apa yang harus dilakukan integrasi, dan agen akan menulis integrasi, mengupload dan memublikasikannya dengan Application Integration REST API, menjalankannya, dan membantu Anda memecahkan masalahnya. Sebagai contoh, Anda membangun integrasi penilaian klaim asuransi sederhana.

Agen mendapatkan pengetahuan Application Integration dari tiga kemampuan agen publik di repositori google/skills:

Untuk file referensi setiap skill, lihat Skill agen Application Integration.

Sebelum memulai

  1. Gunakan project Google Cloud tempat Anda dapat bereksperimen dengan aman, bukan project produksi. Penagihan harus diaktifkan untuk project.
  2. Siapkan Application Integration dalam project, di wilayah yang didukung. Penyiapan Application Integration memerlukan perannya sendiri, yang tercantum di halaman tersebut.
  3. Instal gcloud CLI dan login dengan gcloud auth login. Agen memanggil REST API sebagai Anda, dengan kredensial gcloud Anda atau, jika menggunakan library klien, Kredensial Default Aplikasi. Jika agen menggunakan library klien, agen mungkin akan meminta Anda menjalankan gcloud auth application-default login.
  4. Gunakan agen coding AI yang mendukung keahlian agen.

Peran yang diperlukan

Setelah Application Integration disiapkan, Anda memerlukan peran berikut untuk membangun dan menjalankan integrasi.

Untuk mendapatkan izin yang Anda perlukan untuk mengupload, memublikasikan, dan menjalankan integrasi serta melihat eksekusinya, minta administrator untuk memberi Anda peran IAM berikut:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Untuk mengetahui siapa yang memerlukan Service Account User dan cara memberikannya, lihat Memberikan Service Account User untuk akun layanan run-as.

Menginstal keahlian agen

Di terminal Anda, jalankan perintah berikut untuk menginstal ketiga 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

Jika diminta, pilih agen yang akan dikonfigurasi dan cakupan penginstalan. Jika agen Anda tidak tercantum, opsi Universal default akan diinstal ke .agents/skills. Penginstal mungkin juga menawarkan keterampilan lain, seperti find-skills; Anda tidak memerlukannya untuk halaman ini. Beberapa agen memuat keterampilan dari folder project hanya setelah Anda memercayai folder tersebut. Jika npx tidak tersedia, instal Node.js, yang menyertakannya. Untuk memperbarui keterampilan nanti, jalankan npx skills update.

Deskripsikan integrasi Anda

Mulai agen Anda di direktori kerja kosong dan deskripsikan integrasinya. Berikan detail spesifik tentang pemicu, input dan output, aturan, serta tempat untuk men-deploy-nya. Contoh:

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.

Ganti PROJECT_ID dengan project ID Anda dan LOCATION dengan region tempat Anda menyiapkan Application Integration.

Meninjau rencana dan menyetujui perintah

Agen menulis file versi integrasi, misalnya claims-adjudication.json. File ini berisi pemicu (triggerConfigs), tugas (taskConfigs), dan variabel (integrationParameters). Baca file ini sebelum melanjutkan, 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.

Keterampilan ini memberi tahu agen untuk menjalankan pemeriksaan hanya baca secara bebas, seperti mencantumkan integrasi atau eksekusi, tetapi menampilkan perintah atau permintaan yang tepat dan menunggu persetujuan Anda sebelum mengubah apa pun. Hal ini termasuk mengaktifkan API, mengubah kebijakan IAM, dan mengupload, memublikasikan, atau menjalankan integrasi. Jika agen meminta persetujuan tanpa menampilkan perintah atau permintaan yang tepat, minta agen untuk menampilkannya. Setelan izin agen Anda sendiri mungkin juga meminta Anda untuk menyetujui setiap perintah, termasuk perintah hanya baca. Periksa project, region, dan nama integrasi di setiap perintah sebelum Anda menyetujuinya.

Mengupload, memublikasikan, dan menjalankan integrasi

Setelah Anda menyetujui, agen akan melakukan panggilan API Application Integration berikut:

  1. versions.upload mengupload file JSON sebagai versi baru integrasi.
  2. versions.publish memublikasikan versi tersebut. Versi yang dipublikasikan adalah ACTIVE, dan versi yang dipublikasikan sebelumnya tidak dipublikasikan.
  3. integrations.execute menjalankan integrasi yang dipublikasikan secara sinkron melalui pemicu API-nya.

Anda juga dapat menjalankan sendiri integrasi yang dipublikasikan:

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"

Respons berisi executionId dan variabel output integrasi di outputParameters.

Memeriksa eksekusi dan memecahkan masalah

Respons yang berhasil dari integrations.execute tidak selalu berarti bahwa setiap tugas melakukan apa yang Anda harapkan. Strategi percobaan ulang tugas dapat memungkinkan operasi dilanjutkan setelah tugas gagal: dengan Abaikan, integrasi memperlakukan tugas yang gagal sebagai berhasil, dan dengan Tidak ada, integrasi masih dapat berakhir sebagai berhasil melalui jalur alternatif. Selain itu, jika permintaan menetapkan doNotPropagateError ke true, error akan ditampilkan dalam respons, bukan sebagai status error. Minta agen untuk memeriksa eksekusi, misalnya:

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

Agen membaca data eksekusi dengan metode executions.list, yang difilter berdasarkan ID eksekusi:

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"

Data tersebut menampilkan status eksekusi, seperti SUCCEEDED, FAILED, atau SUSPENDED, dan status setiap tugas. Anda juga dapat membuka log eksekusi di konsol Google Cloud . Cloud Logging dinonaktifkan untuk integrasi secara default; untuk menggunakannya, lihat Melihat log integrasi di Cloud Logging.

Menerapkan perbaikan berarti mengupload dan memublikasikan versi baru, sehingga keterampilan akan memberi tahu agen untuk meminta persetujuan Anda lagi terlebih dahulu. Setelah Anda memublikasikan, versi sebelumnya dapat terus berjalan hingga 10 menit, jadi tunggu sebelum Anda menguji perbaikan. Publikasi juga membatalkan operasi yang ditangguhkan dari versi sebelumnya, seperti operasi yang menunggu persetujuan.

Praktik terbaik

  • Mulai di luar produksi. Bangun dan uji dalam project non-produksi, lalu promosikan file JSON yang telah ditinjau. Lihat Mengupload dan mendownload integrasi.
  • Gunakan akun layanan run-as khusus. Gunakan akun layanan khusus dengan cakupan minimal untuk setiap integrasi. Lihat Menetapkan akun layanan run-as.
  • Jangan simpan secret dalam variabel konfigurasi. Variabel konfigurasi disimpan dan diekspor dalam teks biasa. Gunakan profil autentikasi atau tugas akses Secret Manager.
  • Tinjau JSON yang dihasilkan. Simpan di kontrol sumber dan tinjau perubahan sebelum Anda menguploadnya. Profil autentikasi tidak disertakan dalam file, jadi konfigurasikan profil tersebut di setiap project.

Pembersihan

Untuk menghapus contoh integrasi, tanyakan kepada agen:

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

Setelah Anda menyetujui, agen akan memanggil versions.unpublish pada versi yang dipublikasikan dan versions.delete pada setiap versi. Jika tidak ada versi yang tersisa, integrasi tidak akan muncul lagi di daftar integrasi Anda. Menghapus integrasi itu sendiri memerlukan peran seperti Admin Application Integration; peran Editor tidak dapat melakukannya.

Langkah berikutnya