에이전트 공유

이 페이지에서는 사용자 또는 서비스 계정에 ID 및 액세스 관리 (IAM) 권한을 부여하여 프로젝트에서 단일 에이전트를 공유하는 방법을 설명합니다.

에이전트를 공유하려면 특정 에이전트 리소스에 aiplatform.reasoningEngines.query 권한을 부여합니다.

에이전트를 공유해야 하는 경우

에이전트를 공유하면 여러 사용자 또는 자동화된 시스템이 에이전트를 쿼리할 수 있습니다. 에이전트를 공유하는 일반적인 시나리오는 다음과 같습니다.

  • 협업: 팀 또는 조직의 다른 구성원과 에이전트를 공유하여 작업을 위해 에이전트를 사용합니다.
  • 애플리케이션 통합: 서비스 계정에 액세스 권한을 부여하여 내부 챗봇 또는 고객 지원 포털과 같은 커스텀 애플리케이션이 에이전트를 호출하여 특정 사용자 요청을 처리할 수 있도록 합니다.
  • 에이전트 간 통신: 멀티 에이전트 시스템에서 한 에이전트가 정보 또는 하위 작업 위임을 위해 다른 에이전트를 호출해야 할 수 있습니다.
  • 정보 액세스: 기본 데이터 소스에 대한 직접 액세스 권한을 부여하지 않고 대화형 인터페이스를 통해 사용자에게 데이터에 대한 제어된 액세스 권한을 제공합니다. 예를 들어 기술 자료 (예: HR 정책 또는 기술 문서)에 연결된 에이전트를 모든 직원과 공유합니다.

시작하기 전에

  1. 공유할 에이전트를 식별합니다. 에이전트의 프로젝트 ID와 추론 엔진 ID가 필요합니다.
  2. 액세스 권한을 부여할 사용자 또는 서비스 계정을 식별합니다.

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 = "REASONING_ENGINE_ID"
role             = google_project_iam_custom_role.reasoning_engine_query.name
member           = "USER_OR_SA"
}

다음을 바꿉니다.

  • PROJECT_ID: 프로젝트 ID
  • REGION: 리전
  • REASONING_ENGINE_ID: 에이전트의 추론 엔진 ID
  • USER_OR_SA: 사용자 또는 서비스 계정

보안 고려사항

에이전트에 대한 액세스 권한을 부여하면 에이전트의 엔드포인트로 메시지를 전송하는 직접 액세스 권한이 제공됩니다. 보안 제어는 트랜스퍼를 받는 에이전트의 코드로 결정됩니다.

  • 신뢰할 수 있는 프런트엔드: 대부분의 기본 에이전트 개발 키트 (ADK) 에이전트는 신뢰할 수 있는 프런트엔드에서 작동합니다. 에이전트는 프런트엔드 명령어를 신뢰하므로 프런트엔드가 세션과 사용자를 완전히 제어할 수 있습니다. 이러한 경우 신뢰할 수 없는 항목에 에이전트에 대한 직접 액세스 권한을 부여하지 마세요.
  • A2A 에이전트: Agent2Agent (A2A) 에이전트와 같은 다른 에이전트는 자체 인증 및 승인을 구현하는 경우 신뢰할 수 없는 항목에 노출될 수 있습니다. Agent Runtime은 에이전트 인터페이스에 대한 대략적인 액세스 제어만 제공합니다.

다음 단계