이 페이지는 Cloud Translation API를 통해 번역되었습니다.

배포된 에이전트의 액세스 관리

액세스 모드에 따라 사용할 수 있는 여러 인증 방법이 있습니다.

사용 사례	인증 방법	이 인증 방법에 대한 정보
에이전트 내에서 직접 데이터 소스에 액세스합니다.	서비스 계정	배포된 에이전트는 서비스 계정에 액세스 권한이 있는 모든 리소스에 액세스할 수 있습니다.
에이전트 내에서 API 키를 사용하여 엔드포인트로 요청을 보냅니다.	API 키	이 인증 방법을 사용하기 전에 사용하려는 API에서 API 키를 지원하는지 확인하세요.
에이전트의 최종 사용자를 위한 사용자 계정, 등록, 로그인 또는 승인을 처리합니다.	OAuth 클라이언트 ID	에이전트가 사용자의 동의를 요청하고 수락해야 합니다.

역할

Vertex AI Agent Engine에 배포하는 에이전트는 AI Platform Reasoning Engine 서비스 에이전트 또는 커스텀 서비스 계정을 사용하여 실행됩니다. 자세한 내용은 에이전트의 ID 및 권한 설정을 참조하세요.

AI Platform Reasoning Engine 서비스 에이전트

AI Platform Reasoning Engine 서비스 에이전트 서비스 계정은 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com 형식을 사용합니다.

서비스 계정에는 배포된 에이전트에 필요한 기본 권한을 부여하는 Vertex AI Reasoning Engine 서비스 에이전트 역할(roles/aiplatform.reasoningEngineServiceAgent)이 있습니다. IAM 문서에서 기본 권한의 전체 목록을 확인할 수 있습니다.

배포된 에이전트의 역할 나열

콘솔

IAM 페이지로 이동합니다.

IAM으로 이동
Google Cloud 프로젝트에 해당하는 프로젝트를 선택합니다.
에이전트 ID로 사용되는 서비스 계정과 일치하는 주 구성원을 찾습니다.
배포된 에이전트의 역할은 역할 열에서 확인할 수 있습니다.

gcloud

먼저 gcloud CLI를 설치하고 초기화합니다. 그러고 나서 다음 명령어를 실행합니다.

gcloud projects get-iam-policy PROJECT_ID_OR_NUMBER \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:PRINCIPAL" \
  --format="value(bindings.role)"

각 항목의 의미는 다음과 같습니다.

PROJECT_ID_OR_NUMBER: 프로젝트의 ID 또는 번호입니다.
PRINCIPAL: 에이전트가 Vertex AI Agent Engine에 배포될 때 사용된 서비스 계정을 기반으로 합니다.

자세한 내용은 IAM 문서 및 CLI 참조를 참조하세요.

Python

먼저 다음을 실행하여 클라이언트 라이브러리를 설치합니다.

pip install google-api-python-client

그런 다음 자신을 인증하고 다음을 실행하여 배포된 에이전트의 역할을 나열합니다.

from google.cloud import resourcemanager_v3
from google.iam.v1 import iam_policy_pb2

project_id = "PROJECT_ID"
principal = "PRINCIPAL"

crm_service = resourcemanager_v3.ProjectsClient()
policy = crm_service.get_iam_policy(iam_policy_pb2.GetIamPolicyRequest(
    resource=f"projects/{project_id}"
))
for binding in policy.bindings:
    for member in binding.members:
        if principal in member:
            print(binding.role)

여기서 PRINCIPAL은 에이전트가 Vertex AI Agent Engine에 배포될 때 사용된 서비스 계정을 기반으로 합니다.

배포된 에이전트 역할 부여

콘솔(권장)

IAM 페이지로 이동합니다.

IAM으로 이동
Google Cloud 프로젝트에 해당하는 프로젝트를 선택합니다.
에이전트 ID로 사용되는 서비스 계정과 일치하는 주 구성원을 찾습니다.
수정 버튼을 클릭하고 역할을 추가한 다음 저장 버튼을 클릭하여 주 구성원에 필요한 역할을 추가합니다.

gcloud

먼저 gcloud CLI를 설치하고 초기화합니다. 그러고 나서 다음 명령어를 실행합니다.

gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

각 항목의 의미는 다음과 같습니다.

PRINCIPAL: 에이전트가 Vertex AI Agent Engine에 배포될 때 사용된 서비스 계정을 기반으로 합니다.
ROLE_NAME: 부여할 역할의 이름입니다. 사전 정의된 역할의 목록은 역할 이해를 참조하세요.

자세한 내용은 IAM 문서 및 CLI 참조를 참조하세요.

Python

배포된 에이전트의 역할을 부여하거나 취소하기 위해 자체 Python 코드를 작성하지 않는 것이 좋습니다. 대신 일회성 작업에는 Google Cloud 콘솔 또는 gcloud를 사용하고 IAM 액세스 제어를 프로그래매틱 방식으로 관리하려면 Terraform을 사용하는 것이 좋습니다. Python에서 이 작업을 수행하려면 IAM 클라이언트 라이브러리 문서를 참조하세요.

배포된 에이전트의 역할 취소

콘솔(권장)

IAM 페이지로 이동합니다.

IAM으로 이동
Google Cloud 프로젝트에 해당하는 프로젝트를 선택합니다.
에이전트 ID로 사용되는 서비스 계정과 일치하는 주 구성원을 찾습니다.
수정 버튼을 클릭하고 해당 역할을 삭제한 다음 저장 버튼을 클릭하여 주 구성원에서 역할을 취소합니다.

gcloud

먼저 gcloud CLI를 설치하고 초기화합니다. 그러고 나서 다음 명령어를 실행합니다.

gcloud projects remove-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

각 항목의 의미는 다음과 같습니다.

PRINCIPAL: 에이전트가 Vertex AI Agent Engine에 배포될 때 사용된 서비스 계정을 기반으로 합니다.
ROLE_NAME: 취소할 역할의 이름입니다. 사전 정의된 역할의 목록은 역할 이해를 참조하세요.

자세한 내용은 IAM 문서 및 CLI 참조를 참조하세요.

Python

보안 비밀

보안 비밀에는 라벨 및 복제 정보와 같은 메타데이터와 함께 보안 비밀 버전이 한 개 이상 포함됩니다. 보안 비밀의 실제 페이로드는 보안 비밀 버전에 저장됩니다. 보안 비밀은 프로젝트 수준에서 Secret Manager를 통해 관리되며 배포된 여러 에이전트 간에 공유할 수 있습니다. Secret Manager에서 에이전트에 상응하는 보안 비밀을 나열하려면 라벨을 추가하고 이를 필터링에 사용할 수 있습니다.

보안 비밀 만들기

콘솔

Secret Manager 페이지로 이동합니다.

Secret Manager로 이동
Secret Manager 페이지에서 보안 비밀 만들기를 클릭합니다.
이름 필드에 보안 비밀의 이름을 입력합니다(예: my-secret).
선택사항: 초기 보안 비밀을 만들 때 보안 비밀 버전도 추가하려면 보안 비밀 값 필드에 보안 비밀의 값을 입력합니다(예: abcd1234).
라벨로 이동한 다음 라벨 추가를 클릭합니다.
키와 해당 값을 입력하여 라벨을 만듭니다.
보안 비밀 만들기를 클릭합니다.

gcloud

먼저 gcloud CLI를 설치하고 초기화합니다. 그리고 다음 명령어를 실행합니다.

gcloud secrets create SECRET_ID --replication-policy="automatic"
gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"

각 항목의 의미는 다음과 같습니다.

SECRET_ID: 보안 비밀의 ID 또는 보안 비밀의 정규화된 식별자
FILE_PATH: 버전 세부정보가 포함된 파일의 전체 경로(파일 이름 포함)

자세한 내용은 보안 비밀 및 보안 비밀 버전 만들기에 관한 Secret Manager 문서 또는 보안 비밀 및 보안 비밀 버전 만들기에 관한 CLI 참조를 확인하세요.

Python

먼저 다음을 실행하여 클라이언트 라이브러리를 설치합니다.

pip install google-cloud-secret-manager

그런 다음 자신을 인증하고 다음을 실행합니다.

from google.cloud import secretmanager
import google_crc32c

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "SECRET_ID",
    "secret": {  # google.cloud.secretmanager_v1.types.Secret
        # Required. The replication policy cannot be changed after the Secret has been created.
        "replication": {"automatic": {}},
        # Optional. Labels to associate with the secret.
        "labels": {"type": "api_key", "provider": "anthropic"},
        # Optional. The secret's time-to-live in seconds with format (e.g.,
        # "900s" for 15 minutes). If specified, the secret versions will be
        # automatically deleted upon reaching the end of the TTL period.
        "ttl": "TTL",
    },
})

anthropic_api_key = "API_KEY"  # The secret to be stored.
payload_bytes = anthropic_api_key.encode("UTF-8")
# Optional. Calculate payload checksum.
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

version = client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),  # Optional.
    },
})
print(f"Added secret version: {version.name}")

보안 비밀 가져오기

콘솔

Secret Manager 페이지로 이동합니다.

Secret Manager로 이동
Secret Manager 페이지에서 설명할 보안 비밀의 이름을 클릭합니다.
보안 비밀 세부정보 페이지에 보안 비밀에 대한 정보가 나열됩니다.

gcloud

먼저 gcloud CLI를 설치하고 초기화합니다. 그러고 나서 다음 명령어를 실행합니다.

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID

각 항목의 의미는 다음과 같습니다.

VERSION_ID: 보안 비밀 버전의 ID
SECRET_ID: 보안 비밀의 ID 또는 보안 비밀의 정규화된 식별자

자세한 내용은 Secret Manager 문서 또는 CLI 참조를 확인하세요.

Python

먼저 다음을 실행하여 클라이언트 라이브러리를 설치합니다.

pip install google-cloud-secret-manager

그런 다음 자신을 인증하고 다음을 실행합니다.

from google.cloud import secretmanager

client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.get_secret(request={"name": name})

보안 비밀 나열

콘솔

Secret Manager 페이지로 이동합니다.

Secret Manager로 이동
보안 비밀 테이블에서 필터 필드를 클릭합니다.
필터 속성과 해당 값(예: Location:asia-east1)을 선택합니다.
테이블이 입력된 값을 기준으로 자동으로 필터링됩니다.
(선택사항) 보안 비밀 버전을 필터링하려면 보안 비밀을 선택하여 버전에 액세스한 후 버전 테이블에서 필터 옵션을 사용합니다.

gcloud

먼저 gcloud CLI를 설치하고 초기화합니다.

프로젝트의 모든 보안 비밀을 나열하려면 다음 명령어를 실행합니다.

gcloud secrets list --filter="FILTER"

여기서 FILTER는 문자열(예: name:asecret OR name:bsecret) 또는 정규 표현식(예: name ~ "secret_ab.*")입니다.

보안 비밀의 모든 버전을 나열하려면 다음 명령어를 실행합니다.

gcloud secrets versions list SECRET_ID

SECRET_ID: 보안 비밀의 ID 또는 보안 비밀의 정규화된 식별자

자세한 내용은 보안 비밀 필터링 및 보안 비밀 버전 나열에 관한 Secret Manager 문서 또는 각각 보안 비밀 및 보안 비밀 버전 나열에 관한 CLI 참조를 확인하세요.

Python

먼저 다음을 실행하여 클라이언트 라이브러리를 설치합니다.

pip install google-cloud-secret-manager

그런 다음 자신을 인증하고 다음을 실행합니다.

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
for secret in client.list_secrets(request={
    "parent": "projects/PROJECT_ID",
    "filter": "FILTER", # e.g. "labels.provider=anthropic"
}):
    print(f"Found secret: {secret.name}")

보안 비밀 업데이트

콘솔

Secret Manager 페이지로 이동합니다.

Secret Manager로 이동
Secret Manager 페이지에서 보안 비밀 이름 옆에 있는 체크박스를 클릭합니다.
정보 패널이 닫혀 있으면 정보 패널 표시를 클릭하여 표시합니다.
정보 패널에서 라벨 탭을 선택합니다.
라벨 추가를 클릭하고 라벨의 키와 값을 입력합니다.
저장을 클릭합니다.

gcloud

먼저 gcloud CLI를 설치하고 초기화합니다. 그러고 나서 다음 명령어를 실행합니다.

gcloud secrets update SECRET_ID --update-labels=KEY=VALUE

각 항목의 의미는 다음과 같습니다.

SECRET_ID: 보안 비밀의 ID 또는 보안 비밀의 정규화된 식별자
KEY: 라벨 키
VALUE: 라벨의 해당하는 값

자세한 내용은 Secret Manager 문서 또는 CLI 참조를 확인하세요.

Python

먼저 다음을 실행하여 클라이언트 라이브러리를 설치합니다.

pip install google-cloud-secret-manager

그런 다음 자신을 인증하고 다음을 실행합니다.

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.update_secret(request={
    "secret": {
        "name": name,
        "labels": {"type": "api_key", "provider": "anthropic"}, # updated labels
    },
    "update_mask": {"paths": ["labels"]},
})
print(f"Updated secret: {response.name}")

보안 비밀 삭제

콘솔

Secret Manager 페이지로 이동합니다.

Secret Manager로 이동
Secret Manager 페이지의 보안 비밀 작업 열에서 더보기를 클릭합니다.
메뉴에서 삭제를 선택합니다.
보안 비밀 삭제 대화상자에 보안 비밀 이름을 입력합니다.
보안 비밀 삭제 버튼을 클릭합니다.

gcloud

먼저 gcloud CLI를 설치하고 초기화합니다.

보안 비밀 버전을 삭제하려면 다음 명령어를 실행합니다.

gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID

각 항목의 의미는 다음과 같습니다.

VERSION_ID: 보안 비밀 버전의 리소스 이름
SECRET_ID: 보안 비밀의 ID 또는 보안 비밀의 정규화된 식별자

보안 비밀과 모든 버전을 삭제하려면 다음 명령어를 실행합니다.

gcloud secrets delete SECRET_ID

SECRET_ID: 보안 비밀의 ID 또는 보안 비밀의 정규화된 식별자

자세한 내용은 보안 비밀 삭제 및 보안 비밀 버전 폐기에 관한 Secret Manager 문서 또는 보안 비밀 삭제 및 보안 비밀 버전 폐기에 관한 CLI 참조를 확인하세요.

Python

먼저 다음을 실행하여 클라이언트 라이브러리를 설치합니다.

pip install google-cloud-secret-manager

그런 다음 자신을 인증하고 다음을 실행합니다.

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
client.delete_secret(request={"name": name})

OAuth 클라이언트 및 사용자 인증 정보

클라이언트 ID는 Google OAuth 서버에서 단일 에이전트를 식별하는 데 사용됩니다. 에이전트가 여러 플랫폼에서 실행되는 경우 각각 자체 클라이언트 ID가 있어야 합니다. 대략적으로 OAuth 기반 에이전트를 통합하려면 다음 단계를 따르세요.

OAuth 클라이언트 및 사용자 인증 정보를 만듭니다.
클라이언트 ID와 보안 비밀을 Secret Manager에 저장합니다. (보안 비밀 만들기 참고)
개발 중 에이전트에서 보안 비밀에 액세스합니다.

OAuth 클라이언트 사용자 인증 정보 만들기

Google Cloud 콘솔에서 Google 인증 플랫폼 > 클라이언트 페이지로 이동합니다.

Google 인증 플랫폼 > 클라이언트로 이동
(필요한 경우) 화면에 'Google 인증 플랫폼이 아직 구성되지 않음'이 표시되면 시작하기를 클릭하고 프로젝트 구성을 작성합니다. (나중에 업데이트할 수 있습니다.) 프로덕션 준비에 관한 자세한 내용은 OAuth 2.0 정책 준수를 참고하세요.
클라이언트 만들기를 클릭합니다.
애플리케이션 유형을 Web application으로 설정합니다.
OAuth 클라이언트의 이름을 OAUTH_CLIENT_DISPLAY_NAME으로 설정합니다.
승인된 리디렉션 URI에서 REDIRECT_URI의 URI를 추가합니다.
클라이언트 보안 비밀번호에서 'JSON 다운로드' 버튼을 클릭합니다. 다음 콘텐츠가 포함된 client_secret.json 파일이 다운로드됩니다.

{'web': {
    'client_id': "CLIENT_ID",
    'client_secret': "CLIENT_SECRET",
    'project_id': "PROJECT_ID",
    'redirect_uris': [REDIRECT_URIs],
    'auth_uri': 'https://accounts.google.com/o/oauth2/auth',
    'token_uri': 'https://www.googleapis.com/oauth2/v3/token',
    'auth_provider_x509_cert_url': 'https://www.googleapis.com/oauth2/v1/certs',
    'javascript_origins': "JAVASCRIPT_ORIGINS",  # Optional.
}}

클라이언트 ID와 보안 비밀을 Secret Manager에 저장합니다. 예를 들면 다음과 같습니다.

from google.cloud import secretmanager
import google_crc32c
import json

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "OAUTH_SECRET_ID", # e.g. "oauth-client-demo"
    "secret": {
        "labels": {"type": "oauth_client"},
        "replication": {"automatic": {}},
    },
})

payload_bytes = json.dumps(cred).encode("UTF-8")
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),
    },
})

OAuth 클라이언트 표시

Google Cloud 콘솔에서 Google 인증 플랫폼 > 클라이언트 페이지로 이동합니다.

Google 인증 플랫폼 > 클라이언트로 이동
보유한 OAuth 클라이언트 사용자 인증 정보가 나열됩니다.

OAuth 클라이언트 삭제

Google Cloud 콘솔에서 Google 인증 플랫폼 > 클라이언트 페이지로 이동합니다.

Google 인증 플랫폼 > 클라이언트로 이동
삭제할 OAuth 클라이언트 사용자 인증 정보를 선택하고 '삭제'를 클릭합니다.

고객 관리 암호화 키(CMEK)

기본적으로 Google Cloud 는 Google에서 관리하는 암호화 키를 사용하여 데이터를 저장할 때 자동으로 암호화합니다. 데이터를 보호하는 키와 관련된 특정 규정 준수 또는 규제 요구사항이 있으면 배포된 에이전트에 고객 관리 암호화 키(CMEK)를 사용할 수 있습니다.

다음 내용을 비롯하여 Vertex AI와 함께 CMEK를 사용하는 방법에 관한 일반적인 요구사항과 안내는 Vertex AI용 CMEK 문서를 참조하세요.

프로젝트 설정(결제 및 사용 설정된 API)
키링 및 키 생성
필요한 권한 부여

에이전트의 CMEK를 사용 설정하려면 Agent Engine 인스턴스를 만들 때 Cloud KMS 키와 함께 encryption_spec을 지정해야 합니다. 코드 샘플은 고객 관리 암호화 키 구성을 참조하세요.

제한사항

Vertex AI Agent Engine에서 CMEK를 사용할 때는 다음 제한사항이 적용됩니다.

멀티 리전 키는 허용되지 않음: 단일 리전 키만 지원됩니다. 키링과 키의 리전은 Agent Engine 인스턴스와 동일해야 합니다.
CMEK 인스턴스의 암호화 키를 업데이트할 수 없음: CMEK 키로 에이전트가 배포되면 해당 배포의 암호화 키를 변경할 수 없습니다. 새 키를 사용하려면 새 Agent Engine 인스턴스를 배포해야 합니다.
암호화되지 않는 특정 메타데이터 및 운영 데이터: CMEK는 에이전트의 핵심 저장 데이터를 암호화합니다. 하지만 특정 메타데이터와 런타임 운영 데이터는 암호화되지 않습니다. 여기에는 다음이 포함됩니다.
- 에이전트 메타데이터:
  - 표시 이름
  - 설명
- 런타임 운영 데이터:
  - 서비스 계정 이메일
  - 에이전트 객체 클래스 메서드 이름
  - 환경 변수

배포된 에이전트의 액세스 관리 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

역할

AI Platform Reasoning Engine 서비스 에이전트

배포된 에이전트의 역할 나열

콘솔

gcloud

Python

배포된 에이전트 역할 부여

콘솔(권장)

gcloud

Python

배포된 에이전트의 역할 취소

콘솔(권장)

gcloud

Python

보안 비밀

보안 비밀 만들기

콘솔

gcloud

Python

보안 비밀 가져오기

콘솔

gcloud

Python

보안 비밀 나열

콘솔

gcloud

Python

보안 비밀 업데이트

콘솔

gcloud

Python

보안 비밀 삭제

콘솔

gcloud

Python

OAuth 클라이언트 및 사용자 인증 정보

OAuth 클라이언트 사용자 인증 정보 만들기

OAuth 클라이언트 표시

OAuth 클라이언트 삭제

고객 관리 암호화 키(CMEK)

제한사항

배포된 에이전트의 액세스 관리