프로젝트 간 경계

미리보기

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

교차 프로젝트 관리 경계 (또는 경계)를 사용하면 여러 Google Cloud 프로젝트에서 AI 에이전트, 모델 컨텍스트 프로토콜 (MCP) 서버, 도구를 탐색, 관리, 제어할 수 있습니다. Agent Registry는 기본적으로 단일 거버넌스 프로젝트 내에서 작동하지만 Resource Manager에서 관리 경계를 구성하면 중앙 관리 프로젝트가 분산된 구성원 프로젝트 전반에서 에이전트, MCP 서버, 도구를 집계할 수 있습니다. 관리 경계가 프로젝트 역할, 리소스 집계, 액세스 제어를 구조화하는 방법을 이해하면 확장 가능한 멀티 프로젝트 토폴로지를 설계하는 데 도움이 됩니다.

관리 경계를 구성하려면 여러 프로젝트의 관리 경계 구성을 참조하세요.

경계 모델

Resource Manager에서 폴더 또는 조직에 관리 경계를 정의합니다.

• 폴더 전체 또는 조직 전체 경계: 기본적으로 태그 필터를 구성하지 않고 폴더 또는 조직에 경계를 만들면 경계에 해당 폴더 또는 조직의 모든 하위 프로젝트가 구성원 프로젝트로 포함됩니다.
• 태그 필터링 경계 (선택사항): 선택적으로 폴더 또는 조직의 하위 프로젝트를 여러 경계로 파티셔닝하려면 Resource Manager 태그를 사용하여 경계 멤버십을 필터링하면 됩니다. 예를 들어 prod 환경과 dev 환경을 분리할 수 있습니다. 각 경계에 포함할Google Cloud 프로젝트에 태그를 연결합니다. 폴더 또는 조직의 하위 프로젝트에 경계 필터와 일치하는 태그가 있으면 해당 프로젝트는 관리 경계의 구성원 프로젝트가 됩니다.

태그를 사용하여 관리 경계를 파티셔닝하면 태그는 다음과 같은 이점을 제공합니다.

• 동적 자동 등록: 클라우드 환경은 프로젝트를 자주 수정합니다. env=prod와 같은 등록된 태그 값으로 프로젝트에 태그를 지정하면 Agent Registry는 경계 정의를 수동으로 업데이트하지 않고도 해당 프로젝트를 경계의 구성원 프로젝트로 자동으로 포함합니다.
• 폴더 계층 구조에서 분리: Resource Manager 폴더 구조는 일반적으로 결제 또는 비즈니스 목적으로 구성됩니다. 태그는 경계 정의를 물리적 폴더 계층 구조에서 분리하여 상위 폴더 또는 조직에서 폴더 간 관리 경계를 설정할 수 있게 해줍니다.
• 상속 및 확장성: 조직 또는 폴더에 적용된 태그는 리소스 계층 구조를 따라 하위 폴더 및 프로젝트로 자동 전파됩니다. 이 상속 모델을 사용하면 단일 태그 할당으로 리소스 트리의 전체 브랜치를 등록할 수 있습니다.
• 중앙 집중식 거버넌스: 태그는 중앙 집중식 Identity and Access Management (IAM) 권한으로 관리됩니다. 태그를 사용하여 관리 경계를 정의하면 개별 사용자가 경계에서 프로젝트를 임의로 추가하거나 삭제하지 못하도록 할 수 있습니다.

아키텍처 및 주요 리소스

프로젝트 간 관리 경계는 다음 Resource Manager 리소스에 따라 달라집니다.

• 경계 구성 (BoundaryConfig 리소스): 해당 폴더 또는 조직의 경계 파티셔닝 규칙을 설정하는 Resource Manager의 조직 또는 폴더에 있는 구성 리소스입니다. BoundaryConfig 리소스에 태그 키를 설정하지 않으면 조직 또는 폴더가 모든 하위 프로젝트를 포함하는 단일 경계를 지원합니다. 하위 프로젝트를 여러 태그 필터링 경계로 파티셔닝하기 위해 BoundaryConfig 리소스는 해당 폴더 또는 조직의 프로젝트 멤버십을 평가하는 데 사용되는 단일 리소스 태그 키(예: 123456789012/env)를 지정합니다.

• 경계 (Boundary 리소스): 조직 또는 폴더에 있는 구성원 프로젝트의 경계입니다. 태그 필터가 없으면 경계에 상위 조직 또는 폴더의 모든 하위 프로젝트가 포함됩니다. 상위 BoundaryConfig 리소스에서 태그 키를 구성하면 Boundary 리소스가 env=prod와 같은 태그 값 필터를 지정하고 해당 태그 값을 상속하거나 연결하는 하위 프로젝트가 자동으로 경계에 속합니다. 상위 요소의 BoundaryConfig 리소스는 단일 태그 키를 사용하고 프로젝트는 태그 키당 하나의 유효 태그 값만 가질 수 있으므로 프로젝트는 상위 폴더 또는 조직당 최대 하나의 경계에 속할 수 있습니다.

• 기능 구성 (CapabilityConfig 리소스): 조직, 폴더 또는 프로젝트에 정의된 리소스입니다. 조직 또는 폴더 수준에서 하나 이상의 경계를 전용 관리 프로젝트에 바인딩하고 해당 경계에서 사용 설정된 관리 기능을 지정합니다. 프로젝트 수준에서는 경계가 없는 단일 독립형 프로젝트에 대한 관리 기능을 사용 설정합니다. Agent Registry의 경우 AGENT_MANAGEMENT(Google Cloud CLI: agent-management) 기능을 구성합니다. 이 기능은 Agent Registry에서 중앙 집중식 구성요소 검색, 검색 롤업, 교차 프로젝트 거버넌스를 사용 설정하고 관리 프로젝트에서 agentregistry.googleapis.com를 자동으로 사용 설정합니다.

이러한 Resource Manager 리소스에 대한 자세한 내용은 관리 경계 및 기능 개요를 참조하세요.

다음 다이어그램은 Resource Manager 리소스가 구성원 프로젝트를 중앙 관리 프로젝트에 연결하는 방법을 보여줍니다.

그림 1. 구성원 프로젝트를 중앙 관리 프로젝트에 연결하는 프로젝트 간 관리 경계의 아키텍처

다중 프로젝트 관리

관리 경계는 중앙 관리 프로젝트와 하나 이상의 구성원 프로젝트라는 두 가지 고유한 프로젝트 역할에서 관리 거버넌스를 컴퓨팅 실행과 분리합니다.

이 분리된 구조는 멀티 테넌트 격리를 적용합니다. 팀은 다른 구성원 프로젝트에 직접 액세스할 필요 없이 각 구성원 프로젝트에서 에이전트를 빌드하고 배포하며, 관리자와 조정자는 관리 프로젝트에서 관리 경계 전반에 걸쳐 통합된 가시성을 유지합니다.

관리 프로젝트

관리 프로젝트는 관리 경계의 중앙 거버넌스 프로젝트 역할을 하는 Google Cloud 프로젝트입니다. 기본 컴퓨팅 런타임을 호스팅할 필요 없이 경계 전반에서 API 구성, 액세스 제어, 청구, 할당량 소비, 집계된 구성요소 메타데이터를 중앙 집중화합니다.

에이전트 레지스트리에서 관리 프로젝트는 다음 기능을 수행합니다.

• 경계 및 기능 바인딩: AGENT_MANAGEMENT 기능이 사용 설정된 CapabilityConfig 리소스를 통해 Resource Manager의 하나 이상의 경계와 연결됩니다. 구성 단계는 관리 경계 구성을 참조하세요.
• 중앙 집중식 검색 및 탐색: 프로젝트 간 목록 및 검색 요청의 대상 프로젝트 역할을 하여 조정자, 개발자, 클라이언트 애플리케이션이 경계 내의 모든 구성원 프로젝트에서 자동 검색된 에이전트, MCP 서버, 도구와 상호작용할 수 있도록 합니다.
• 경계 전체 리소스 등록: 커스텀 에이전트, 외부 MCP 서버, 엔드포인트와 같은 수동으로 등록된 Service 리소스와 관리 경계 전반에 표시하려는 Binding 리소스를 호스팅합니다.
• 중앙 집중식 API, 결제, 할당량 관리: 경계 수준 검색 및 거버넌스 작업을 위해 Agent Registry API 활성화, 할당량 할당, 결제를 통합합니다.

Resource Manager의 폴더 또는 조직에서 CapabilityConfig 리소스를 구성할 때 다음 방법 중 하나로 관리 프로젝트를 프로비저닝할 수 있습니다.

• 자체 관리형 관리 프로젝트: CapabilityConfig 리소스를 만들 때 --management-project 플래그를 전달하여 관리하는 기존Google Cloud 프로젝트를 지정합니다. 프로젝트는 CapabilityConfig 리소스와 동일한 상위 폴더 또는 조직에 직접 있어야 하며 다른 CapabilityConfig 리소스의 관리 프로젝트로 이미 사용되고 있지 않아야 합니다. 나중에 CapabilityConfig 리소스를 삭제하면 Resource Manager는 자체 관리형 프로젝트를 보존하고 표준 프로젝트로 되돌립니다.
• Google 관리 프로젝트: CapabilityConfig 리소스를 만들 때 --management-project 플래그를 생략하면 Resource Manager가 상위 폴더 또는 조직에서 새 프로젝트를 자동으로 만들고 관리합니다. 생성된 프로젝트의 프로젝트 ID 프리픽스는 google-mpf 또는 google-mpo입니다. 나중에 CapabilityConfig 리소스를 삭제하면 Resource Manager가 이 Google 관리 프로젝트를 삭제합니다.

두 경우 모두 agent-management를 사용하여 CapabilityConfig 리소스를 만들면 관리 프로젝트에서 agentregistry.googleapis.com가 자동으로 사용 설정됩니다.

회원 프로젝트

구성원 프로젝트는 관리 경계에 속하는 Google Cloud 프로젝트입니다. 경계의 상위 폴더 또는 조직의 모든 하위 프로젝트이거나 env=prod과 같은 선택적 경계 태그 필터와 일치하는 하위 프로젝트일 수 있습니다. 자동 검색된 에이전트, MCP 서버, 도구는 구성원 프로젝트에서 실행됩니다.

구성원 프로젝트는 Agent Runtime 추론 엔진, Cloud Run 서비스, GKE 클러스터와 같은 자체 로컬 컴퓨팅 리소스를 유지합니다. 자동 검색된 리소스는 각 구성원 프로젝트 내에서 로컬로 수집되고 레지스트리를 나열하거나 검색할 때 관리 프로젝트로 집계됩니다. 반면 구성원 프로젝트에서 만드는 수동으로 등록된 리소스는 해당 개별 구성원 프로젝트에 요청을 보낼 때만 표시됩니다.

경계에서 구성원 프로젝트와 관리 프로젝트의 연결에는 시스템 한도가 적용됩니다. 이 한도를 초과하면 롤업 오류가 발생할 수 있습니다. 자세한 내용은 할당량 및 시스템 한도를 참조하세요.

등록 및 롤업

에이전트 레지스트리의 프로젝트 간 검색은 구성원 프로젝트에 배포된 자동 검색 리소스와 생성된 프로젝트로 범위가 지정된 수동 등록 리소스를 구분합니다.

자동 검색 및 등록된 리소스

관리 경계에서 리소스의 범위가 지정되는 방식은 리소스가 등록되는 방식에 따라 다릅니다.

• 자동 검색된 에이전트 및 MCP 서버: Agent Runtime 추론 엔진, Cloud Run 서비스, GKE 배포와 같이 구성원 프로젝트에 배포된 지원되는 리소스는 배포된 구성원 프로젝트에 자동으로 수집되고 관리 프로젝트로 집계됩니다.

• 수동으로 등록된 리소스 및 바인딩: 커스텀 에이전트, 외부 MCP 서버, 엔드포인트, Binding 리소스와 같이 수동으로 등록된 Service 리소스는 생성된 프로젝트로 범위가 지정됩니다.

  • 관리 경계 전반에 표시하려면 관리 프로젝트에서 만듭니다.
  • 단일 구성원 프로젝트 내에서만 표시되도록 하려면 구성원 프로젝트에서 만듭니다.

• 독립형 기술, 게시자, AI 애플리케이션: 커스텀 독립형 Skill, SkillRevision, Publisher, AiApplication 리소스는 생성된 프로젝트로 범위가 지정되며 관리 경계의 구성원 프로젝트 간에 집계되지 않습니다. 에이전트 또는 개발자가 검색해야 하는 프로젝트에 커스텀 독립형 기술과 AI 애플리케이션을 등록합니다. Google 관리형 독립형 기술은 모든 프로젝트에서 자동으로 검색할 수 있습니다.

중앙 집중식 쿼리 롤업

에이전트 레지스트리가 위치의 범위를 지정하는 방법은 독립형 거버넌스 프로젝트를 쿼리하는지, 아니면 관리 경계의 구성원 프로젝트 또는 관리 프로젝트를 쿼리하는지에 따라 다릅니다.

• 독립형 거버넌스 프로젝트 및 구성원 프로젝트: us-central1, europe-west1, us, eu 또는 global와 같은 Agent Registry 지원 위치의 쿼리는 프로젝트 간 롤업 없이 해당 단일 프로젝트의 해당 위치에 있는 리소스만 반환합니다.

• 관리 프로젝트: 관리 프로젝트에서 agent-management를 사용하여 CapabilityConfig 리소스를 사용 설정하면 모든 에이전트 레지스트리 지원 위치에서 교차 프로젝트 롤업이 지원됩니다. 관리 프로젝트에서 위치를 쿼리하면 관리 프로젝트와 관리 경계에 있는 모든 구성원 프로젝트에서 동일한 위치의 리소스가 집계됩니다. 이 롤업에는 여러 위치의 리소스가 포함되지 않습니다.

  • 단일 리전: us-central1 또는 europe-west1와 같은 단일 리전의 쿼리는 관리 프로젝트 및 해당 구성원 프로젝트 전반에서 해당 단일 리전에 배포된 자동 검색된 에이전트와 MCP 서버를 관리 프로젝트의 해당 리전에 생성된 Service 및 Binding 리소스와 함께 집계합니다.
  • 멀티 리전: us 또는 eu와 같은 멀티 리전의 쿼리는 관리 프로젝트 및 해당 구성원 프로젝트 전반에서 해당 멀티 리전에 배포된 자동 검색 에이전트와 MCP 서버를 집계합니다. 멀티 리전의 쿼리는 단일 리전에 배포된 리소스를 집계하지 않습니다.
  • 전역: global 위치의 쿼리는 관리 프로젝트 및 해당 구성원 프로젝트 전반에서 global에 배포된 자동 검색된 에이전트와 MCP 서버를 집계하고, 관리 프로젝트의 global에 생성된 Service 및 Binding 리소스도 함께 집계합니다. global의 쿼리는 멀티 리전 또는 단일 리전에 배포된 리소스를 집계하지 않습니다.

관리 프로젝트의 위치에서 에이전트 구성요소를 나열, 검색 또는 가져올 때 Agent Registry는 다음 단계를 수행합니다.

1. 활성 CapabilityConfig 리소스를 통해 관리 프로젝트와 연결된 모든 구성원 프로젝트를 식별합니다.
2. 관리 프로젝트 및 각 구성원 프로젝트에서 해당 위치의 자동 검색된 에이전트와 MCP 서버를 쿼리하고, 관리 프로젝트의 해당 위치에 생성된 수동으로 등록된 Service 리소스도 함께 쿼리합니다.
3. 일치하는 리소스를 통합 결과 집합으로 집계합니다.
4. 집계된 결과를 반환합니다.

여러 경계가 동일한 CapabilityConfig 리소스에 연결된 경우 에이전트 레지스트리는 연결된 모든 경계의 구성원 프로젝트를 동일한 관리 프로젝트 레지스트리로 집계합니다. 관리 프로젝트의 목록 또는 검색 결과를 단일 구성원 프로젝트로 좁히려면 --filter="project_id=MEMBER_PROJECT_ID"를 전달합니다. 두 환경에 별도의 공개 상태가 필요한 경우 각 경계에 대해 별도의 CapabilityConfig 리소스 및 관리 프로젝트를 만듭니다.

단일 프로젝트 탐색과 교차 프로젝트 탐색은 동일한 API 메서드를 사용합니다. 검색 범위는 대상 프로젝트가 구성원 프로젝트인지 관리 프로젝트인지에 따라 다릅니다.

관리 경계 전반의 리소스 이름

구성요소가 구성원 프로젝트에 포함되면 Agent Registry는 AGENT_ID 또는 SERVER_ID와 같은 ID를 할당합니다. 관리 경계에서 구성요소를 나열, 검색 또는 가져올 때 에이전트 레지스트리는 해당 구성요소의 ID를 보존하고 사용하는 프로젝트에 따라 연결된 리소스 이름의 형식을 지정합니다.

• 관리 프로젝트: 관리 프로젝트를 사용하여 구성요소를 나열, 검색 또는 가져올 때 각 리소스 이름은 관리 프로젝트를 사용합니다.
• 구성원 프로젝트: 리소스가 배포된 구성원 프로젝트를 사용하여 구성요소를 나열, 검색 또는 가져올 때 각 리소스 이름은 해당 구성원 프로젝트를 사용합니다.

다음 표에서는 구성원 프로젝트에 배포된 자동 검색 리소스의 요청 URL과 연결된 리소스 이름을 보여줍니다.

리소스 유형	요청 URL	연결된 리소스 이름
에이전트	projects/MANAGEMENT_PROJECT_ID/locations/LOCATION/agents/AGENT_ID	projects/MANAGEMENT_PROJECT_ID/locations/LOCATION/agents/AGENT_ID
	projects/MEMBER_PROJECT_ID/locations/LOCATION/agents/AGENT_ID	projects/MEMBER_PROJECT_ID/locations/LOCATION/agents/AGENT_ID
MCP 서버	projects/MANAGEMENT_PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID	projects/MANAGEMENT_PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID
	projects/MEMBER_PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID	projects/MEMBER_PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID

연결된 리소스 이름은 요청의 프로젝트를 반영합니다. 하지만 구성요소의 레지스트리 식별자 및 런타임 참조는 변경할 수 없으며 기본 워크로드가 실행되는 구성원 프로젝트를 항상 유지합니다.

토폴로지 시각화 및 트래픽 흐름

플랫폼 관리자와 AI 설계자는 토폴로지 그래프를 사용하여 멀티 에이전트 관계와 프로젝트 간 트래픽을 시각화할 수 있습니다.

토폴로지 그래프는 다음 아키텍처 측정기준을 시각화합니다.

• 런타임 참조 상관관계: 논리적 에이전트 식별자를 물리적 런타임 참조와 연결합니다. 이 상관관계를 통해 운영자는 Agent Registry의 에이전트를 기본 Agent Runtime 추론 엔진, Cloud Run 서비스 또는 GKE 배포로 직접 추적할 수 있습니다.
• 교차 프로젝트 바인딩: 한 프로젝트의 조정자 에이전트와 다른 프로젝트의 MCP 서버 또는 다운스트림 도구 간의 바인딩을 표시합니다.
• 경계 확인: 관리자가 에이전트 통신이 VPC 서비스 제어 경계를 준수하고 지정된 Agent Gateway 엔드포인트를 통해 라우팅되는지 확인하는 데 도움이 됩니다.

액세스 제어

관리 경계에서 사용자와 조정자가 개별 구성원 프로젝트에 대한 직접적인 IAM 액세스 없이 경계 전반에서 검색할 수 있도록 관리 프로젝트에 IAM 검색 역할을 부여합니다. 멤버 프로젝트에서 생성된 수동으로 등록된 Service 및 Binding 리소스는 관리 프로젝트로 롤업되지 않으므로 보안 관리자는 조직 정책 제약 조건 또는 IAM 거부 정책을 사용하여 멤버 프로젝트에서 로컬 Service 및 Binding 생성을 제한할 수도 있습니다. 멤버 프로젝트의 에이전트가 도구를 호출하거나 경계를 넘어 다른 프로젝트의 에이전트와 통신할 때 트래픽은 중앙 Agent Gateway를 통해 라우팅될 수 있습니다.

관리 경계에 있는 리소스의 경우 VPC 서비스 제어 제한사항은 관리 프로젝트의 에이전트 레지스트리 상호작용에만 적용됩니다. Agent Registry는 구성원 프로젝트가 관리 프로젝트와 동일한 서비스 경계에 있지 않더라도 관리 경계 내의 모든 구성원 프로젝트에서 에이전트와 MCP 서버를 검색할 수 있습니다.

경계 설정, 레지스트리 액세스, 구성원 프로젝트 쓰기 제한에 필요한 역할에 대한 자세한 내용은 교차 프로젝트 관리 경계 역할을 참조하세요.

다음 단계

• Resource Manager에서 관리 경계를 구성합니다.
• 프로젝트 간 데이터 모델 알아보기
• 관리 경계 전반에서 검색
• 에이전트 레지스트리의 역할 및 권한을 검토합니다.