이 페이지에서는 사용자 또는 서비스 계정에 ID 및 액세스 관리 권한을 부여하여 프로젝트에서 단일 에이전트를 공유하는 방법을 설명합니다.
에이전트를 공유하려면 특정 에이전트 리소스에 aiplatform.reasoningEngines.query 권한을 부여합니다.
에이전트를 공유해야 하는 경우
에이전트를 공유하면 여러 사용자 또는 자동화된 시스템이 에이전트를 쿼리할 수 있습니다. 에이전트를 공유하는 일반적인 시나리오는 다음과 같습니다.
- 협업: 팀 또는 조직의 다른 구성원과 에이전트를 공유하여 작업에 사용할 수 있습니다.
- 애플리케이션 통합: 내부 챗봇이나 고객 지원 포털과 같은 맞춤 애플리케이션이 에이전트를 호출하여 특정 사용자 요청을 처리할 수 있도록 서비스 계정에 대한 액세스 권한을 부여합니다.
- 에이전트 간 통신: 멀티 에이전트 시스템에서 한 에이전트가 정보나 하위 작업을 위임하기 위해 다른 에이전트를 호출해야 할 수 있습니다.
- 정보 액세스: 기본 데이터 소스에 대한 직접 액세스 권한을 부여하지 않고 대화형 인터페이스를 통해 사용자에게 데이터에 대한 제어된 액세스 권한을 제공합니다. 예를 들어 기술 자료 (예: HR 정책 또는 기술 문서)에 연결된 에이전트를 모든 직원과 공유합니다.
시작하기 전에
- 공유할 에이전트를 식별합니다. 에이전트의 프로젝트 ID와 추론 엔진 ID가 필요합니다.
- 액세스 권한을 부여할 사용자 또는 서비스 계정을 식별합니다.
1단계: 맞춤 역할 만들기
최소 권한의 원칙을 따르려면 aiplatform.reasoningEngines.query 권한만 포함하는 맞춤 역할을 만드세요.
gcloud
프로젝트에서 맞춤 역할을 만들려면 다음 명령어를 실행합니다.
gcloud iam roles create ROLE_ID --project=PROJECT_ID \ --title="ROLE_TITLE" \ --description="ROLE_DESCRIPTION" \ --permissions=aiplatform.reasoningEngines.query
또는 조직 전체의 역할을 만들려면 다음 단계를 따르세요.
gcloud iam roles create ROLE_ID --organization=ORGANIZATION_ID \ --title="ROLE_TITLE" \ --description="ROLE_DESCRIPTION" \ --permissions=aiplatform.reasoningEngines.query
다음을 바꿉니다.
ROLE_ID: 역할의 ID입니다(예:agentUser).ROLE_TITLE: 역할의 제목입니다(예:Agent runtime user).ROLE_DESCRIPTION: 역할에 대한 간단한 설명입니다(예:Allows querying agents).PROJECT_ID: 프로젝트 ID입니다.ORGANIZATION_ID: 조직 ID
Terraform
Terraform을 사용하여 맞춤 역할을 만들려면 google_project_iam_custom_role 리소스를 사용합니다.
resource "google_project_iam_custom_role" "reasoning_engine_query" {
role_id = "ROLE_ID"
title = "ROLE_TITLE"
project = "PROJECT_ID"
permissions = ["aiplatform.reasoningEngines.query"]
}
다음을 바꿉니다.
ROLE_ID: 역할의 ID입니다(예:agentUser).ROLE_TITLE: 역할의 제목입니다(예:Agent runtime user).PROJECT_ID: 프로젝트 ID입니다.
맞춤 역할 이름은 projects/PROJECT_ID/roles/ROLE_ID 또는 organizations/ORGANIZATION_ID/roles/ROLE_ID입니다.
2단계: 에이전트에 역할 부여
역할이 생성되면 역할을 에이전트에 바인딩하고 권한을 부여할 사용자 또는 서비스 계정을 지정합니다.
Python
Python을 사용하여 역할을 부여하려면 google-cloud-aiplatform 라이브러리를 사용하세요.
from google.cloud.aiplatform_v1 import ReasoningEngineServiceClient from google.api_core.client_options import ClientOptions # Initialize the client client = ReasoningEngineServiceClient( client_options=ClientOptions(api_endpoint="LOCATION-aiplatform.googleapis.com") ) # Define the resource path resource = "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID" # Get the current IAM policy and add the new binding policy = client.get_iam_policy(request={"resource": resource}) binding = policy.bindings.add() binding.role = "projects/PROJECT_ID/roles/ROLE_ID" binding.members.append("USER_OR_SA") # Update the IAM policy on the resource client.set_iam_policy(request={"resource": resource, "policy": policy})
다음을 바꿉니다.
LOCATION: 에이전트가 배포된 리전입니다(예:us-central1).PROJECT_ID: 프로젝트 ID입니다.REASONING_ENGINE_ID: 에이전트의 추론 엔진 ID입니다.ROLE_ID: 역할의 ID입니다(예:agentUser).USER_OR_SA: 사용자 이메일 또는 서비스 계정(예:user:someone@example.com또는serviceAccount:my-sa@my-project.iam.gserviceaccount.com)
Terraform
Terraform을 사용하여 역할을 부여하려면 google_vertex_ai_reasoning_engine_iam_member 리소스를 사용합니다.
resource "google_vertex_ai_reasoning_engine_iam_member" "example" {
project = "PROJECT_ID"
region = "REGION"
reasoning_engine = google_vertex_ai_reasoning_engine.my_engine.name
role = google_project_iam_custom_role.reasoning_engine_query.name
member = "USER_OR_SA"
}
다음을 바꿉니다.
PROJECT_ID: 프로젝트 ID입니다.REGION: 리전USER_OR_SA: 사용자 또는 서비스 계정입니다.
보안 고려사항
에이전트에 대한 액세스 권한을 부여하면 에이전트의 FastAPI 엔드포인트로 메시지를 보낼 수 있는 직접 액세스 권한이 제공됩니다. 보안 보장은 수신 에이전트의 코드에 따라 결정됩니다.
- 신뢰할 수 있는 프런트엔드: 대부분의 기본 ADK 에이전트는 신뢰할 수 있는 프런트엔드에서 작동합니다. 에이전트는 프런트엔드 명령어를 신뢰하므로 프런트엔드가 세션과 사용자를 완전히 제어할 수 있습니다. 이러한 경우 신뢰할 수 없는 항목에 대한 직접 액세스 권한을 상담사에게 부여하지 마세요.
- A2A 에이전트: Agent2Agent (A2A) 에이전트와 같은 다른 에이전트는 자체 인증 및 승인을 구현하는 경우 신뢰할 수 없는 엔티티에 노출될 수 있습니다. 에이전트 런타임은 에이전트 인터페이스에 대한 대략적인 액세스 제어만 제공합니다.