ID 및 식별자

Agent Registry에서 에이전트를 등록하고 관리하려면 4개의 아키텍처 레이어에서 작업해야 합니다. 각 레이어는 특정 이름 지정, ID 또는 라우팅 메커니즘을 사용합니다.

  • 레지스트리 식별자 (에이전트 식별자, MCP 서버 식별자, 엔드포인트 식별자): 인벤토리 추적, 레지스트리 검색, 필터링에 사용되는 논리적이고 변경 불가능한 Uniform Resource Name (URN)입니다. 이러한 URN은 런타임 거버넌스에 사용되지 않습니다.
  • 리소스 이름: 등록 시 생성되고 Agent Gateway 라우팅 규칙, Identity-Aware Proxy (IAP) 이그레스 정책, Identity and Access Management (IAM) 정책 바인딩에서 사용되는 표준 전역 고유Google Cloud 리소스 이름 (registryResource 또는 name)입니다.
  • 에이전트 주 구성원: 호출자 인증, 승인, 감사 로깅에 사용되는Google Cloud 에서 실행되는 에이전트의 SPIFFE ID 또는 외부 에이전트의 서비스 계정과 같은 확인 가능한 IAM ID입니다.
  • 런타임 참조: 토폴로지 쿼리 및 이그레스 트래픽 일치에 사용되는 컴퓨팅 또는 인프라 경로 (RuntimeReference)입니다.

다음 표에서는 각 레이어, 기본 목적, 다운스트림 거버넌스 역할, 구문을 비교합니다.

레이어 기본 목적 거버넌스 역할 구문
레지스트리 식별자
(에이전트, MCP 서버 또는 엔드포인트 식별자)		 안정적인 레지스트리 검색, 메타데이터 태그 지정, 검색 변경할 수 없으며 거버넌스에 사용되지 않습니다.
  • urn:agent:IDENTIFIER
  • urn:mcp:IDENTIFIER
  • urn:endpoint:IDENTIFIER
리소스 이름 정책 시행을 위한 타겟 리소스 식별입니다. 정책에 필요하며 Agent Gateway 경로 및 IAP 바인딩에서 사용됩니다.
  • projects/PROJECT_NUMBER/locations/LOCATION/agents/agentregistry-ID
  • projects/PROJECT_NUMBER/locations/LOCATION/mcpServers/agentregistry-ID
  • projects/PROJECT_NUMBER/locations/LOCATION/endpoints/agentregistry-ID
에이전트 주 구성원 호출자 인증, 승인, 감사 로깅 IAM에 의해 적용됩니다.
  • principal://PRINCIPAL_PATH
  • principalSet://PRINCIPAL_SET_PATH
런타임 참조 물리적 컴퓨팅 라우팅 및 아웃바운드 트래픽 일치 네트워크 트래픽과 일치하도록 토폴로지 쿼리 및 Agent Gateway에서 평가됩니다. agentregistry.googleapis.com/system/RuntimeReference 컴퓨팅 또는 인프라 경로를 uri: "RUNTIME_URI"로 포함

레지스트리 식별자

레지스트리 식별자는 에이전트 레지스트리가 등록된 구성요소에 할당하는 전역적으로 고유하고 불변인 Uniform Resource Name(URN)입니다. 이 URN은 소비자 및 오케스트레이터 에이전트가 에이전트 레지스트리에서 구성요소를 검색, 필터링, 검색할 수 있는 안정적인 참조를 제공하며, 기본 인프라 마이그레이션이나 코드 업데이트와 관계없이 일정하게 유지됩니다.

레지스트리 식별자는 레지스트리 검색 및 메타데이터 주석에만 사용되는 논리적 URN입니다. 런타임 보안 ID 및 리소스 이름과 다르며 IAM 정책 바인딩, 승인 헤더 또는 Agent Gateway 라우팅 규칙에서 사용할 수 없습니다.

에이전트 레지스트리는 세 가지 유형의 레지스트리 식별자를 사용합니다.

에이전트 식별자

에이전트 레지스트리는 Google 관리 에이전트와 외부 또는 맞춤 에이전트를 비롯한 모든 등록된 에이전트에 에이전트 식별자 (agentId)를 할당합니다. 에이전트의 보안 정책에 따라 관리되는 통신을 관리하려면 에이전트 식별자 대신 에이전트 보안 주체를 사용하세요.

Agent Registry는 수집 중에 에이전트 식별자를 자동으로 생성합니다. 정확한 URN 구조는 에이전트가 배포된 컴퓨팅 환경에 따라 다릅니다.

  • Gemini Enterprise Agent Platform의 Agent Runtime: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:aiplatform:reasoningEngines:AGENT_ID
  • Cloud Run 서비스: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:services:SERVICE_NAME
  • Cloud Run 작업: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:jobs:JOB_NAME
  • GKE 배포: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:container:clusters:CLUSTER_NAME:k8s:namespaces:NAMESPACE:apps:deployments:DEPLOYMENT_NAME
  • Gemini Enterprise: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:global:discoveryengine:collections:default_collection:engines:ENGINE_ID:assistants:default_assistant:agents:AGENT_ID
  • Google Workspace: urn:agent:googleapis.com:locations:global:workspaceagent:workspaceagent--a2a
  • 수동으로 등록된 에이전트: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:AGENT_ID

MCP 서버 식별자

MCP 서버 식별자 (mcpServerId)는 에이전트 레지스트리에서 MCP 서버와 도구를 검색하는 데 사용되는 레지스트리 식별자입니다.

MCP 서버는 요청에만 응답하며 IAM 주 구성원이 없습니다. 에이전트가 MCP 서버에서 도구를 호출하면 호출하는 에이전트 주 구성원을 사용하여 액세스가 승인됩니다.

URN 형식은 서버가 Google 관리 서비스인지 아니면 외부 등록 서버인지에 따라 다릅니다.

  • Google 및 Google Cloud 원격 MCP 서버: urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:SERVER_ID
  • 수동으로 등록된 MCP 서버: urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:SERVER_ID

엔드포인트 식별자

엔드포인트 식별자 (endpointId)는 대상 API 대상을 검색하기 위해 등록된 엔드포인트에 할당된 레지스트리 식별자입니다.

수동으로 등록된 엔드포인트의 URN 형식은 urn:endpoint:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:ENDPOINT_ID입니다.

리소스 이름

에이전트 레지스트리에 에이전트, MCP 서버 또는 엔드포인트를 등록하면 등록 프로세스에서 계층적 URI 경로로 형식이 지정된 표준 Google Cloud 리소스 이름이 생성됩니다.

  • 에이전트: projects/PROJECT_NUMBER/locations/LOCATION/agents/agentregistry-ID
  • MCP 서버: projects/PROJECT_NUMBER/locations/LOCATION/mcpServers/agentregistry-ID
  • 엔드포인트: projects/PROJECT_NUMBER/locations/LOCATION/endpoints/agentregistry-ID

gcloud agent-registry services describe을 실행하는 등 쓰기 가능한 Service 리소스를 만들거나 검사하면 이 리소스 이름이 출력 전용 registryResource 필드에 반환됩니다. gcloud agent-registry agents describe 명령어를 사용하는 등 결과로 생성된 읽기 전용 Agent, McpServer 또는 Endpoint 리소스를 직접 쿼리하거나 검사하면 이 리소스 이름이 표준 name 필드에 반환됩니다.

리소스 이름은 정책을 바인딩하고, 네트워크 트래픽을 라우팅하고, 액세스 제어를 구성하는 데 사용할 수 있습니다. 에이전트 게이트웨이 라우팅 규칙, IAP 이그레스 정책, IAM 리소스 정책을 비롯한 다운스트림 거버넌스 표시 영역은 이 리소스 이름을 기준으로 평가됩니다. 에이전트 식별자, MCP 서버 식별자, 엔드포인트 식별자와 같은 레지스트리 식별자의 URN은 허용되지 않습니다.

정책 바인딩 또는 라우팅 규칙에서 리소스 이름 대신 등록기관 식별자 URN을 사용하면 API에서 NOT_FOUND: Requested entity was not found. 오류를 반환합니다. 거버넌스 정책을 구성할 때 이 오류가 발생하면 다음을 확인하세요.

  • 등록 상태: 대상 에이전트, MCP 서버 또는 엔드포인트가 예상 위치의 Agent Registry에 등록되어 있는지 확인합니다.
  • 식별자 형식: 정책 바인딩 또는 라우팅 규칙이 레지스트리 식별자 URN이 아닌 표준 리소스 이름(projects/PROJECT_NUMBER/locations/LOCATION/.../agentregistry-ID)을 지정하는지 확인합니다.

에이전트 보안 주체

에이전트 주 구성원은 IAM의 에이전트 보안 ID입니다. 사용자 또는 서비스 계정과 마찬가지로 에이전트는 주 구성원을 사용하여 권한을 보유하고 다운스트림 서비스를 호출합니다. IAM 정책을 구성할 때는 에이전트의 주 구성원 문자열을 사용하여 액세스 권한을 부여하거나 제한합니다.

Agent Registry에서 에이전트가 보안 주체로 식별되는 방식은 에이전트가 실행되는 위치에 따라 다릅니다.

  • 인프라 Google Cloud 에서 실행되는 에이전트: Gemini Enterprise Agent Platform의 에이전트 런타임과 같은 관리형 런타임의 경우 Google CloudSPIFFE ID 형식으로 관리형 워크로드 아이덴티티를 자동으로 프로비저닝하며, 이는 에이전트의 컴퓨팅 런타임에 직접 바인딩됩니다. IAM 허용 정책 및 바인딩에서 이 ID를 참조할 때는 SPIFFE URI 스킴이 아닌 IAM 주 구성원 또는 주 구성원 집합 문자열 형식을 사용해야 합니다. IAM 정책 바인딩에 SPIFFE 문자열을 사용하면 INVALID_ARGUMENT 오류가 반환됩니다.
  • Google Cloud외부에서 실행되는 에이전트: 외부 또는 온프레미스 에이전트는 워크로드 아이덴티티 제휴를 통해 외부 ID를 제휴하거나 표준 서비스 계정을 사용하여 Google Cloud 리소스와 상호작용해야 합니다. 인증되면 해당 제휴 워크로드 아이덴티티 문자열 또는 서비스 계정 이메일이 IAM 정책에서 에이전트 주 구성원 역할을 합니다.

Google Cloud에서 실행되는 에이전트의 경우 관리형 에이전트 보안 주체가 에이전트 런타임의 컴퓨팅 리소스에 직접 바인딩되므로 보안 주체 문자열에는 기본 컴퓨팅 리소스의 전체 경로가 포함됩니다.

IAM은 다음 범위에서 에이전트 액세스 관리를 지원합니다.

  • 단일 엔진 인스턴스: 특정 에이전트 배포에 권한을 부여합니다. 예를 들어 개별 Agent Runtime 인스턴스는 단일 주 구성원 문자열을 통해 표현됩니다.principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/REASONING_ENGINE_ID
  • 프로젝트 범위: 주 구성원 집합을 통해 특정 프로젝트 내에서 실행되는 모든 추론 엔진에 권한을 부여합니다. principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
  • 조직 전체 범위: 주 구성원 집합 와일드 카드를 통해 조직 전체의 모든 상담사에게 권한을 부여합니다. principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*

에이전트의 세부정보를 확인하면 Agent Registry에 개별 에이전트 주 구성원이 출력 전용 속성으로 표시됩니다.

런타임 참조

런타임 참조는 에이전트, MCP 서버 또는 엔드포인트의 코드가 실행되는 기본 컴퓨팅 인프라를 가리킵니다. 예를 들어 런타임 참조는 Agent Runtime 추론 엔진, GKE 배포 또는 Cloud Run 서비스를 가리킬 수 있습니다.

에이전트의 주 구성원 문자열에는 런타임 참조 경로가 포함되어 있으며, 이는 IAM 권한을 에이전트가 실행되는 위치에 직접 연결합니다. 에이전트가 배포된 프로젝트와 다른 프로젝트에 에이전트를 등록하면 런타임이 기본 워크로드를 호스팅하는 프로젝트를 가리킵니다.

에이전트 레지스트리 API에서 런타임 참조는 agentregistry.googleapis.com/system/RuntimeReference 속성으로 표시되며, 이 속성의 uri 필드에는 컴퓨팅 또는 인프라 경로가 포함됩니다. 이 출력 전용 속성을 에이전트 세부정보의 일부로 보거나 이를 사용하여 토폴로지 그래프에서 트래픽 흐름과 관계를 쿼리할 수 있습니다.

다음 단계