IAM 에이전트 ID 사용

에이전트 런타임에서 에이전트 ID를 사용하면 액세스 관리에 최소 권한 접근 방식을 사용할 수 있는 보안 에이전트별 ID가 제공됩니다. 이 문서에서는 에이전트 ID로 에이전트를 만들고,Google Cloud API에 대한 액세스를 승인하고, 서드 파티 서비스의 사용자 인증 정보를 관리하는 방법을 설명합니다.

개요

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

에이전트 ID 사용자 인증 정보는 Google 관리 컨텍스트 인식 액세스 (CAA) 정책을 통해 기본적으로 보호됩니다. 이 정책은 mTLS 바인딩을 적용하여 인증서 바인딩 토큰 형태의 에이전트 사용자 인증 정보가 의도된 신뢰할 수 있는 런타임 환경 (예: Cloud Run 컨테이너)에서만 사용될 수 있도록 합니다. 이 보안 기준을 통해 도난된 사용자 인증 정보를 재생할 수 없게 되어 사용자 인증 정보 도용 및 계정 탈취 (ATO)를 방지할 수 있습니다.

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

제한사항

에이전트 ID에는 Cloud Storage 버킷에 대한 기존 버킷 역할(storage.legacyBucketReader, storage.legacyBucketWriter 또는 storage.legacyBucketOwner)이 부여될 수 없습니다.

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

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

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

  • 에이전트 코드를 배포하지 않고 에이전트 런타임 인스턴스 만들기: 에이전트를 배포하기 전에 IAM 정책을 설정하려면 에이전트 코드를 배포하지 않고 에이전트 ID를 만들면 됩니다. 이렇게 하려면 identity_type 필드만 사용하여 Agent Runtime 인스턴스를 만드세요.

    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 Runtime 인스턴스를 만든 후 agent_engine.update(...)을 사용하여 에이전트 코드를 추가할 수 있습니다.

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

    선호하는 프레임워크에서 에이전트를 정의합니다.

    from google.adk.agents import Agent

agent = Agent(
    model="gemini-2.5-flash",
    name="minimal_agent",
    instruction="You are a helpful assistant.",
)

    그런 다음 배포합니다.

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

# Initialize the Agent Platform 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
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity
remote_app = client.agent_engines.create(
  agent=app,
  config={
    "display_name": "running-agent-with-identity",
    "identity_type": types.IdentityType.AGENT_IDENTITY,
    "requirements": ["google-cloud-aiplatform[adk,agent_engines]"],
    "staging_bucket": f"gs://"BUCKET_NAME",
  },
)

print(f"Effective Identity: {remote_app.api_resource.spec.effective_identity}")

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

  • 에이전트 CLI를 사용하여 에이전트 배포: 에이전트 CLI는 모니터링을 위한 기본 리소스를 제공하는 빠른 배포 솔루션을 제공하므로 학습자, 프로토타입 제작, 신속한 테스트에 적합합니다. 다음 명령어를 실행하면 에이전트가 배포됩니다.

    agents-cli deploy --agent-identity

  • ADK 배포를 사용하여 에이전트 ID로 에이전트 배포: ADK로 에이전트를 설정합니다. adk deploy를 실행하기 전에 에이전트 폴더에서 다음 명령어를 실행하여 에이전트 ID가 포함된 구성 파일을 추가합니다.

    # Create the file
$ touch .agent_engine_config.json

# Update the file to specify that you're using Agent Identity
$ echo '{ "identity_type": "AGENT_IDENTITY" }' > .agent_engine_config.json

에이전트 런타임 인스턴스는 읽기 전용 시스템 증명 에이전트 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: Agent Platform 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 인증서를 자동 프로비저닝하고 관리합니다. 기본적으로 에이전트는 자체 로깅, 측정항목, 모델 액세스, 세션, 메모리, 샌드박스 (미리보기)에 액세스할 수 있습니다.

에이전트 ID에는 에이전트가 작동할 수 있는 기본 권한이 있도록 기본 roles/aiplatform.agentContextEditor 및 roles/aiplatform.agentDefaultAccess 역할이 제공됩니다.

Agent Runtime 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: 에이전트가 프로젝트의 할당량과 Agent Platform SDK를 사용할 수 있는 권한을 부여합니다.

  • roles/browser: 기본 Google Cloud 기능에 대한 액세스 권한을 부여합니다.

로깅, 측정항목, Cloud API 레지스트리를 사용하는 경우와 에이전트에 노출하려는 다른 리소스의 경우 추가 권한이 필요할 수 있습니다. 자세한 내용은 나중에 나오는 예시를 참고하세요.

에이전트에게 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: 리전 런타임에서 지원되는 리전을 참고하세요.

  • AGENT_ENGINE_ID: 에이전트 런타임 인스턴스의 리소스 ID입니다.

  • ROLE_NAME: 부여할 역할의 이름입니다. 예를 들면 roles/vision.user입니다. 사전 정의된 역할의 목록은 역할 이해를 참고하세요.

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

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

특정 프로젝트 또는 전체 조직의 모든 에이전트 런타임 에이전트에 IAM 역할을 부여할 수 있습니다.

프로젝트의 모든 에이전트 런타임 에이전트에 역할을 부여하려면 다음 명령어 중 하나를 사용하세요.

프로젝트가 조직에 속한 경우:

# Grant all agents in a project the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

프로젝트가 조직에 속해 있지 않은 경우:

# Grant all agents in an orgless project the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.project-PROJECT_NUMBER.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"

배포를 간소화하기 위해 할당량, 로깅 또는 모델 액세스와 같은 공통 권한을 프로젝트의 모든 에이전트에 부여하는 것이 더 쉬울 수 있습니다. 그런 다음 데이터 액세스와 같은 더 민감한 권한에 대해 개별 상담사에게 구체적이고 좁은 권한을 부여합니다. 이러한 권한은 조직 또는 프로젝트 내에서 에이전트 ID 기능을 처음 사용한 후 언제든지 부여할 수 있으므로 에이전트 배포 전에 실행할 수 있습니다.

예를 들어 다음 명령어는 프로젝트의 모든 에이전트에게 기본 역할을 부여합니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/serviceusage.serviceUsageConsumer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/browser

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/aiplatform.expressUser

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/cloudapiregistry.viewer

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/logging.logWriter

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role=roles/monitoring.metricWriter

조직 전체의 모든 에이전트 런타임 에이전트에 역할을 부여하려면 다음 단계를 따르세요.

# Grant all agents in an organization the following role
gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
--member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platform/aiplatform" \
--role="ROLE_NAME"

에이전트 액세스 거부

에이전트의 리소스 액세스를 거부하려면 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

에이전트 활동 로깅

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

  • 상담사가 사용자를 대신하여 조치를 취하면 로그에 상담사와 사용자의 신원이 모두 표시됩니다.

  • 에이전트가 자체 권한으로 행동하는 경우 로그에는 에이전트의 ID만 표시됩니다.

에이전트 및 ID 나열

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

콘솔

  1. Google Cloud 콘솔에서 Agent Platform Deployments 페이지로 이동합니다.

    배포로 이동

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

  2. 각 상담사의 경우 상담사 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를 사용하지 않는 에이전트 런타임 인스턴스의 경우 effectiveIdentity 필드에 에이전트 런타임 인스턴스와 연결된 서비스 에이전트 또는 서비스 계정 이름이 포함됩니다.

컨텍스트 인식 액세스 (CAA) 선택 해제하기

기본적으로 의도된 에이전트 런타임 외부에서 액세스 토큰을 사용하려고 하면 다음 오류가 발생합니다.

Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"

상담사 간의 특정 토큰 공유 요구사항과 같은 특수한 경우에는 기본 CAA 정책을 선택 해제할 수 있습니다. 이 작업은 에이전트가 사용자 인증 정보 도난에 취약해지므로 권장되지 않습니다.

에이전트 런타임 인스턴스를 만들 때 다음 환경 변수를 설정하여 기본 컨텍스트 인식 액세스 (CAA) 정책을 선택 해제합니다.

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

다음 단계

가이드

Agent Platform 관리형 런타임에 배포된 에이전트를 관리하는 방법을 알아봅니다.

가이드

Agent Platform 런타임으로 에이전트를 사용합니다.