建構與 AI 代理的整合
本頁面說明如何透過提示 AI 程式設計代理,建構整合。您只要說明整合項目應執行的操作,代理就會編寫整合項目、透過 Application Integration REST API 上傳及發布、執行整合項目,並協助您排解問題。舉例來說,您建構了簡單的保險理賠裁決整合項目。
代理會從 google/skills 存放區中的三個公開代理技能,取得 Application Integration 知識:
application-integration-basics:概念、啟用 API、佈建區域、IAM 角色和執行身分服務帳戶,以及限制。application-integration-authoring:以 JSON 格式編寫整合版本,並上傳、發布及執行。application-integration-troubleshooting:診斷失敗、停滯或無訊息的執行作業。
如需各項技能的參考檔案,請參閱「Application Integration 代理技能」。
事前準備
- 請使用可安全實驗的 Google Cloud 專案,而非正式環境專案。必須為專案啟用計費功能。
- 在支援的地區,於專案中設定 Application Integration。設定 Application Integration 時,需要使用該頁面列出的專屬角色。
- 安裝 gcloud CLI,並使用
gcloud auth login登入。代理會以您的身分呼叫 REST API,並使用您的 gcloud 憑證,或使用用戶端程式庫、應用程式預設憑證。如果代理程式使用用戶端程式庫,可能會要求您執行gcloud auth application-default login。 - 使用支援代理技能的 AI 程式設計代理。
必要的角色
設定 Application Integration 後,您需要下列角色才能建構及執行整合。
如要取得上傳、發布及執行整合項目,以及查看執行作業所需的權限,請要求管理員授予您下列 IAM 角色:
- 專案的 Application Integration 編輯者 (
roles/integrations.integrationEditor) -
如果整合項目有執行身分服務帳戶:執行身分服務帳戶的服務帳戶使用者 (
roles/iam.serviceAccountUser)
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
如要瞭解哪些使用者需要服務帳戶使用者角色,以及如何授予該角色,請參閱「為執行身分服務帳戶授予服務帳戶使用者角色」。
安裝代理技能
在終端機執行下列指令,安裝這三項技能:
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 呼叫:
versions.upload將 JSON 檔案上傳為整合的新版本。versions.publish發布該版本。已發布的版本為ACTIVE,先前發布的版本則會取消發布。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 管理員等角色,編輯者角色無法執行這項操作。