使用 AI 代理和 Application Integration 代理技能建構整合

1. 簡介

在本實驗室中,您將向 AI 代理描述 Application Integration 整合項目,並建構該項目。您將從 google/skills 存放區安裝三個公開的 Application Integration 代理技能,然後提示 Gemini CLI 編寫、上傳、發布及執行小型範例整合。

範例 sample-claims-adjudication 會接收保險理賠,並傳回 APPROVE、REVIEW 或 DENY。

學習內容

  • 在 Google Cloud 專案中設定 Application Integration。
  • 安裝 Application Integration 代理技能。
  • 提示 Gemini CLI 建構、上傳、發布及執行整合。
  • 請自行檢查執行結果,並要求代理排解問題。
  • 清除整合範例。

課程內容

  • application-integration-basics、-authoring 和 -troubleshooting 技能可為代理提供的功能。
  • 如何在核准前,查看整合版本 JSON 和代理執行的指令。
  • 如何解讀執行記錄。

2. 專案設定

  1. 如果沒有 Google 帳戶,請建立帳戶。
    • 請改用個人帳戶,而非公司或學校帳戶。公司和學校帳戶可能設有限制,導致您無法啟用本實驗室所需的 API。
  2. 登入 Google Cloud 控制台。
  3. 在 Cloud 控制台中啟用計費功能。
    • 完成本實驗室所需的 Cloud 資源費用應低於 $1 美元。
    • 您可以按照本實驗室結尾的步驟刪除資源,以免產生額外費用。
    • 新使用者可享有價值 $300 美元的免費試用期。
  4. 建立新專案或選擇重複使用現有專案。
    • 如果看到專案配額錯誤,請重複使用現有專案,或刪除現有專案來建立新專案。

請使用新專案或可安全實驗的現有專案,而非正式環境專案。代理會使用您的憑證,上傳、發布及執行整合作業。

3. 開啟 Cloud Shell 編輯器

  1. 按一下這個連結,直接前往 Cloud Shell 編輯器
  2. 如果今天在任何時候看到授權提示,請點選「授權」繼續操作。按一下即可授權 Cloud Shell
  3. 如果終端機未顯示在畫面底部,請開啟終端機:
    • 點選「查看」。
    • 按一下「終端機」在 Cloud Shell 編輯器中開啟新的終端機
  4. 在終端機中,使用下列指令設定專案:
    • 格式:
      gcloud config set project [PROJECT_ID]
      
    • 範例:
      gcloud config set project lab-project-id-example
      
    • 如果忘記專案 ID:
      • 您可以使用下列指令列出所有專案 ID:
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
        
      在 Cloud Shell 編輯器終端機中設定專案 ID
  5. 您應會看到下列訊息:
    Updated property [core/project].
    
    如果看到 WARNING,且系統詢問 Do you want to continue (Y/n)?,代表您可能輸入了錯誤的專案 ID。按下 n,再按下 Enter,然後嘗試再次執行 gcloud config set project 指令。

4. 設定 Application Integration

Application Integration 具有區域性,因此您必須在一個區域中設定。本實驗室會使用 us-central1。

  1. 記下專案 ID,稍後要貼到提示中:
    gcloud config get-value project
    
  2. 啟用 Application Integration API:
    gcloud services enable integrations.googleapis.com
    
  3. 前往 Google Cloud 控制台的「Application Integration」頁面,然後選取專案。
  4. 在「總覽」頁面中,選取「us-central1」區域,然後按一下「快速設定」。設定完成後,控制台會顯示「Integrations」(整合) 清單。如果重複使用專案,請先確認您具備「設定 Application Integration」中列出的角色,再點選「快速設定」。

詳情請參閱「設定 Application Integration」。

5. 安裝代理技能

技能可讓代理具備 Application Integration 知識:

  • application-integration-basics:概念、啟用 API、佈建區域、IAM 角色和限制。
  • application-integration-authoring:以 JSON 格式編寫整合版本,並上傳、發布及執行。
  • application-integration-troubleshooting:診斷失敗、停滯或無訊息的執行作業。
  1. 建立本實驗室的目錄,然後前往該目錄:
    mkdir ~/appint-agent-lab && cd ~/appint-agent-lab
    
  2. 安裝三項技能:
    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
    
    安裝程式會針對每項技能提出幾個問題。Gemini CLI 包含在預設的「Universal (.agents/skills)」選項中,因此請按下 Enter 鍵保留該選項,選擇「Project」做為安裝範圍,然後確認安裝。

技能現已移至「~/appint-agent-lab/.agents/skills」。

6. 啟動 Gemini CLI

  1. 從實驗室目錄啟動 Gemini CLI:
    gemini
    
    Gemini CLI 詢問您是否信任這個資料夾時,請選擇「Trust folder」。Gemini CLI 只會在您信任專案資料夾後,才從該資料夾載入技能,然後重新啟動。如果沒有重新啟動,請開啟新的終端機,前往 ~/appint-agent-lab,然後再次執行 gemini。您可能需要按下 Enter 鍵來接受部分預設設定。
  2. 列出 Gemini CLI 可使用的技能:
    /skills
    
    您應該會在清單中看到三個 application-integration-* 技能。

7. 建構、發布及執行整合作業

  1. 將這段提示詞貼到 Gemini CLI。將 PROJECT_ID 替換為您在「設定 Application Integration」中記下的專案 ID。
    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. 代理首次使用技能時,Gemini CLI 會要求您啟用。允許。
  3. 代理會寫入整合版本檔案,例如 sample-claims-adjudication.json。其中包含觸發條件 (triggerConfigs)、工作 (taskConfigs) 和變數 (integrationParameters)。請詳閱內容,並要求代理說明任何不符合預期的部分。舉例來說,請檢查代理是否已啟用 Cloud Logging (cloudLoggingDetails.enableCloudLogging),這可能會增加費用。如要關閉,請將 enableCloudLogging 設為 false,並移除 cloudLoggingSeverity。
  4. 核准指令。Gemini CLI 執行指令前會先詢問,包括唯讀指令。此外,這些技能也會指示代理在變更任何內容 (例如上傳、發布或執行整合) 之前,先向您顯示確切的指令或要求。如果代理要求核准,但未顯示指令,請要求代理顯示指令。核准前,請先檢查專案、區域和整合名稱,並拒絕讀取或變更非您整合項目的指令。

核准後,代理會將 JSON 檔案上傳為新版本 (versions.upload)、發布 (versions.publish),並透過 API 觸發條件 (integrations.execute) 執行。接著,代理會顯示決策、原因和執行 ID。

8. 驗證執行作業

自行執行已發布的整合項目,並查看執行記錄。

  1. 開啟新的 Cloud Shell 終端機分頁,前往實驗室目錄,然後將專案 ID 和區域儲存至變數:
    cd ~/appint-agent-lab
    export PROJECT_ID=$(gcloud config get-value project)
    export LOCATION=us-central1
    
  2. 執行整合,並將索賠金額設為超過 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"
    
    回應包含 executionId 和 outputParameters,其中 decision 設為 REVIEW。
  3. 閱讀執行記錄。將 EXECUTION_ID 替換為回應中的 executionId:
    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"
    
    在回應中,executionDetails.state 為 SUCCEEDED,executionDetails.executionSnapshots 則顯示每項工作的狀態。

您也可以在 Google Cloud 控制台的執行記錄中查看執行作業。

9. 疑難排解

成功的回應不一定代表每項工作都符合預期。請代理檢查執行情況。在 Gemini CLI 輸入下列提示詞,並替換 EXECUTION_ID:

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

代理會使用 executions.list 讀取執行記錄,並依執行 ID 篩選,然後總結執行作業和各項工作的狀態。

如果本實驗室發生問題,請檢查下列常見原因:

  • /skills 不會列出 Application Integration 技能。從 ~/appint-agent-lab 啟動 Gemini CLI,並信任資料夾。
  • 呼叫失敗,並顯示 PERMISSION_DENIED。確認您使用的是正確的專案,且具備 Application Integration 編輯者角色 (roles/integrations.integrationEditor)。
  • 執行整合失敗,並顯示 No integrations found for the requested trigger_id。請確認要求中的專案和區域與整合項目發布位置相符、triggerId 為 api_trigger/adjudicate_claim,且整合項目版本已發布。如果您上傳了版本但未發布,也會收到相同的錯誤訊息。

10. 清除

  1. 在 Gemini CLI 中,要求代理移除範例整合:
    Unpublish sample-claims-adjudication, then delete every version of it.
    
    核准後,代理會取消發布已發布的版本 (versions.unpublish),並刪除每個版本 (versions.delete)。如果沒有任何版本,整合項目就不會再顯示在整合項目清單中。如果您是專為這個實驗室建立專案,可以刪除專案,不必移除整合項目。在「驗證執行作業」開啟的終端機分頁中,執行下列指令:
    gcloud projects delete $(gcloud config get-value project)
    
  2. 輸入 /quit 並按下 Enter 鍵,即可退出 Gemini CLI。
  3. 刪除實驗室目錄:
    cd ~ && rm -rf ~/appint-agent-lab
    

11. 恭喜

您已透過提示 AI 代理,使用 Application Integration 代理技能建構、發布、執行及檢查整合項目。

後續步驟