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

Vertex AI Agent Engine에서 에이전트 ID 사용

이 페이지에서는 Identity Access Management(IAM) 에이전트 ID를 사용하여 Vertex AI Agent Engine 런타임에서 에이전트를 사용할 때 보안 및 액세스 관리 기능을 제공하는 방법을 설명합니다.

개요

에이전트 ID는 최소 권한 접근 방식을 지원하고 에이전트의 수명 주기에 연결되는 에이전트별 ID를 제공하므로 에이전트 ID가 서비스 계정보다 더 안전한 주 구성원입니다. IAM을 통한 기존 액세스 관리 제어는 상담사 ID를 지원하여 강력한 거버넌스를 지원합니다.

이 페이지에서는 다음 주제에 대해 설명합니다.

에이전트 ID로 에이전트 만들기: Vertex AI Agent Engine 런타임에 배포할 때 에이전트가 고유 ID를 자동으로 수신하도록 에이전트를 만듭니다.
에이전트 ID를 사용하여 Google Cloud API에 대한 액세스 권한 부여: 프로비저닝된 에이전트 ID를 사용하여 에이전트가 Google Cloud의 서드 파티 도구, API, 리소스에 액세스하도록 허용하거나 거부합니다. 여기에는 Agent2Agent (A2A) 프로토콜을 사용하여 Vertex AI Agent Engine에서 호스팅되는 다른 에이전트에 대한 액세스도 포함됩니다.
OAuth를 사용하여 위임된 권한으로 서드 파티 서비스에 액세스: 에이전트가 사용자를 대신하여 작업을 실행할 수 있도록 OAuth를 사용하여 퍼스트 파티 및 서드 파티 도구에 사용자 위임 인증을 구성합니다.
API 키를 사용하여 서드 파티 서비스에 액세스: 런타임 중에 안전하게 저장되고 사용할 수 있는 API 키를 사용하여 서드 파티 서비스에 연결합니다.
상담사 활동 로깅: 여러 Google Cloud 서비스의 로그에서 상담사 ID를 확인합니다. 사용자 위임 흐름의 경우 로그에 사용자 ID와 에이전트 ID가 모두 표시됩니다.
에이전트 및 에이전트 ID 나열: Vertex AI Agent Engine에서 에이전트 목록과 ID를 확인합니다.

제한사항

프로젝트를 계획할 때 다음 제한사항을 고려하세요.

에이전트 ID에는 Cloud Storage 버킷에 대한 기존 버킷 역할(storage.legacyBucketReader, storage.legacyBucketWriter 또는 storage.legacyBucketOwner)이 부여될 수 없습니다.
테스트 환경에서만 에이전트 ID를 사용하는 것이 좋습니다.

에이전트 ID로 에이전트 만들기

Agent Engine 인스턴스를 만들 때 Vertex AI Agent Engine에 배포하는 에이전트에 고유한 ID를 프로비저닝할 수 있습니다. ID는 Vertex AI Agent Engine의 에이전트 리소스 ID에 연결되며 에이전트를 개발하는 데 사용한 에이전트 프레임워크와는 독립적입니다.

에이전트 ID를 만들 때 다음 옵션을 사용할 수 있습니다.

에이전트 코드를 배포하지 않고 Agent Engine 인스턴스 만들기: 에이전트를 배포하기 전에 IAM 정책을 설정하려면 에이전트 코드를 배포하지 않고 에이전트 ID를 만들면 됩니다. 이렇게 하려면 identity_type 필드만 사용하여 Agent Engine 인스턴스를 만드세요.
```
import vertexai
from vertexai import agent_engines
from vertexai import types

client = vertexai.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)
remote_app = client.agent_engines.create(
  config={"identity_type": types.IdentityType.AGENT_IDENTITY}
)
```
에이전트 ID로 Agent Engine 인스턴스를 만든 후 agent_engine.update(...)를 사용하여 에이전트 코드를 추가할 수 있습니다.

에이전트 코드를 배포하는 동안 Agent Engine 인스턴스 만들기: 에이전트 코드를 배포하는 동안 에이전트 ID를 프로비저닝하려면 Python용 Vertex AI SDK와 identity_type=AGENT_IDENTITY 플래그를 사용하세요.

import vertexai
from vertexai import agent_engines
from vertexai import types

client = vertexai.Client(
  project=PROJECT_ID,
  location=LOCATION,
  http_options=dict(api_version="v1beta1")
)
remote_app = client.agent_engines.create(
      agent=app,
      config={
          "identity_type": types.IdentityType.AGENT_IDENTITY,
          "requirements": ["google-cloud-aiplatform[adk,agent_engines]"],
          "staging_bucket": f"gs://"BUCKET _NAME",
      },
)

여기서 BUCKET_NAME은 Cloud Storage 버킷의 이름입니다.

에이전트 엔진 인스턴스는 읽기 전용 시스템 증명 에이전트 ID (주 구성원 식별자)로 생성됩니다.

# Agent identity Format
principal://TRUST_DOMAIN/NAMESPACE/AGENT_NAME

# Example agent identity
principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID

다음 부분은 에이전트 ID의 일부로 자동 프로비저닝됩니다.

TRUST_DOMAIN: Vertex AI API를 사용 설정하면 신뢰 도메인이 프로비저닝됩니다.
- 조직이 있는 경우 신뢰 도메인은 조직 수준에서 agents.global.org-ORGANIZATION_ID.system.id.goog 형식으로 생성됩니다.
- 프로젝트에 조직이 없는 경우 agents.global.project-PROJECT_NUMBER.system.id.goog 형식의 신뢰 도메인이 프로젝트 수준에서 생성됩니다.
NAMESPACE: 에이전트의 변경 불가능한 리소스 경로입니다.
AGENT_NAME: 변경 불가능한 agent-reasoning-engine-id입니다.

에이전트 ID는 SPIFFE를 기반으로 합니다. 또한 보안 인증을 위해 동일한 ID를 사용하여 에이전트에서 x509 인증서를 자동 프로비저닝하고 관리합니다.

Vertex AI Agent Engine Google Cloud 콘솔 및 API를 통해 ID를 볼 수 있습니다.

에이전트 ID를 사용하여 Google Cloud API 및 서비스에 액세스

에이전트 ID로 에이전트를 만든 후 다음 IAM 정책을 사용하여 Google Cloud API 및 서비스에 대한 에이전트 액세스를 부여하거나 거부할 수 있습니다.

허용 정책: 에이전트에게 Google Cloud 리소스에 대한 액세스 권한을 부여합니다.
거부 정책: 에이전트의 Google Cloud 리소스 액세스를 거부합니다.

상담사에게 액세스 권한 부여

에이전트 ID에 IAM 권한을 부여합니다. 다음 역할을 사용하는 것이 좋습니다.

roles/aiplatform.expressUser: 추론, 세션, 메모리 실행에 대한 액세스 권한을 부여합니다.
roles/serviceusage.serviceUsageConsumer: 에이전트가 프로젝트의 할당량과 Vertex AI SDK를 사용할 수 있는 권한을 부여합니다.

에이전트에게 IAM 역할을 부여하는 IAM 허용 정책을 만듭니다.

  # Example: Grant the agent access to vision API.
  gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
  --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID" \
  --role="ROLE_NAME" \

다음을 바꿉니다.

ORGANIZATION_ID: 조직의 ID입니다.
PROJECT_NUMBER: 프로젝트 번호입니다.
LOCATION: 리전 Vertex AI Agent Engine의 지원되는 리전을 참고하세요.
AGENT_ENGINE_ID: Agent Engine 인스턴스의 리소스 ID입니다.
ROLE_NAME: 부여할 역할의 이름입니다. 예를 들면 roles/vision.user입니다. 사전 정의된 역할의 목록은 역할 이해를 참고하세요.

IAM이 구성되면 Google Cloud SDK의 애플리케이션 기본 사용자 인증 정보가 에이전트 ID를 사용하여Google Cloud 리소스에 대한 인증을 자동으로 실행합니다.

에이전트에 대한 액세스 거부

에이전트의 리소스 액세스를 거부하려면 IAM 거부 정책을 사용하거나 주 구성원 액세스 경계 정책을 설정하면 됩니다.

IAM 거부 정책을 사용하여 에이전트의 특정 리소스 액세스를 거부합니다.

// Deny policy (deny all agents across the org from ability to create or delete buckets)

{
"displayName": "Deny access to bucket for all agent identities in the org",
"rules": [
  {
    "denyRule": {
      "deniedPrincipals": [
        "principalSet://<org.id>.global.agent.id.goog/*"
      ],
      "deniedPermissions": [
        "iam.googleapis.com/roles.create",
        "storage.googleapis.com/buckets.delete"
      ]
    }
  }
]
}

에이전트가 보유할 수 있는 다른 권한에도 불구하고 에이전트가 액세스할 수 있는 리소스를 제한하도록 주 구성원 액세스 경계를 설정합니다.

// PAB Policy (Only allow agents to operate within resource boundary)

{
    "name":"organizations/ORGANIZATION_ID/locations/global/principalAccessBoundaryPolicies/example-policy",
    "details": {
    "rules": [
      {
        "description": "Restrict agent identity inside a folder",
        "resources": [
          "//cloudresourcemanager.googleapis.com/folder/0123456789012"
        ],
        "effect": "ALLOW"
      }
    ],
  }
}

// Bind PAB policy to all identities in the organization (incl agent id)

gcloud iam principal-access-boundary-policies bindings create example-pab-binding \
      --organization=organizations/ORGANIZATION_ID \
      --policy=example-policy \ --target-principal-set=cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_ID

OAuth를 사용하여 위임된 권한으로 서드 파티 서비스에 액세스

에이전트 ID를 사용하면 Secret Manager와 통합하여 에이전트가 사용자를 대신하여 서드 파티 서비스에 액세스할 수 있습니다.

Secret Manager와의 통합을 설정하려면 먼저 다음 단계에 따라 서드 파티 서비스에 액세스하기 위한 보조 사용자 인증 정보 (클라이언트 ID 또는 클라이언트 보안 비밀번호)를 Secret Manager (에이전트가 수명 주기 관리되는 소비자 프로젝트)에 저장해야 합니다.

Secret Manager에서 새 컨테이너를 만듭니다.
서드 파티 앱 제공업체에서 클라이언트 ID 또는 클라이언트 보안 비밀번호를 가져옵니다.
Secret Manager에 클라이언트 ID 또는 클라이언트 보안 비밀번호를 추가합니다.

에이전트 ID (주 구성원 식별자)를 기반으로 이러한 사용자 인증 정보에 대한 액세스를 제한합니다.

# Create the secret container
gcloud secrets create my-app-oauth-secret

# Add the actual client secret to Secret Manager
gcloud secrets versions add my-app-oauth-secret "gcp-client-secret-1a2b3c4d"

# Grant agent identity access to the secret
gcloud secrets add-iam-policy-binding my-app-oauth-secret \
--role='roles/secretmanager.secretAccessor' \
--member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID" \

시크릿이 저장되면 에이전트는 런타임에 주 구성원 식별자와 표준Google Cloud 인증 라이브러리를 사용하여 애플리케이션 기본 사용자 인증 정보의 일부로 이러한 사용자 인증 정보에 자동으로 액세스할 수 있습니다.

# Example: Use agent identity to retrieve third party credentials from Secret Manager
# Use case: Using an agent, the user is trying to post a message on Slack,
# The developer first retrieves secret from Secret Manager using agent identity,
# and then uses it to login to Slack and post a message.

from google.cloud import secretmanager

def access_secret(project_id: str, secret_id: str, version_id: str = "latest") -> str:

      # Application default credential automatically gets token from MDS using agent identity
      agent_identity_credentials = default()

       # Create the Secret Manager client.
       client = secretmanager.SecretManagerServiceClient(credentials=agent_identity_credentials)

       # Build the resource name of the secret version.
       name = f"projects/{project_id}/secrets/{secret_id}/versions/{version_id}"

       # Access the secret version.
       response = client.access_secret_version(request={"name": name})

       # Decode the payload to get the secret string.
       secret_value = response.payload.data.decode("UTF-8")
       return secret_value

이제 클라이언트 ID와 클라이언트 보안 비밀번호를 사용하여 도구를 빌드하고 OAuth 기반 인증을 구성할 수 있습니다.

다음 예에서는 에이전트 개발 키트 (ADK)로 개발된 에이전트를 사용합니다. OAuth 기반 인증은 도구 생성의 일부로 authenticationScheme 및 authCredential 메서드로 래핑됩니다.

import os

from google.adk.auth.auth_schemes import OpenIdConnectWithConfig
from google.adk.auth.auth_credential import AuthCredential, AuthCredentialTypes, OAuth2Auth
from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset
from google.adk.agents.llm_agent import LlmAgent

auth_scheme = OpenIdConnectWithConfig(
   authorization_endpoint="https://your-endpoint.slack.com/oauth2/v1/authorize",
   token_endpoint="https://your-token-endpoint.slack.com/oauth2/v1/token",
   scopes=['openid', 'profile', "email"]
)

auth_credential = AuthCredential(
 auth_type=AuthCredentialTypes.OPEN_ID_CONNECT,
 oauth2=OAuth2Auth(
   client_id=access_secret(project_id: 'foo', secret_id: 'slack_oauth_client_id'),
   client_secret=access_secret(project_id: 'foo', secret_id: 'slack_oauth_client_secret'),
 )
)

# --- Slack Toolset Configuration Based On OpenAPI Specification ---

with open(os.path.join(os.path.dirname(__file__), 'spec.yaml'), 'r') as f:
   spec_content = f.read()

slack_toolset = OpenAPIToolset(
  spec_str=spec_content,
  spec_str_type='yaml',

  # ** Crucially, associate the authentication scheme and credentials with these tools. **
  # This tells the ADK that the tools require the defined OIDC/OAuth2 flow.
  auth_scheme=auth_scheme,
  auth_credential=auth_credential,
)

# Configure and create the main LLM Agent.

root_agent = LlmAgent(
   model='gemini-2.0-flash',
   name='enterprise_assistant',
   instruction='Help user integrate with Slack and post messages to Slack.',
   tools=userinfo_toolset.get_tools(),
)

런타임 중에 다음이 발생합니다 (ADK 웹을 통해 로컬로 ADK를 사용하는 경우 단계는 ADK 웹 및 ADK 백엔드 내에서 자동화됨).

사용자가 에이전트에 액세스하면 에이전트가 도구 (예: Slack)를 호출해야 한다고 결정합니다.
ADK 내부에 프로그래밍된 도구(auth_scheme 및 auth_credential 사용)는 리디렉션 URI와 클라이언트 ID를 포함하는 authConfig 객체를 프런트엔드에 반환합니다.
프런트엔드가 authConfig 객체를 파싱하고 서드 파티 승인 페이지로 리디렉션됩니다. 로그인하면 에이전트의 프런트엔드로 리디렉션되고 승인 코드가 ADK 백엔드로 전송됩니다.
백엔드에서는 승인 코드를 사용하여 서드 파티 서비스의 액세스 토큰을 가져오고 도구 실행을 계속합니다.

ADK 에이전트를 Vertex AI Agent Engine 런타임에 배포하는 경우 커스텀 프런트엔드를 빌드하고 ADK 웹 인증 또는 리디렉션 코드를 프런트엔드로 이전하여 동일한 OAuth 통합을 실행해야 합니다.

API 키를 사용하여 서드 파티 서비스에 액세스

에이전트 ID를 사용하면 에이전트가 API 키를 사용하여 서드 파티 서비스에 액세스하고 사용자를 대신하여 작업을 실행할 수 있습니다. 먼저 서드 파티 서비스에 액세스하기 위한 API 키를 Secret Manager에 저장한 다음 Secret Manager에서 이러한 사용자 인증 정보를 검색해야 합니다.

from google.adk.tools.openapi_tool.auth.auth_helpers import token_to_scheme_credential
from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset

WEATHER_DOT_COM_API_KEY = access_secret(project_id: 'foo', secret_id: 'weather_dot_com_api_key')

auth_scheme, auth_credential = token_to_scheme_credential(
   "apikey", "query", "apikey", WEATHER_DOT_COM_API_KEY
)

sample_api_toolset = OpenAPIToolset(
   spec_str="...",
   spec_str_type="yaml",
   auth_scheme=auth_scheme,
   auth_credential=auth_credential,
)

에이전트 활동 로깅

Cloud Logging을 사용 설정하면 어떤 에이전트와 사용자가 Google Cloud 리소스에 액세스했는지에 관한 로그를 볼 수 있습니다.

상담사가 사용자를 대신하여 조치를 취하면 로그에 상담사와 사용자의 신원이 모두 표시됩니다.
에이전트가 자체 권한으로 행동하는 경우 로그에는 에이전트의 ID만 표시됩니다.

에이전트 및 ID 나열

Google Cloud 콘솔과 명령줄을 사용하여 Vertex AI Agent Engine에서 에이전트 ID 목록을 확인할 수 있습니다.

콘솔

Google Cloud 콘솔에서 Vertex AI Agent Engine 페이지로 이동합니다.

Agent Engine으로 이동

선택한 프로젝트에 속하는 배포된 에이전트가 목록에 표시됩니다. 필터 필드를 사용하여 지정된 열을 기준으로 목록을 필터링할 수 있습니다.
각 상담사의 경우 상담사 ID가 ID 열에 표시됩니다.

REST API

REST API를 사용하여 에이전트 엔진 인스턴스를 가져올 때 에이전트 ID를 검색할 수 있습니다.

응답에는 다음 형식의 에이전트 ID가 포함됩니다.

{
  ...
  spec: {
    "effectiveIdentity": "agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID"
  }
  ...
}

에이전트 ID를 사용하지 않는 Agent Engine 인스턴스의 경우 effectiveIdentity 필드에 Agent Engine 인스턴스와 연결된 서비스 에이전트 또는 서비스 계정 이름이 포함됩니다.