Cloud Run에 A2A 에이전트 배포

이 문서에서는 A2A 에이전트를 Cloud Run에 배포하는 방법을 설명합니다. 이러한 단계를 통해 클라우드 환경에서 안전하고 효율적이며 확장 가능한 작업을 보장할 수 있습니다.

시작하기 전에

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Install the Google Cloud CLI.

  5. 외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

  6. gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다. 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Install the Google Cloud CLI.

  10. 외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

  11. gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다. 

    gcloud init
  12. A2A 에이전트 소스 코드가 포함된 디렉터리로 이동합니다.

      cd PATH_TO_YOUR_AGENT_DIRECTORY

  13. 필요한 IAM 역할 및 권한은 Cloud Run A2A 에이전트의 IAM 역할 및 권한을 참고하세요.

    14. Cloud Run 서비스 인증 구성

    A2A 에이전트가 완전히 개발되고 배포 환경이 준비되면 인증을 구성하고 gcloud run deploy 명령어를 사용하여 에이전트를 Cloud Run에 배포해야 합니다.

    다음 옵션 중 하나를 사용하여 A2A Cloud Run 서비스의 액세스 및 인증을 구성합니다.

    • 내부 Google Cloud 클라이언트를 위한 IAM 기반 인증: Google Cloud내에서 작동하는 클라이언트(예: Agentspace와 같은 내부 서비스)의 경우 IAM 기반 인증이 권장되는 보안 방식입니다. 이러한 클라이언트는 서비스 계정을 사용하며 Cloud Run 서비스를 호출하려면 Cloud Run 호출자 (roles/run.invoker) 역할이 필요합니다. 자세한 내용은 Cloud Run 서비스 간 인증을 참고하세요.

      Cloud Run 서비스에 IAM 기반 인증을 사용 설정하려면 다음 단계를 따르세요.

      • 배포 중에 --no-allow-unauthenticated 플래그를 사용해야 합니다.

    • 공개 노출을 위한 에이전트 수준 인증: A2A 서버가 공개 액세스를 위해 설계된 경우 에이전트 수준 인증을 처리합니다.

      Cloud Run 서비스에 대한 공개 액세스를 허용하려면 다음 단계를 따르세요.

      • securitySchemes 및 security 매개변수를 사용하여 A2A 에이전트의 카드에 중요한 인증 정보를 제공해야 합니다. 자세한 내용은 A2A 사양: SecurityScheme 객체 세부정보를 참고하세요.
      • 배포 중에 --allow-unauthenticated 플래그를 사용합니다. Cloud Run 서비스에 대한 공개 액세스를 허용하는 방법에 대한 자세한 내용은 Cloud Run 공개 액세스 인증을 참고하세요.

    Cloud Run에 A2A 에이전트 배포

    기존 ADK 샘플을 사용하여 A2A 에이전트를 배포합니다. gcloud run deploy 명령어를 사용할 때는 다음 매개변수를 지정하세요.

    • 액세스 구성:
      • IAM 기반 서비스 인증을 사용하려면 --no-allow-unauthenticated 플래그를 사용하세요.
      • 인터넷에서 서비스를 공개하려면 --allow-unauthenticated 플래그를 사용합니다.
    • 메모리: 컨테이너 인스턴스가 실행되기 위한 최소 메모리 요구사항은 1Gi입니다.
    • 보안 비밀: 보안 비밀을 사용하려면 DB_USER 및 DB_PASS 매개변수를 지정합니다.
    • 서비스 계정: 서비스 계정을 지정하려면 a2a-service-account 매개변수를 사용합니다.
    • 환경 변수: 환경 변수를 지정하려면 다음 변수를 사용하세요.
      • APP_URL
      • DB_INSTANCE
      • DB_NAME
      • GOOGLE_GENAI_USE_VERTEXAI = true

    로컬 테스트의 경우 인메모리 TaskStore 구성을 사용합니다. 서비스를 프로덕션에 배포하려면 프로덕션 A2A 서버에 영구 스토리지를 사용해야 합니다. PostgreSQL용 AlloyDB 배포 섹션의 예를 참고하세요.

    인메모리 TaskStore 구성으로 배포

    메모리 내 TaskStore 구성으로 A2A 에이전트를 배포하려면 다음 gcloud run deploy 명령어를 사용하세요.

    gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --service-account=a2a-service-account \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,\
      GOOGLE_CLOUD_PROJECT="PROJECT_ID",\
      GOOGLE_CLOUD_LOCATION="REGION",\
      APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app"

    A2A 에이전트 소스 코드가 포함된 디렉터리에 있지 않으면 에이전트 코드의 전체 경로로 --source 플래그를 업데이트합니다.

    다음을 바꿉니다.

    • REGION: 서비스를 배포할 Google Cloud 리전입니다. 예를 들면 europe-west1입니다.
    • PROJECT_ID: 프로젝트 ID입니다.
    • PROJECT_NUMBER: 프로젝트 번호

    PostgreSQL용 AlloyDB로 배포

    A2A 작업을 유지하려면 PostgreSQL용 AlloyDB를 사용하세요. 영구 작업 저장소에 PostgreSQL용 AlloyDB를 사용하여 A2A 에이전트를 배포하려면 다음 gcloud run deploy 명령어를 사용하세요.

    gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --update-secrets=DB_USER=alloy_db_user:latest,DB_PASS=alloy_db_pass:latest \
    --service-account=a2a-service-account \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,\
      GOOGLE_CLOUD_PROJECT="PROJECT_ID",\
      GOOGLE_CLOUD_LOCATION="REGION",\
      APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app",\
      USE_ALLOY_DB="True",\
      DB_INSTANCE="projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME/instances/primary-instance",\
      DB_NAME="postgres"

    A2A 에이전트 소스 코드가 포함된 디렉터리에 있지 않으면 에이전트 코드의 전체 경로로 --source 플래그를 업데이트합니다.

    다음을 바꿉니다.

    • REGION: 서비스를 배포할 Google Cloud 리전입니다. 예를 들면 europe-west1입니다.
    • PROJECT_ID: 프로젝트 ID입니다.
    • PROJECT_NUMBER: 프로젝트 번호
    • CLUSTER_NAME: PostgreSQL용 AlloyDB 클러스터의 이름입니다.

    Cloud Run 애플리케이션 URL 이해

    배포가 성공하면 Cloud Run에서 활성 A2A 서비스를 쿼리하는 엔드포인트 역할을 하는 run.app URL을 자동으로 제공합니다. 서비스 이름이 충분히 짧으면 URL이 결정적이고 예측 가능합니다.

    • Cloud Run URL 형식: https://TAG---SERVICE_NAME-PROJECT_NUMBER.REGION.run.app
    • URL 예: https://sample-a2a-agent-1234.europe-west1.run.app

    배포 실패 디버그

    Cloud Run 배포 실패를 디버그하려면 다음을 고려하세요.

    • 상세 로그: 자세한 배포 로그를 보려면 gcloud run deploy 명령어에서 --verbosity=info 플래그를 설정하세요.

    • URL 불일치: 배포 명령에서 반환된 run.app URL이 예상되는 결정적 URL과 다른 경우 Cloud Run 서비스의 APP_URL 환경 변수를 업데이트합니다.

      1. 다음 명령어를 사용하여 APP_URL 환경 변수를 업데이트합니다.

        gcloud run services update SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION" \
    --update-env-vars=APP_URL="CLOUD_RUN_SERVICE_URL"

        다음을 바꿉니다.

        • SERVICE_NAME: Cloud Run 서비스의 이름
        • PROJECT_ID: 프로젝트 ID입니다.
        • REGION: 서비스를 배포할 Google Cloud 리전입니다. 예를 들면 europe-west1입니다.
        • CLOUD_RUN_SERVICE_URL: Cloud Run 서비스의 URL입니다.

      2. 서비스를 설명하여 APP_URL가 올바르게 업데이트되었는지 확인합니다.

        gcloud run services describe SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION"