Cloud Run에서 A2A 에이전트 호스팅 개요

이 가이드에서는 Cloud Run에 배포하기 위해 Agent2Agent(A2A) 에이전트를 준비하고 구성하는 방법을 간략히 설명합니다. 여기에는 클라우드 환경 설정, 필수 Identity and Access Management (IAM) 역할 구성, 배포를 위한 에이전트 준비와 같은 필수 단계가 포함됩니다.

시작하기 전에

A2A 에이전트를 개발하고 배포하기 전에 다음 개념과 리소스를 숙지하세요.

A2A 에이전트 배포 로드맵

에이전트를 배포하려면 다음 단계를 완료하세요.

상위 수준 아키텍처

A2A 에이전트의 핵심은 Cloud Run과 같은 서비스 및 오케스트레이션 레이어입니다. 이 레이어는 API를 통해 Gemini 및 Vertex AI와 같은 AI 모델, AlloyDB 및 A2A TaskStore와 같은 메모리 스토리지, 외부 도구와의 상호작용을 관리합니다. 클라이언트는 '에이전트 카드 가져오기' 또는 '메시지 보내기'와 같은 요청을 보내 에이전트와 상호작용하고 작업 업데이트를 수신합니다.

다음 다이어그램은 A2A 에이전트의 아키텍처를 보여주며, A2A 클라이언트 (사용자 또는 에이전트)가 A2A 에이전트와 상호작용하는 모습을 보여줍니다.

서빙 및 오케스트레이션 레이어를 통해 에이전트와 클라이언트가 상호작용하는 A2A 에이전트 아키텍처
A2A 에이전트 아키텍처

A2A 요청 수명 주기에 관한 자세한 내용은 A2A 요청 수명 주기 섹션을 참고하세요.

Cloud Run A2A 에이전트의 IAM 역할 및 권한

Cloud Run 서비스가 다른 Google Cloud서비스와 안전하게 상호작용하려면 IAM 역할을 올바르게 구성해야 합니다. 운영 보안과 효율성을 보장하기 위해 전용 서비스 계정을 만들고 다음 섹션에 나열된 특정 권한을 부여합니다.

Cloud Run 서비스 계정 만들기

gcloud 명령어를 실행하기 전에 인증을 받아야 합니다. 다음 명령어를 실행하여 Google Cloud 계정에 로그인합니다.

gcloud auth login

배포된 A2A 서비스 인스턴스 전용 서비스 계정을 만듭니다. gcloud iam service-accounts create 명령어를 사용합니다.

gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="Service account for A2A Cloud Run service" \
  --display-name="A2A Cloud Run Service Account"

A2A_SERVICE_ACCOUNT_NAME을 서비스 계정의 이름으로 바꿉니다.

A2A 에이전트의 IAM 역할 구성

A2A 에이전트가 상호작용하는 서비스에 따라 서비스 계정에 다음 IAM 역할을 할당합니다. Google Cloud

보안 사용자 인증 정보를 위한 Secret Manager 액세스

  • 역할: Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)

  • 목적: Cloud Run 서비스 계정이 Secret Manager에서 데이터베이스 사용자 인증 정보와 같은 보안 비밀을 안전하게 가져올 수 있도록 허용합니다.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

AI 기능을 위한 Vertex AI 모델 액세스

  • 역할: Vertex AI User (roles/aiplatform.user)

  • 목적: Cloud Run 서비스 계정이 Vertex AI 모델에서 예측 API를 호출하는 데 필요합니다.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

영구 스토리지를 위한 AlloyDB 인스턴스 액세스 (해당하는 경우)

  • 역할: AlloyDB Client (roles/alloydb.client) 및 Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

  • 목적: Cloud Run 서비스 ID가 지속적인 작업 저장을 위해 AlloyDB 클러스터와 상호작용할 수 있도록 지원합니다. 이는 프로덕션 A2A 에이전트에 중요합니다.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.client"

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"

Cloud Run 배포를 위해 A2A 에이전트 준비

이 섹션에서는 Cloud Run에 배포할 A2A 에이전트를 준비하는 데 필요한 구성을 설명하여 클라우드에서 안전하고 효율적이며 확장 가능한 작업을 보장합니다.

Cloud Run 서비스의 보안 비밀 구성

보안 메커니즘을 사용하여 API 키, 데이터베이스 비밀번호와 같은 모든 민감한 사용자 인증 정보를 A2A 서버에 제공합니다. Cloud Run은 보안 비밀을 환경 변수 또는 동적으로 마운트된 볼륨으로 제공하는 것을 지원합니다. 자세한 내용은 Cloud Run에서 보안 비밀 구성을 참고하세요.

예를 들어 gcloud CLI를 사용하여 Google Secret Manager 내에서 데이터베이스 사용자 및 비밀번호 보안 비밀을 만들고 관리합니다. 자세한 내용은 보안 비밀 만들기를 참고하세요.

gcloud secrets create alloy_db_user --replication-policy="automatic"
# Create a file user.txt with contents of secret value
gcloud secrets versions add alloy_db_user --data-file="user.txt"

gcloud secrets create alloy_db_pass --replication-policy="automatic"
# Create a file pass.txt with contents of secret value
gcloud secrets versions add alloy_db_pass --data-file="pass.txt"

컨테이너화를 위한 Dockerfile 만들기

Cloud Run은 이미 호스팅된 컨테이너 이미지에서 또는 소스 코드에서 직접 서비스를 배포할 수 있습니다. 소스 코드에서 배포할 때 프로젝트의 루트 디렉터리에 Dockerfile이 있으면 Cloud Run이 자동으로 컨테이너 이미지를 빌드합니다.

다음은 A2A 에이전트 배포의 샘플 Dockerfile입니다.

FROM python:3.13-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
EXPOSE 8080
WORKDIR /app
COPY . ./
RUN uv sync
ENTRYPOINT ["uv", "run", ".", "--host", "0.0.0.0", "--port", "8080"]

Dockerfile 없이 소스 코드에서 배포

Dockerfile가 없는 소스 코드 저장소의 경우 Cloud Run은 특정 인기 프로그래밍 언어에 대한 기본 지원을 제공하여 컨테이너화 프로세스를 간소화합니다.

다음 단계