建構與 AI 代理的整合

本頁面說明如何透過提示 AI 程式設計代理,建構整合。您只要說明整合項目應執行的操作,代理就會編寫整合項目、透過 Application Integration REST API 上傳及發布、執行整合項目,並協助您排解問題。舉例來說,您建構了簡單的保險理賠裁決整合項目。

代理會從 google/skills 存放區中的三個公開代理技能,取得 Application Integration 知識:

如需各項技能的參考檔案,請參閱「Application Integration 代理技能」。

事前準備

  1. 請使用可安全實驗的 Google Cloud 專案,而非正式環境專案。必須為專案啟用計費功能。
  2. 在支援的地區,於專案中設定 Application Integration。設定 Application Integration 時,需要使用該頁面列出的專屬角色。
  3. 安裝 gcloud CLI,並使用 gcloud auth login 登入。代理會以您的身分呼叫 REST API,並使用您的 gcloud 憑證,或使用用戶端程式庫、應用程式預設憑證。如果代理程式使用用戶端程式庫,可能會要求您執行 gcloud auth application-default login。
  4. 使用支援代理技能的 AI 程式設計代理。

必要的角色

設定 Application Integration 後,您需要下列角色才能建構及執行整合。

如要取得上傳、發布及執行整合項目,以及查看執行作業所需的權限,請要求管理員授予您下列 IAM 角色:

如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色,取得必要權限。

如要瞭解哪些使用者需要服務帳戶使用者角色,以及如何授予該角色,請參閱「為執行身分服務帳戶授予服務帳戶使用者角色」。

安裝代理技能

在終端機執行下列指令,安裝這三項技能:

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

系統提示時,請選擇要設定的代理程式和安裝範圍。如果清單中未列出您的代理程式,預設的通用選項會安裝至 .agents/skills。安裝程式可能也會提供其他技能,例如 find-skills,但這個頁面不需要這些技能。部分代理只會在您信任專案資料夾後,才從中載入技能。如果無法使用 npx,請安裝 Node.js,其中包含。如要日後更新技能,請執行 npx skills update。

說明整合項目

在空白的目前使用的目錄中啟動代理,並說明整合。請具體說明觸發條件、輸入和輸出內容、規則,以及部署位置。例如:

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.

將 PROJECT_ID 替換為專案 ID,並將 LOCATION 替換為設定 Application Integration 的區域。

查看計畫並核准指令

代理程式會寫入整合版本檔案,例如 claims-adjudication.json。其中包含觸發條件 (triggerConfigs)、工作 (taskConfigs) 和變數 (integrationParameters)。請先詳閱這份檔案再繼續操作,並要求代理說明任何不符合預期的內容。例如,檢查代理是否已啟用 Cloud Logging (cloudLoggingDetails.enableCloudLogging),這可能會增加費用。如要關閉,請將 enableCloudLogging 設為 false,並移除 cloudLoggingSeverity。

這些技能會指示代理自由執行唯讀檢查,例如列出整合項目或執行作業,但必須先向您顯示確切的指令或要求,並等待您核准,才能進行任何變更。包括啟用 API、變更 IAM 政策,以及上傳、發布或執行整合。如果代理要求核准,但未顯示確切的指令或要求,請要求代理顯示。代理程式本身的權限設定也可能會要求您核准每項指令,包括唯讀指令。核准前,請先檢查各指令中的專案、區域和整合名稱。

上傳、發布及執行整合作業

核准後,代理會發出下列 Application Integration API 呼叫:

  1. versions.upload 將 JSON 檔案上傳為整合的新版本。
  2. versions.publish 發布該版本。已發布的版本為 ACTIVE,先前發布的版本則會取消發布。
  3. integrations.execute 透過 API 觸發條件同步執行已發布的整合項目。

您也可以自行執行已發布的整合項目:

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"

回應包含 executionId 和 outputParameters 中的整合作業輸出變數。

查看執行作業並排解問題

integrations.execute 傳回成功回應,不一定代表每項工作都符合預期。工作失敗後,可透過重試策略繼續執行:如果設為「Ignore」,整合會將失敗的工作視為成功;如果設為「None」,整合仍可透過替代路徑成功結束。此外,如果要求將 doNotPropagateError 設為 true,系統會在回應中傳回錯誤,而不是傳回錯誤狀態。要求代理檢查執行作業,例如:

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

代理會使用 executions.list 方法讀取執行記錄,並依執行 ID 篩選:

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"

記錄會顯示執行狀態 (例如 SUCCEEDED、FAILED 或 SUSPENDED) 和每項工作的狀態。您也可以在 Google Cloud 控制台中開啟執行記錄。根據預設,系統會停用整合的 Cloud Logging。如要使用這項功能,請參閱「在 Cloud Logging 中查看整合記錄」。

套用修正項目代表上傳及發布新版本,因此技能會指示代理先再次徵求您的核准。發布後,舊版本最多可繼續執行 10 分鐘,因此請稍候再測試修正。發布也會取消先前版本中暫停的執行作業,例如等待核准的執行作業。

最佳做法

  • 從室外開始。在非正式環境專案中建構及測試,然後推送經過審查的 JSON 檔案。請參閱「上傳及下載整合項目」。
  • 使用專用的「執行身分」服務帳戶。為每項整合使用專屬且範圍最小的服務帳戶。請參閱「設定執行身分服務帳戶」。
  • 請勿將 Secret 儲存在設定變數中。設定變數會以純文字格式儲存及匯出。請改用驗證設定檔或 Secret Manager 存取工作。
  • 查看生成的 JSON。請將其保留在原始碼控制中,並在上傳前檢查變更。檔案不含驗證設定檔,因此請在各項專案中設定。

清除所用資源

如要移除範例整合,請向代理提出以下要求:

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

核准後,代理會對已發布版本呼叫 versions.unpublish,並對每個版本呼叫 versions.delete。如果沒有任何版本,整合項目就不會再顯示在整合項目清單中。如要刪除整合,則需要 Application Integration 管理員等角色,編輯者角色無法執行這項操作。

後續步驟