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 계정이 없다면 Google 계정을 만들어야 합니다.
    • 직장 또는 학교 계정 대신 개인 계정을 사용합니다. 직장 및 학교 계정에는 이 실습에 필요한 API를 사용 설정하지 못하도록 하는 제한사항이 있을 수 있습니다.
  2. Google Cloud 콘솔에 로그인합니다.
  3. Cloud 콘솔에서 결제를 사용 설정합니다.
    • 이 실습을 완료하는 데 드는 클라우드 리소스 비용은 $1(USD) 미만입니다.
    • 이 실습이 끝날 때 안내되는 단계에 따라 리소스를 삭제하면 추가 요금이 청구되지 않습니다.
    • 신규 사용자는 미화 $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 리전을 선택하고 빠른 설정을 클릭합니다. 설정이 완료되면 콘솔에 통합 목록이 표시됩니다. 프로젝트를 재사용하는 경우 빠른 설정을 클릭하기 전에 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에서 이 폴더를 신뢰하는지 묻는 메시지가 표시되면 폴더 신뢰를 선택합니다. Gemini CLI는 폴더를 신뢰한 후에만 프로젝트 폴더에서 기술을 로드한 다음 다시 시작합니다. 다시 시작되지 않으면 새 터미널을 열고 ~/appint-agent-lab로 이동한 후 gemini를 다시 실행합니다. 일부 기본 설정을 수락하려면 Enter 키를 눌러야 할 수 있습니다.
  2. Gemini CLI에서 사용할 수 있는 기술을 나열합니다.
    /skills
    
    목록에 세 가지 application-integration-* 기술이 표시됩니다.

7. 통합 빌드, 게시, 실행

  1. 이 프롬프트를 Gemini CLI에 붙여넣습니다. thought 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. 1,000개가 넘는 소유권 주장이 있는 통합을 실행합니다.
    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.

에이전트는 실행 ID로 필터링된 executions.list를 사용하여 실행 레코드를 읽고 실행 및 각 태스크의 상태를 요약합니다.

이 실습에서 문제가 발생하면 다음과 같은 일반적인 원인을 확인하세요.

  • /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. 축하합니다

Application Integration 에이전트 스킬을 사용하여 AI 에이전트에 프롬프트를 입력하여 통합을 빌드, 게시, 실행, 확인했습니다.

다음 단계