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로 로그인합니다. 에이전트는 gcloud 사용자 인증 정보 또는 클라이언트 라이브러리를 사용하는 경우 애플리케이션 기본 사용자 인증 정보를 사용하여 사용자로 REST API를 호출합니다. 에이전트가 클라이언트 라이브러리를 사용하는 경우 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의 성공적인 응답이 항상 모든 태스크가 예상대로 수행되었음을 의미하지는 않습니다. 태스크의 재시도 전략을 사용하면 태스크가 실패한 후에도 실행을 계속할 수 있습니다. 무시를 사용하면 통합에서 실패한 태스크를 성공한 것으로 처리하고 없음을 사용하면 통합이 대체 경로를 통해 성공한 것으로 종료될 수 있습니다. 또한 요청에서 doNotPropagateError를 true로 설정하면 오류가 오류 상태가 아닌 응답으로 반환됩니다. 에이전트에게 실행을 확인하도록 요청합니다. 예를 들면 다음과 같습니다.

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

에이전트는 실행 ID로 필터링된 executions.list 메서드를 사용하여 실행 레코드를 읽습니다.

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 Manager 액세스 태스크를 사용하세요.
  • 생성된 JSON을 검토합니다. 소스 제어에 보관하고 업로드하기 전에 변경사항을 검토합니다. 인증 프로필은 파일에 포함되지 않으므로 각 프로젝트에서 구성합니다.

삭제

예시 통합을 삭제하려면 에이전트에게 다음을 요청하세요.

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

승인하면 에이전트가 게시된 버전에서 versions.unpublish를 호출하고 각 버전에서 versions.delete를 호출합니다. 남은 버전이 없으면 통합이 더 이상 통합 목록에 표시되지 않습니다. 통합 자체를 삭제하려면 Application Integration 관리자와 같은 역할이 필요합니다. 편집자 역할은 삭제할 수 없습니다.

다음 단계