에이전트 레지스트리 설정

Agent Registry에서 AI 에이전트, 모델 컨텍스트 프로토콜 (MCP) 서버, 독립형 스킬, 엔드포인트를 등록하고 검색하려면 Google Cloud 프로젝트에서 Agent Registry API를 사용 설정해야 합니다. 에이전트 레지스트리를 사용 설정하는 프로젝트는 거버넌스 프로젝트 역할을 합니다.

중앙 관리 프로젝트가 거버넌스 프로젝트 역할을 하는 관리 경계를 구성하여 단일 거버넌스 프로젝트 또는 여러 프로젝트에서 에이전트 레지스트리를 설정할 수 있습니다.

시작하기 전에

단일 프로젝트 또는 여러 프로젝트에서 Agent Registry를 구성합니다.

• 단일 프로젝트: 단일 Google Cloud 거버넌스 프로젝트에서 에이전트, MCP 서버, 스킬, 엔드포인트를 탐색하고 관리합니다. 기존 프로젝트를 사용하거나 프로젝트를 만들고 Agent Registry API를 사용 설정하고 권한을 부여합니다.
• 여러 프로젝트 (관리 경계): 관리 경계를 관리 프로젝트와 연결하여 Google Cloud 리소스 계층 구조의 여러 구성원 프로젝트에서 탐색 및 거버넌스를 중앙 집중화합니다. 기존 Google Cloud 프로젝트를 관리 프로젝트로 지정하거나 Resource Manager에서 프로젝트를 만들도록 허용하고, Resource Manager API를 사용 설정하고, 관리 경계를 구성하고, 권한을 부여합니다.

필요한 역할

에이전트 레지스트리를 설정하는 데 필요한 권한을 얻으려면 관리자에게 Google Cloud 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

• Agent Registry API 사용 설정: 서비스 사용량 관리자 (roles/serviceusage.serviceUsageAdmin)
• Agent Registry API 사용을 위한 역할 부여: 프로젝트 IAM 관리자 (roles/resourcemanager.projectIamAdmin)
• Agent Registry API 리소스에 대한 전체 액세스 권한 부여: Agent Registry API 관리자 (roles/agentregistry.admin)

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

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

Google Cloud CLI 환경 설정

Agent Registry에 gcloud CLI를 사용하려면 다음 단계를 따르세요.

1. Google Cloud 콘솔에서 Cloud Shell을 활성화합니다.

   Cloud Shell 활성화

   Google Cloud 콘솔 하단에서 Cloud Shell 세션이 시작되고 명령줄 프롬프트가 표시됩니다. Cloud Shell은 Google Cloud CLI가 사전 설치된 셸 환경으로, 현재 프로젝트의 값이 이미 설정되어 있습니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.

2. gcloud components update 명령어를 사용하여 gcloud CLI를 최신 버전으로 업데이트합니다.

   gcloud components update
   

3. 프리뷰 기능을 사용하려면 gcloud components install 명령어를 사용하여 alpha 구성요소를 설치합니다.

   gcloud components install alpha
   

Agent Registry API 사용 설정

• 단일 프로젝트: 거버넌스 프로젝트에서 Agent Registry API를 사용 설정합니다. API를 사용 설정하고 권한을 부여한 후 해당 프로젝트에서 에이전트를 등록하고 검색할 수 있습니다. 관리 경계를 구성할 필요가 없습니다.
• 여러 프로젝트 (관리 경계): 구성 명령어를 실행하는 데 사용하는 프로젝트에서 Resource Manager API를 사용 설정합니다. 여러 프로젝트의 관리 경계를 구성하고 기능 구성을 만들면 Resource Manager가 관리 프로젝트에서 Agent Registry API를 자동으로 사용 설정합니다.

프로젝트 ID를 사용하여 API를 사용 설정합니다.

콘솔

단일 프로젝트의 경우 프로젝트에서 Agent Registry API를 사용 설정합니다.

API 사용 설정에 필요한 역할

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

API 사용 설정하기

여러 프로젝트 (관리 경계)의 경우 구성에 사용하는 프로젝트에서 Resource Manager API를 사용 설정합니다.

API 사용 설정에 필요한 역할

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

API 사용 설정하기

gcloud

• 단일 프로젝트의 경우 gcloud services enable 명령어를 사용하여 프로젝트에서 Agent Registry API를 사용 설정합니다.

  gcloud services enable agentregistry.googleapis.com \
      --project=PROJECT_ID
  

• 여러 프로젝트 (관리 경계)의 경우 구성에 사용하는 프로젝트에서 Resource Manager API를 사용 설정합니다.

  gcloud services enable cloudresourcemanager.googleapis.com \
      --project=PROJECT_ID
  

PROJECT_ID를 독립형 거버넌스 프로젝트의 프로젝트 ID 또는 관리 경계의 관리 프로젝트로 사용할 프로젝트로 바꿉니다.

참고: 정책 시행을 위해 에이전트 레지스트리를 Agent Gateway와 통합하는 경우 프로젝트에서 Identity-Aware Proxy API도 사용 설정해야 합니다. 게이트웨이는 Identity-Aware Proxy API를 사용하여 에이전트에서 외부 대상으로의 이그레스 트래픽을 인증하고 승인합니다.

여러 프로젝트의 관리 경계 구성

미리보기

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

여러 Google Cloud 프로젝트에서 에이전트 레지스트리를 사용하려면 관리 경계를 구성합니다. 관리 경계는 하나 이상의 Google Cloud 구성원 프로젝트를 거버넌스 프로젝트 역할을 하는 중앙 관리 프로젝트로 그룹화하여 프로젝트 전반에서 AI 에이전트, MCP 서버, 도구를 탐색하고 제어할 수 있도록 합니다.

Resource Manager에서 관리 경계를 정의합니다. 단계별 안내는 Resource Manager 문서의 관리 경계 구성을 참조하세요.

BoundaryConfig, Boundary, CapabilityConfig 리소스가 함께 작동하는 방식에 대한 아키텍처 개요는 프로젝트 간 경계를 참조하세요.

agent-management를 사용하여 CapabilityConfig 리소스를 만들면 Resource Manager가 관리 프로젝트에서 agentregistry.googleapis.com를 자동으로 사용 설정합니다. 관리 경계를 설정한 후 다음을 수행합니다.

1. 개별 구성원 프로젝트 내에서 로컬 작업에 필요한 경우 해당 구성원 프로젝트에서 Agent Registry API를 사용 설정합니다.
2. 관리 프로젝트의 사용자 및 서비스 계정에 필요한 역할 및 권한을 부여합니다.

관리 프로젝트의 위치에서 에이전트 또는 MCP 서버를 나열하거나 검색하면 에이전트 레지스트리는 해당 위치에서 관리 프로젝트에 직접 생성된 등록된 Service 리소스와 함께 경계 내의 모든 구성원 프로젝트에서 자동 검색된 리소스를 집계하고 반환합니다. 반환된 각 리소스 이름은 구성요소의 ID를 보존하고 요청에 지정된 프로젝트를 사용합니다.

권한 부여

Agent Registry에서 리소스를 보고 관리하려면 사용자에게 적절한 Identity and Access Management (IAM) 권한을 부여해야 합니다.

사용자에게 다음 Agent Registry 역할 중 하나 이상을 부여합니다.

• Agent Registry API 뷰어 (roles/agentregistry.viewer): 에이전트, MCP 서버, 도구, 독립형 스킬, 스킬 버전, 게시자, 엔드포인트, 바인딩을 보고 검색합니다.
• Agent Registry API 편집자 (roles/agentregistry.editor): 에이전트, MCP 서버, 도구, 엔드포인트, 독립형 스킬, 스킬 버전의 등록, 업데이트, 삭제를 포함한 Agent Registry 리소스를 보고 수정합니다.
• Agent Registry API 관리자 (roles/agentregistry.admin): 에이전트, MCP 서버, 도구, 엔드포인트, 독립형 기술, 기술 버전, 바인딩, 기술 IAM 정책 등록 및 관리를 포함하여 Agent Registry 리소스에 대한 모든 작업을 수행합니다.
• 에이전트 레지스트리 사용자 (roles/agentregistry.user): 모든 에이전트 레지스트리 리소스를 보고 에이전트, MCP 서버 또는 엔드포인트에 대한 수정 액세스 권한 없이 독립형 스킬 및 스킬 버전을 만들고 업데이트하고 삭제합니다.

프로젝트에서 IAM 역할을 부여하는 방법은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

참고: Agent Registry와 Agent Gateway는 직원 ID 제휴를 제한적으로 지원합니다. Google Cloud 콘솔에서 로드 또는 승인 오류가 발생하면 Cloud ID 또는 Google Workspace를 통해 관리되는 표준 Google 계정으로 서비스에 액세스하세요.

에이전트 레지스트리 프로젝트 변경

Agent Registry를 사용하는 프로젝트를 변경하고 이전 프로젝트에서 종속 항목을 삭제하려면 이전 프로젝트에서 Agent Registry API를 사용 중지합니다. 이전 프로젝트에서 Agent Registry API를 사용 중지한 후 다른 프로젝트에서 사용 설정할 수 있습니다. 데이터가 마이그레이션되지 않으며 이 새 프로젝트에서 리소스를 다시 만들어야 합니다.

Agent Registry API 사용 중지

Agent Registry를 더 이상 사용하지 않으려면 프로젝트에서 Agent Registry API를 사용 중지합니다.

콘솔

1. Google Cloud 콘솔에서 Agent Registry API 관리 페이지로 이동합니다.

   Agent Registry API로 이동

2. 프로젝트 선택 도구에서 에이전트 레지스트리를 설정한 Google Cloud 프로젝트를 선택합니다.

3. API 사용 중지를 클릭합니다.

4. 확인 대화상자에서 사용 중지를 클릭합니다.

gcloud

gcloud services disable 명령어를 사용하여 프로젝트에서 Agent Registry API를 사용 중지합니다.

gcloud services disable agentregistry.googleapis.com \
    --project=PROJECT_ID

PROJECT_ID를 프로젝트 ID로 바꿉니다.

다음 단계

• 프로젝트 간 경계 알아보기
• 빠른 시작: 에이전트 등록
• MCP 서버 등록
• 기술 등록
• 에이전트, 도구, 스킬 검색