에이전트 자체 권한을 사용하여 인증

에이전트는 자체 권한을 사용하여 Google Cloud API 및 기타 리소스에 액세스할 수 있습니다. 다른 Google Cloud 서비스와 상호작용하기 위해 호스팅되는 에이전트에는 이 방법을 사용하는 것이 좋습니다. Google Cloud

에이전트가 자체 권한으로 작동할 때는 기본 SPIFFE ID 를 사용하여 Google Cloud 액세스 토큰을 요청합니다.

시작하기 전에

필요한 역할

에이전트가 서비스에 액세스할 수 있는 권한을 부여하는 데 필요한 권한을 얻으려면 관리자에게 대상 리소스에 대한 다음 IAM 역할을 부여해 달라고 요청하세요. Google Cloud

에이전트에 액세스 권한을 부여하려면 다음 단계를 따르세요.
- 프로젝트 IAM 관리자 (roles/resourcemanager.projectIamAdmin)
- 보안 관리자 (roles/iam.securityAdmin)
에이전트 ID에 권장되는 역할:
- 에이전트 컨텍스트 편집자 (roles/aiplatform.agentContextEditor)
- 에이전트 기본 액세스 (roles/aiplatform.agentDefaultAccess)
- Vertex AI 사용자 (roles/aiplatform.user)
- 서비스 사용량 소비자 (roles/serviceusage.serviceUsageConsumer)
- 브라우저 (roles/browser)
- 스토리지 객체 뷰어 (roles/storage.objectViewer)

역할 부여 방법에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

에이전트에 액세스 권한 부여

에이전트가 Google Cloud 서비스에 액세스하도록 하려면 대상 리소스에 에이전트 ID에 필요한 역할을 부여해야 합니다.

IAM 허용 정책에서 에이전트 ID는 주 구성원 식별자를 사용합니다.

에이전트에 리소스 액세스 권한을 부여하려면 Google Cloud 콘솔 또는 gcloud CLI를 사용하세요.

콘솔

콘솔에서 액세스 권한을 부여할 리소스의 IAM 페이지로 이동합니다. Google Cloud
- 프로젝트의 경우 IAM 페이지로 이동합니다.
  IAM 페이지로 이동
- 다른 리소스의 경우 해당 리소스의 페이지로 이동하여 권한 또는 IAM 탭을 클릭합니다.
액세스 권한 부여 를 클릭합니다.
새 주 구성원 필드에 부여할 액세스 수준과 일치하는 주 구성원 식별자를 입력합니다.
- 단일 에이전트: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/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/*
역할 선택 필드에서 부여할 역할을 검색하여 선택합니다.
저장 을 클릭합니다.

Google Cloud CLI

에이전트에 리소스 액세스 권한을 부여하려면 다음 명령어를 실행합니다.

gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

다음을 바꿉니다.

SERVICE: 서비스 (예: storage 또는 bigquery). Google Cloud
RESOURCE_NAME: 리소스 이름 (예: 버킷 이름 또는 데이터 세트 ID).
PRINCIPAL_IDENTIFIER: 부여할 액세스 수준과 일치하는 주 구성원 식별자:
- 단일 에이전트: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/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/*
ORGANIZATION_ID: 조직 ID. Google Cloud
PROJECT_NUMBER: 귀하의 Google Cloud 프로젝트 번호.
LOCATION: 에이전트의 위치 (예: us-central1). (단일 에이전트 액세스에만 필요)
ENGINE_ID: 추론 엔진의 ID. (단일 에이전트 액세스에만 필요)
ROLE: 부여할 IAM 역할.

코드에서 에이전트 ID 참조

에이전트가 지원되는 Google Cloud 환경에 배포되면 Google Cloud 클라이언트 라이브러리가 자동으로 에이전트 ID를 사용합니다.

다음 Python 스니펫은 에이전트 개발 키트 (ADK)를 사용하여 에이전트 ID 사용자 인증 정보를 수동으로 사용하여 Cloud Vision API를 호출하는 방법을 보여줍니다.

from google.cloud import vision
from google.auth import default
from google.adk.tools import tool

@tool
def analyze_image_from_gcs(gcs_uri: str) -> dict:
    # Application default credentials automatically retrieve the
    # Agent Identity token from the metadata server.
    agent_identity_credentials, project_id = default()

    client = vision.ImageAnnotatorClient(
        credentials=agent_identity_credentials,
        project=project_id
    )

    # Prepare the image object with the Cloud Storage URI.
    image = vision.Image()
    image.source.image_uri = gcs_uri

    # Perform label detection on the image.
    response = client.label_detection(image=image)

    # Check for any errors returned by the API.
    if response.error.message:
        return {"status": "failure", "error_message": response.error.message}

    labels = response.label_annotations
    return {"status": "success", "labels": [label.description for label in labels]}

선택사항: 컨텍스트 인식 액세스 선택 해제

기본 Google 관리 컨텍스트 인식 액세스 정책은 에이전트 ID 사용자 인증 정보를 보호하는 데 도움이 됩니다. 에이전트 게이트웨이 외에도 이 정책은 에이전트의 액세스 토큰을 인증하여 소유 증명 (DPoP)을 시행합니다. 또한 이 정책은 mTLS를 사용하여 에이전트 게이트웨이에 액세스하도록 시행합니다. 이렇게 하면 인증서 바인딩 토큰을 의도된 신뢰할 수 있는 런타임 환경 (예: Cloud Run 컨테이너)에서만 사용할 수 있습니다. 이 보안 기준은 도난당한 사용자 인증 정보를 재사용할 수 없게 하여 사용자 인증 정보 도용 및 계정 탈취 (ATO)를 방지하는 데 도움이 됩니다.

에이전트 간의 특정 토큰 공유 요구사항과 같이 드문 경우에 헤더에 토큰을 직접 삽입해야 하거나 에이전트가 401 UNAUTHENTICATED 오류로 인증할 수 없는 경우 기본 컨텍스트 인식 액세스 정책을 선택 해제할 수 있습니다. 선택 해제하면 토큰 바인딩 보호가 삭제되어 이러한 단기 액세스 토큰이 도용 또는 재사용 공격에 취약해집니다. 따라서 선택 해제는 권장되지 않습니다.

선택 해제하려면 에이전트를 배포할 때 다음 환경 변수를 설정하세요.

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

에이전트 배포

에이전트를 Google Cloud배포할 때는 에이전트 ID가 사용 설정되어 있는지 확인하세요. 에이전트 런타임에 배포하는 경우 identity_type=AGENT_IDENTITY 플래그를 사용합니다.

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)