Yapay zeka ajanı ve Application Integration temsilci becerileriyle entegrasyon oluşturma

1. Giriş

Bu laboratuvarda, bir yapay zeka ajanına açıklayarak Application Integration entegrasyonu oluşturacaksınız. google/skills deposundan herkese açık üç Application Integration temsilci becerisini yükledikten sonra Gemini CLI'dan küçük bir örnek entegrasyon yazmasını, yüklemesini, yayınlamasını ve çalıştırmasını isteyeceksiniz.

sample-claims-adjudication örneği, bir sigorta talebini alır ve APPROVE, REVIEW veya DENY değerini döndürür.

Yapacaklarınız

  • Google Cloud projesinde Application Integration'ı ayarlama
  • Application Integration temsilci becerilerini yükleyin.
  • Gemini CLI'dan bir entegrasyon oluşturmasını, yüklemesini, yayınlamasını ve çalıştırmasını isteyin.
  • Yürütme işlemini kendiniz kontrol edin ve temsilciden sorunu gidermesini isteyin.
  • Örnek entegrasyonu temizleyin.

Neler öğreneceksiniz?

  • application-integration-basics, -authoring ve -troubleshooting becerilerinin bir temsilciye kazandırdıkları.
  • Entegrasyon sürümü JSON'unu ve temsilcinin çalıştırdığı komutları onaylamadan önce inceleme.
  • Yürütme kaydını okuma

2. Proje ayarlama

  1. Google Hesabınız yoksa bir Google Hesabı oluşturmanız gerekir.
    • İş veya okul hesabı yerine kişisel hesap kullanıyorsanız İş ve okul hesaplarında, bu laboratuvar için gereken API'leri etkinleştirmenizi engelleyen kısıtlamalar olabilir.
  2. Google Cloud Console'da oturum açın.
  3. Cloud Console'da faturalandırmayı etkinleştirin.
    • Bu laboratuvarı tamamlamak için 1 ABD dolarından daha az değerde bulut kaynağı kullanmanız gerekir.
    • Daha fazla ücret ödememek için bu laboratuvarın sonundaki adımları uygulayarak kaynakları silebilirsiniz.
    • Yeni kullanıcılar 300 ABD doları değerindeki ücretsiz deneme sürümünden yararlanabilir.
  4. Yeni bir proje oluşturun veya mevcut bir projeyi yeniden kullanmayı seçin.
    • Proje kotasıyla ilgili bir hata görürseniz mevcut bir projeyi yeniden kullanın veya yeni bir proje oluşturmak için mevcut bir projeyi silin.

Yeni bir proje veya güvenli bir şekilde deneme yapabileceğiniz mevcut bir projeyi kullanın. Üretim projesi kullanmayın. Temsilci, kimlik bilgilerinizle entegrasyonları yükler, yayınlar ve çalıştırır.

3. Cloud Shell Düzenleyici'yi açma

  1. Doğrudan Cloud Shell Düzenleyici'ye gitmek için bu bağlantıyı tıklayın.
  2. Bugün herhangi bir noktada yetkilendirme yapmanız istenirse devam etmek için Authorize'ı (Yetkilendir) tıklayın. Cloud Shell'i yetkilendirmek için tıklayın
  3. Terminal, ekranın alt kısmında görünmüyorsa açın:
    • Görüntüle'yi tıklayın.
    • Terminal'i tıklayın.Cloud Shell Düzenleyici'de yeni terminal açma
  4. Terminalde şu komutla projenizi ayarlayın:
    • Biçim:
      gcloud config set project [PROJECT_ID]
      
    • Örnek:
      gcloud config set project lab-project-id-example
      
    • Proje kimliğinizi hatırlamıyorsanız:
      • Tüm proje kimliklerinizi şu komutla listeleyebilirsiniz:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
        
      Cloud Shell Düzenleyici terminalinde proje kimliğini ayarlama
  5. Şu mesajı görürsünüz:
    Updated property [core/project].
    
    WARNING ifadesini görürseniz ve Do you want to continue (Y/n)? sorusu sorulursa proje kimliğini yanlış girmiş olabilirsiniz. n tuşuna, ardından Enter tuşuna basın ve gcloud config set project komutunu tekrar çalıştırmayı deneyin.

4. Application Integration'ı ayarlama

Application Integration bölgesel bir hizmet olduğundan tek bir bölgede ayarlanır. Bu laboratuvarda us-central1 kullanılır.

  1. Proje kimliğinizi not edin. Daha sonra bir isteme yapıştıracaksınız:
    gcloud config get-value project
    
  2. Application Integration API'yi etkinleştirin:
    gcloud services enable integrations.googleapis.com
    
  3. Google Cloud Console'da Application Integration sayfasına gidip projenizi seçin.
  4. Genel bakış sayfasında us-central1 bölgesini seçin ve Hızlı kurulum'u tıklayın. Kurulum tamamlandığında konsolda Entegrasyonlar listesi gösterilir. Bir projeyi yeniden kullanıyorsanız Hızlı kurulum'u tıklamadan önce Application Integration'ı ayarlama bölümünde listelenen rollere sahip olduğunuzdan emin olun.

Daha fazla bilgi edinmek için Application Integration'ı ayarlama başlıklı makaleyi inceleyin.

5. Temsilci becerilerini yükleme

Beceriler, temsilciye Application Integration bilgisini verir:

  • application-integration-basics: kavramlar, API'leri etkinleştirme, bölge temel hazırlığı, IAM rolleri ve sınırlar.
  • application-integration-authoring: Entegrasyon sürümlerini JSON olarak yazma, yükleme, yayınlama ve çalıştırma.
  • application-integration-troubleshooting: başarısız, takılı kalmış veya sessiz çalıştırmaları teşhis etme.
  1. Bu laboratuvar için bir dizin oluşturun ve bu dizine gidin:
    mkdir ~/appint-agent-lab && cd ~/appint-agent-lab
    
  2. Üç beceriyi yükleyin:
    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
    
    Yükleyici, her beceri için birkaç soru sorar. Gemini CLI, varsayılan Universal (.agents/skills) seçeneğine dahildir. Bu nedenle, Enter tuşuna basarak bu seçeneği koruyun, yükleme kapsamı olarak Project'i seçin ve yüklemeyi onaylayın.

Beceriler artık ~/appint-agent-lab/.agents/skills dilinde.

6. Gemini KSA'yı başlatma

  1. Laboratuvar dizininden Gemini CLI'ı başlatın:
    gemini
    
    Gemini CLI, bu klasöre güvenip güvenmediğinizi sorduğunda Trust folder'ı (Klasöre güven) seçin. Gemini CLI, becerileri yalnızca siz klasöre güvendikten sonra bir proje klasöründen yükler ve ardından yeniden başlatılır. Yeniden başlatılmazsa yeni bir terminal açın, ~/appint-agent-lab dizinine gidin ve gemini komutunu tekrar çalıştırın. Bazı varsayılan ayarları kabul etmek için Enter tuşuna basmanız gerekebilir.
  2. Gemini KSA'nın kullanabileceği becerileri listeleme:
    /skills
    
    Listede üç application-integration-* becerisi görmeniz gerekir.

7. Entegrasyonu derleme, yayınlama ve çalıştırma

  1. Bu istemi Gemini KSA'ya yapıştırın. PROJECT_ID ifadesini, Application Integration'ı ayarlama bölümünde not ettiğiniz proje kimliğiyle değiştirin.
    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. Temsilci bir beceriyi ilk kez kullandığında Gemini CLI, beceriyi etkinleştirmenizi ister. İzin verin.
  3. Aracı, sample-claims-adjudication.json gibi bir entegrasyon sürümü dosyası yazar. Tetikleyici (triggerConfigs), görevler (taskConfigs) ve değişkenler (integrationParameters) içerir. Planı okuyun ve beklemediğiniz bir şey varsa temsilciden açıklamasını isteyin. Örneğin, temsilcinin Cloud Logging'i (cloudLoggingDetails.enableCloudLogging) etkinleştirip etkinleştirmediğini kontrol edin. Bu işlem maliyeti artırabilir. Devre dışı bırakmak için enableCloudLogging değerini false olarak ayarlayın ve cloudLoggingSeverity değerini kaldırın.
  4. Komutları onaylayın. Gemini CLI, salt okunur komutlar da dahil olmak üzere her komutu çalıştırmadan önce onayınızı ister. Beceriler, temsilciye entegrasyonu yükleme, yayınlama veya çalıştırma gibi herhangi bir değişiklik yapmadan önce size tam komutu veya isteği göstermesini de söyler. Temsilci, komutu göstermeden onay isterse komutu göstermesini isteyin. Onaylamadan önce projeyi, bölgeyi ve entegrasyon adını kontrol edin ve size ait olmayan entegrasyonları okuyan veya değiştiren komutları reddedin.

Onayınızın ardından temsilci, JSON dosyasını yeni bir sürüm (versions.upload) olarak yükler, yayınlar (versions.publish) ve API tetikleyicisi (integrations.execute) aracılığıyla çalıştırır. Ardından kararı, nedeni ve yürütme kimliğini gösterir.

8. Yürütmeyi doğrulama

Yayınlanan entegrasyonu kendiniz çalıştırın ve yürütme kaydını okuyun.

  1. Yeni bir Cloud Shell terminal sekmesi açın, laboratuvar dizinine gidin ve proje kimliğiniz ile bölgenizi değişkenlere kaydedin:
    cd ~/appint-agent-lab
    export PROJECT_ID=$(gcloud config get-value project)
    export LOCATION=us-central1
    
  2. Entegrasyonu 1.000'den fazla hak talebiyle çalıştırın:
    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"
    
    Yanıtta bir executionId ve decision değeri REVIEW olarak ayarlanmış outputParameters yer alır.
  3. Yürütme kaydını okuyun. EXECUTION_ID değerini yanıttaki executionId ile değiştirin:
    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"
    
    Yanıtta executionDetails.state, SUCCEEDED değerini alır ve executionDetails.executionSnapshots her görevin durumunu gösterir.

Çalıştırma işlemini Google Cloud konsolundaki yürütme günlüklerinde de görebilirsiniz.

9. Sorun giderme

Başarılı bir yanıt, her görevin beklediğiniz gibi çalıştığı anlamına gelmez. Temsilciden yürütmeyi kontrol etmesini isteyin. Gemini CLI'da EXECUTION_ID ifadesini değiştirerek şu istemi girin:

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

Temsilci, yürütme kimliğine göre filtrelenmiş executions.list ile yürütme kaydını okur ve çalıştırmanın ve her görevin durumunu özetler.

Bu laboratuvarda bir sorunla karşılaşırsanız aşağıdaki yaygın nedenleri kontrol edin:

  • /skills, Application Integration becerilerini listelemez. Gemini CLI'yı ~/appint-agent-lab konumundan başlatın ve klasöre güvenin.
  • Arama, PERMISSION_DENIED ile başarısız oluyor. Doğru projeyi kullandığınızdan ve bu projede Application Integration Düzenleyici rolüne (roles/integrations.integrationEditor) sahip olduğunuzdan emin olun.
  • Entegrasyon çalıştırılırken No integrations found for the requested trigger_id hatası alınıyor. İstekteki proje ve bölgenin, entegrasyonun yayınlandığı yerle eşleştiğinden, triggerId değerinin api_trigger/adjudicate_claim olduğundan ve entegrasyonun bir sürümünün yayınlandığından emin olun. Bir sürüm yükleyip yayınlamadıysanız da aynı hatayı alırsınız.

10. Temizleme

  1. Gemini CLI'da temsilciden örnek entegrasyonu kaldırmasını isteyin:
    Unpublish sample-claims-adjudication, then delete every version of it.
    
    Onayınızın ardından temsilci, yayınlanan sürümü (versions.unpublish) yayından kaldırır ve her sürümü (versions.delete) siler. Hiçbir sürüm kalmadığında entegrasyon, entegrasyonlar listenizde görünmez.Yalnızca bu laboratuvar için bir proje oluşturduysanız entegrasyonu kaldırmak yerine projeyi silebilirsiniz. Bu komutu, Yürütmeyi doğrulama bölümünde açtığınız terminal sekmesinde çalıştırın:
    gcloud projects delete $(gcloud config get-value project)
    
  2. Gemini CLI'dan çıkmak için /quit yazıp Enter tuşuna basın.
  3. Laboratuvar dizinini silin:
    cd ~ && rm -rf ~/appint-agent-lab
    

11. Tebrikler

Application Integration temsilci becerileriyle bir yapay zeka ajanını yönlendirerek entegrasyon oluşturma, yayınlama, çalıştırma ve kontrol etme işlemlerini tamamladınız.

Sırada ne var?