Cloud Run용 Agent Platform 기능 구성

미리보기 — Cloud Run용 Agent Platform 기능 구성

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제품 또는 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

Gemini Enterprise Agent Platform 의 Agent Identity 및 Agent Registry 와 같은 기능은 AI 에이전트, 모델 컨텍스트 프로토콜 (MCP) 서버, 도구를 빌드, 배포, 관리하기 위한 기본 제공 기능을 제공합니다. Cloud Run 리소스에 이러한 기능을 사용 설정하면 시스템 관리 ID와 자동 등록을 활용하여 에이전트형 워크로드의 검색 및 보안을 간소화할 수 있습니다.

이 가이드에서는 다음 방법을 설명합니다.

• 필수 IAM 역할 설정
• 기능 및 ID 유형 이해
• 서비스 및 작업의 기능 구성
• 할당된 ID 보기
• Agent Registry에 등록된 에이전트 및 도구 보기

Cloud Run은 다음과 같은 Agent Platform 기능을 지원합니다.

• Agent Identity: 워크로드에 고유한 암호화 방식으로 검증 가능한 ID를 할당하여 다른 에이전트, 도구, Google Cloud API에 안전하게 연결할 수 있도록 합니다.
• Agent Registry: 에이전트와 도구를 자동으로 등록하여 조직의 다른 개발자와 에이전트가 검색할 수 있도록 합니다.

시작하기 전에

계정에 로그인합니다. Google Cloud 를 처음 사용하는 경우 Google Cloud 계정을 만들어 실제 시나리오에서 제품이 어떻게 작동하는지 평가하세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Google Cloud CLI를 설치합니다.

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

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

gcloud init

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Google Cloud CLI를 설치합니다.

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

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

gcloud init

1. Cloud Run Admin API, Identity and Access Management API, Agent Registry API, App Hub API API를 사용 설정합니다.

   API 사용 설정에 필요한 역할

   API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한을 이미 보유하고 있을 가능성이 높습니다. 그렇지 않은 경우 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할을 부여하는 방법을 알아보세요.

   API 사용 설정

2. 프로젝트 또는 조직에 Agent Registry 를 설정했는지 확인합니다.
3. gcloud CLI를 설치하고 초기화합니다.
4. 구성요소를 업데이트합니다.

   gcloud components update

5. Cloud Run 가격 책정 페이지에서 CPU, 메모리, 네트워크 이그레스를 검토합니다. 프로비저닝된 디스크의 전체 크기와 이를 사용하는 인스턴스의 수명이 비용에 영향을 미칩니다.

필요한 역할

Agent Platform 기능을 구성하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

• Cloud Run 리소스를 배포하고 관리하려면: Cloud Run 관리자 (roles/run.admin) 역할을 사용합니다.
• App Hub 리소스를 관리하려면 다음 중 하나를 사용합니다.
  • App Hub 관리자 (roles/apphub.admin)
  • Agent Registry API 관리자 (roles/apiregistry.admin)
• 특정 ID로 배포하려면 다음 중 하나를 사용합니다.
  • IAM 서비스 계정 사용자 (roles/iam.serviceAccountUser)
  • IAM 서비스 계정 관리자 (roles/iam.serviceAccountAdmin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

사용 사례

다음 시나리오에서 Cloud Run과 함께 Agent Platform 기능을 사용합니다.

• 수명 주기에 연결된 고유한 시스템 관리 ID를 사용하여 에이전트를 다른 에이전트, 도구, Google Cloud API 에 인증합니다.
• 조직의 Agent Registry 내에서 에이전트와 MCP 서버를 자동으로 검색할 수 있도록 합니다.
• Identity-Aware Proxy를 인증 정책으로 사용하여 MCP 서버를 보호합니다.

기능 및 ID 유형 이해

Cloud Run 리소스에서 기능 및 ID 속성을 설정하여 Agent Platform 기능을 구성합니다.

이 두 속성은 워크로드를 등록하고 식별하는 방법을 제어합니다.

• 기능 유형: 워크로드의 기본 목적을 선언합니다. 이 속성은 설정된 후에는 변경하거나 설정 해제할 수 없습니다. 워크로드에 다음 기능 유형 중 하나를 할당합니다.
  • agent: 워크로드를 AI 에이전트로 지정합니다. 이 유형의 워크로드는 agent-identity 유형을 사용해야 합니다.
  • mcp-server: 워크로드를 사용자 관리 MCP 서버로 지정합니다. 이 유형은 지원되는 모든 ID 유형을 사용할 수 있습니다.
• ID 유형: 워크로드에 할당된 ID의 종류를 지정합니다. 이 속성은 설정된 후에는 변경하거나 설정 해제할 수 없습니다. 워크로드에 다음 ID 유형 중 하나를 할당합니다.
  • agent-identity: 에이전트용으로 설계된 시스템 관리 에이전트 ID를 할당합니다. agent-identity로 배포하면 Agent Platform에서 기본적으로 ID 인증서를 사용 설정합니다. 선택 해제하려면 --no-identity-certificate 플래그로 서비스를 업데이트하거나 run.googleapis.com/identity-certificate-enabled: "false" 주석을 설정합니다. 자체 권한 또는 최종 사용자를 대신하여 행동하는 에이전트의 도구 및 리소스에 인증하는 방법에 관한 가이드 를 따르세요. 시스템 관리 에이전트 ID의 핵심 개념과 보안 이점을 이해하려면 Agent Identity에 대해 자세히 알아보세요.
  • service-account: 표준 Google Cloud 서비스 계정을 사용합니다.

구성 동작

기능 및 ID 속성의 동작은 선택한 조합에 따라 다릅니다.

기능 유형	ID 유형	결과 동작
agent	agent-identity	워크로드가 Agent Registry에 에이전트로 등록되고 시스템 관리 에이전트 ID가 할당됩니다.
agent	기타 또는 지정되지 않음	오류가 발생했습니다. functional-type=agent가 있는 워크로드는 identity-type=agent-identity를 사용해야 합니다.
mcp-server	agent-identity, service-account 또는 지정되지 않음	워크로드가 Agent Registry에 MCP 서버 (/mcpServers)로 등록됩니다. 지정되지 않은 경우 기본적으로 서비스 계정 ID가 사용됩니다.
지정되지 않음	service-account	워크로드가 표준 Cloud Run 서비스 또는 작업으로 실행됩니다.

서비스 및 작업의 기능 구성

Google Cloud CLI를 사용하여 Cloud Run 서비스 및 작업에서 Agent Platform 기능을 구성합니다.

서비스

• 에이전트를 배포하려면 --functional-type=agent 및 --identity-type=agent-identity를 지정합니다.

  gcloud beta run deploy SERVICE_NAME \
      --image=IMAGE_URL \
      --functional-type=agent \
      --identity-type=agent-identity

  다음을 바꿉니다.

  • SERVICE_NAME: Cloud Run 서비스의 이름입니다.
  • IMAGE_URL: 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest)입니다. Artifact Registry를 사용하는 경우 저장소 REPO_NAME이 이미 생성되어 있어야 합니다. URL은 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG 형식을 따릅니다.

• Agent Identity를 사용하도록 기존 서비스를 업데이트하려면 다음 안내를 따르세요.

  gcloud beta run services update SERVICE_NAME \
      --functional-type=agent \
      --identity-type=agent-identity \
      --no-traffic

  중요: 서비스 계정에서 agent-identity로 기존 서비스를 업데이트하면 Cloud Run에서 이전 서비스 계정의 권한을 상속하지 않는 새 보안 주체를 할당합니다. 연결 중단을 방지하려면 정책 분석 도구를 사용하여 필요한 역할을 식별하고 업데이트하기 전에 principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME 보안 주체에 사전 할당하거나 트래픽을 이전하기 전에 권한을 할당하도록 --no-traffic으로 서비스를 업데이트합니다.

  다음을 바꿉니다.

  • SERVICE_NAME: Cloud Run 서비스의 이름입니다.
  • ORGANIZATION_ID: Google Cloud조직 ID입니다.
  • PROJECT_NUMBER: Google Cloud 프로젝트 번호입니다.
  • REGION: 서비스가 배포된 리전입니다.

• 사용자 관리 MCP 서버를 배포하려면 --functional-type=mcp-server를 지정합니다. --identity-type을 사용하여 ID 유형을 선택적으로 지정할 수 있습니다.

  gcloud beta run deploy SERVICE_NAME \
      --image=IMAGE_URL \
      --functional-type=mcp-server \
      --identity-type=IDENTITY_TYPE

  다음을 바꿉니다.

  • SERVICE_NAME: Cloud Run 서비스의 이름입니다.
  • IMAGE_URL: 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest)입니다. Artifact Registry를 사용하는 경우 저장소 REPO_NAME이 이미 생성되어 있어야 합니다. URL은 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG 형식을 따릅니다.
  • IDENTITY_TYPE: 선택사항입니다. 워크로드에 할당된 ID의 유형입니다. agent-identity 또는 service-account를 지정합니다. 기본값은 service-account입니다.

작업

참고: Cloud Run 서비스만 MCP 서버로 노출될 수 있습니다. Cloud Run 작업은 MCP 서버로 노출될 수 없으며 agent 기능 유형만 지원합니다.

• 에이전트 작업을 만들려면 --functional-type=agent 및 --identity-type=agent-identity를 지정합니다.

  gcloud beta run jobs create JOB_NAME \
    --image=IMAGE_URL \
    --functional-type=agent \
    --identity-type=agent-identity

  다음을 바꿉니다.

  • JOB_NAME: Cloud Run 작업의 이름입니다.
  • IMAGE_URL: 컨테이너 이미지에 대한 참조입니다.

할당된 ID 보기

콘솔 Google Cloud 또는 gcloud CLI에서 할당된 에이전트 ID를 볼 수 있습니다.

서비스

콘솔

1. Google Cloud 콘솔에서 Cloud Run으로 이동합니다.

   Cloud Run으로 이동

2. Cloud Run 탐색 메뉴에서 서비스 를 선택하고 서비스를 클릭합니다.

3. 버전 탭을 클릭하고 버전을 선택합니다.

4. 보안 탭을 클릭합니다.

ID 필드에 할당된 에이전트 ID가 표시됩니다.

gcloud

에이전트 ID를 보려면 서비스 버전을 설명합니다.

gcloud beta run revisions describe REVISION_NAME

REVISION_NAME을 서비스 버전의 이름으로 바꿉니다.

할당된 에이전트 ID가 출력에 표시됩니다.

작업

콘솔

1. Google Cloud 콘솔에서 Cloud Run으로 이동합니다.

   Cloud Run으로 이동

2. Cloud Run 탐색 메뉴에서 작업 을 선택하고 작업을 클릭합니다.

3. 실행 탭을 클릭하고 실행을 선택합니다.

4. 실행 세부정보를 봅니다.

ID 필드에 할당된 에이전트 ID가 표시됩니다.

gcloud

작업 실행의 에이전트 ID를 보려면 실행을 설명합니다.

gcloud beta run jobs executions describe EXECUTION_NAME

EXECUTION_NAME을 작업 실행의 이름으로 바꿉니다.

할당된 에이전트 ID가 출력에 표시됩니다.

Agent Registry에서 에이전트 또는 MCP 보기

--functional-type=agent 또는 --functional-type=mcp-server로 Cloud Run 리소스를 배포하면 조직의 Agent Registry에 자동으로 등록됩니다.

• 에이전트는 에이전트 카탈로그 (/agents)에 등록됩니다 .
• MCP 서버는 MCP 서버 카탈로그 (/mcpServers)에 등록됩니다.

레지스트리에 등록된 에이전트와 도구를 보고 에이전트와 도구를 안전하게 저장하고 검색하는 방법을 알아보려면 Agent Registry를 살펴보세요.

다음 단계

• API 및 도구에 에이전트를 인증하는 방법을 알아봅니다.
• 보안 연결을 위해 MCP 서버를 인증하는 방법 을 알아봅니다.
• Cloud Run에서 MCP 서버를 호스팅하는 방법을 알아봅니다.
• 에이전트 개발 키트를 사용하여 레지스트리에 커스텀 에이전트를 빌드하고 등록합니다.
• A2A 사양을 준수하는 에이전트를 빌드하고 배포하려면 Cloud Run에 A2A 에이전트 배포를 참조하세요.
• 에이전트 등록 또는 ID 할당에 문제가 발생하면 문제 해결 가이드 를 참조하세요.