Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

에이전트 런타임에서 에이전트 ID 사용

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

개요

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

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

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

에이전트 ID로 에이전트 만들기: Agent Runtime에 배포할 때 에이전트가 고유한 ID를 자동으로 수신하도록 에이전트를 만듭니다.
에이전트 ID를 사용하여 Google Cloud API 액세스 권한 부여: 프로비저닝된 에이전트 ID를 사용하여 에이전트의 Google Cloud's 퍼스트 파티 도구, API, 리소스에 대한 액세스 권한을 부여하거나 거부합니다. 여기에는 Agent2Agent (A2A) 프로토콜을 사용하여 Agent Runtime에서 호스팅되는 다른 에이전트에 대한 액세스도 포함됩니다.
에이전트 활동 로깅: 서비스 전반의 로그에서 에이전트 ID를 봅니다. Google Cloud 사용자 위임 흐름의 경우 로그에 사용자 ID와 에이전트 ID가 모두 표시됩니다.
에이전트 및 에이전트 ID 나열: Agent Runtime에서 에이전트 목록과 해당 ID를 봅니다.
컨텍스트 인식 액세스 선택 해제 (권장되지 않음): 기본 컨텍스트 인식 액세스 (CAA) 정책을 선택 해제합니다.

제한사항

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

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

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

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

에이전트 코드를 배포하지 않고 Agent Runtime 인스턴스 만들기: 에이전트를 배포하기 전에 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(...)를 사용하여 추가할 수 있습니다.

에이전트 코드를 배포하는 동안 Agent Runtime 인스턴스 만들기: 에이전트 코드를 배포하는 동안 에이전트 ID를 프로비저닝하려면 Agent Platform SDK for Python 및 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 버킷의 이름입니다.

Agents CLI를 사용하여 에이전트 배포: Agents 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
```

Agent Runtime 인스턴스는 읽기 전용 시스템 증명 에이전트 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: Agent Runtime 인스턴스의 리소스 ID입니다.
ROLE_NAME은(는) 부여할 역할의 이름입니다. 예를 들면 roles/vision.user입니다. 사전 정의된 역할의 목록은 역할 이해를 참조하세요.

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

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

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

프로젝트의 모든 Agent Runtime 에이전트에 역할을 부여하려면 다음 명령어 중 하나를 사용합니다.

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

# 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

조직 전체의 모든 Agent Runtime 에이전트에 역할을 부여하려면 다음 안내를 따르세요.

# 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가 모두 표시됩니다.
에이전트가 자체 권한으로 작업할 때 로그에는 에이전트 ID만 표시됩니다.

에이전트 및 해당 ID 나열

콘솔 및 명령줄을 사용하여 Agent Runtime에서 에이전트 ID 목록을 볼 수 있습니다. Google Cloud

콘솔

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

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

REST API

REST API를 사용하여 Agent Runtime 인스턴스를 가져올 때 에이전트 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 Runtime 인스턴스의 경우 effectiveIdentity 필드에 Agent Runtime 인스턴스와 연결된 서비스 에이전트 또는 서비스 계정 이름이 포함됩니다.

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

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

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

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

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

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

다음 단계

가이드

배포된 에이전트 관리

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

가이드

에이전트 사용

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