Menggunakan identitas agen IAM

Menggunakan identitas agen di Agent Runtime memberikan identitas per agen yang aman yang memungkinkan pendekatan hak istimewa terendah untuk pengelolaan akses. Dokumen ini menjelaskan cara membuat agen dengan identitas agen, mengizinkan akses keGoogle Cloud API, dan mengelola kredensial untuk layanan pihak ketiga.

Ringkasan

Identitas agen menyediakan identitas per agen yang memungkinkan pendekatan hak istimewa paling rendah dan terkait dengan siklus proses agen, sehingga identitas agen menjadi akun utama yang lebih aman daripada akun layanan. Kontrol pengelolaan akses yang ada melalui IAM mendukung identitas agen untuk memungkinkan tata kelola yang kuat.

Kredensial identitas agen diamankan secara default melalui kebijakan Akses Kontekstual (CAA) yang dikelola Google. Kebijakan ini menerapkan pengikatan mTLS untuk memastikan bahwa kredensial agen dalam bentuk token terikat sertifikat hanya dapat digunakan dari lingkungan runtime yang tepercaya dan ditujukan (misalnya, penampung Cloud Run). Dasar keamanan ini membuat kredensial yang dicuri tidak dapat diputar ulang, sehingga memberikan perlindungan terhadap Pencurian Kredensial dan Pengambilalihan Akun (ATO).

Halaman ini membahas beberapa topik berikut:

Membuat agen dengan identitas agen: Buat agen sehingga agen secara otomatis menerima identitas unik saat Anda men-deploy ke Agent Runtime.
Memberikan otorisasi akses ke API Google Cloud menggunakan identitas agen: Gunakan identitas agen yang disediakan untuk memberikan atau menolak akses agen ke alat, API, dan resource pihak pertama Google Cloud. Hal ini juga mencakup akses ke agen lain yang dihosting di Agent Runtime menggunakan Agent2Agent (A2A) Protocol.
Mencatat aktivitas agen: Melihat identitas agen dalam log di seluruh layanan Google Cloud . Untuk alur yang didelegasikan pengguna, log menampilkan identitas pengguna dan identitas agen.
Mencantumkan agen dan identitas agen: Melihat daftar agen Anda dan identitasnya di Agent Runtime.
Memilih tidak menggunakan Akses Kontekstual (tidak direkomendasikan): Memilih tidak menggunakan kebijakan Akses Kontekstual (CAA) default.

Batasan

Identitas agen tidak dapat diberi peran Bucket Lama (storage.legacyBucketReader, storage.legacyBucketWriter, atau storage.legacyBucketOwner) di bucket Cloud Storage.

Membuat agen dengan identitas agen

Anda dapat menyediakan agen yang di-deploy ke Agent Runtime dengan identitas unik saat membuat instance Agent Runtime. Identitas ini terkait dengan ID resource agen Agent Runtime dan tidak bergantung pada framework agen yang Anda gunakan untuk mengembangkan agen.

Anda memiliki opsi berikut saat membuat identitas agen:

Membuat instance Agent Runtime tanpa men-deploy kode agen: Jika ingin menyiapkan kebijakan IAM sebelum men-deploy agen, Anda dapat membuat identitas agen tanpa men-deploy kode agen. Untuk melakukannya, buat instance Agent Runtime hanya dengan kolom identity_type:
```
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}
)
```
Setelah membuat instance Agent Runtime dengan identitas agen, Anda dapat menambahkan kode agen menggunakan agent_engine.update(...).

Membuat instance Agent Runtime saat men-deploy kode agen: Jika Anda ingin menyediakan identitas agen saat men-deploy kode agen, gunakan Agent Platform SDK for Python dan tanda identity_type=AGENT_IDENTITY.

Tentukan agen dalam framework pilihan Anda:

from google.adk.agents import Agent

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

Kemudian, deploy:

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}")

dengan BUCKET_NAME adalah nama bucket Cloud Storage Anda.

Men-deploy agen menggunakan Agents CLI: Agents CLI sangat ideal untuk pembelajaran, pembuatan prototipe, dan pengujian cepat, karena menawarkan solusi deployment cepat dengan resource dasar untuk pemantauan. Perintah berikut akan men-deploy agen Anda:
```
agents-cli deploy --agent-identity
```
Men-deploy agen dengan Identitas Agen menggunakan deployment ADK: Siapkan agen Anda dengan ADK. Sebelum menjalankan adk deploy, jalankan perintah berikut di folder agen Anda untuk menambahkan file konfigurasi dengan identitas agen.
```
# 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
```

Instance Agent Runtime dibuat dengan identitas agen yang hanya dapat dibaca dan dibuktikan sistem (ID utama):

# 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

Bagian berikut disediakan secara otomatis untuk Anda sebagai bagian dari identitas agen:

TRUST_DOMAIN: Domain tepercaya disediakan untuk Anda saat Anda mengaktifkan Agent Platform API:
- Jika Anda memiliki organisasi, domain tepercaya dibuat di tingkat organisasi dengan format agents.global.org-ORGANIZATION_ID.system.id.goog.
- Jika project Anda tidak memiliki organisasi, domain tepercaya akan dibuat di tingkat project dengan format agents.global.project-PROJECT_NUMBER.system.id.goog.
NAMESPACE: Jalur resource agen yang tidak dapat diubah.
AGENT_NAME: agent-reasoning-engine-id yang tidak dapat diubah.

Identitas agen didasarkan pada SPIFFE. Kami juga menyediakan dan mengelola sertifikat x509 secara otomatis di agen dengan identitas yang sama untuk autentikasi yang aman. Secara default, agen mendapatkan akses ke pencatatan aktivitas, metrik, akses model, sesi, memori, dan sandbox-nya sendiri (Pratinjau).

Identitas agen dilengkapi dengan peran roles/aiplatform.agentContextEditor dan roles/aiplatform.agentDefaultAccess default sehingga agen memiliki izin dasar untuk beroperasi.

Anda dapat melihat identitas melalui konsol dan API Agent Runtime Google Cloud .

Mengakses Google Cloud API dan layanan menggunakan identitas agen

Setelah membuat agen dengan identitas agen, Anda dapat memberikan atau menolak akses agen ke Google Cloud API dan layanan menggunakan kebijakan IAM berikut:

Kebijakan izinkan: Memberikan akses agen ke Google Cloud resource.
Kebijakan penolakan: Menolak akses agen ke Google Cloud resource.

Memberikan akses ke agen

Berikan izin IAM ke identitas agen. Sebaiknya gunakan peran berikut:

roles/aiplatform.expressUser: Memberikan akses untuk menjalankan inferensi, sesi, dan memori.
roles/serviceusage.serviceUsageConsumer: Beri agen izin untuk menggunakan kuota project dan Agent Platform SDK.
roles/browser: Memberikan akses ke fungsi Google Cloud dasar.

Izin tambahan mungkin diperlukan jika Anda menggunakan logging, metrik, dan Cloud API Registry, serta untuk resource lain yang ingin Anda ekspos ke agen Anda. Lihat nanti untuk contoh lainnya.

Buat kebijakan izin IAM untuk memberi agen peran 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" \

Ganti kode berikut:

ORGANIZATION_ID: ID untuk organisasi Anda.
PROJECT_NUMBER: Nomor project Anda.
LOCATION: Region Anda. Lihat region yang didukung untuk Runtime.
AGENT_ENGINE_ID: ID resource instance Agent Runtime Anda.
ROLE_NAME adalah nama peran yang ingin Anda berikan. Contoh, roles/vision.user. Untuk mengetahui daftar peran bawaan, lihat Memahami peran.

Setelah IAM dikonfigurasi, Kredensial Default Aplikasi Agent Platform SDK akan otomatis menggunakan identitas agen untuk melakukan autentikasi ke resourceGoogle Cloud .

Memberikan akses ke beberapa agen

Anda dapat memberikan peran IAM kepada semua agen Agent Runtime dalam project tertentu atau di seluruh organisasi.

Untuk memberikan peran kepada semua agen Agent Runtime dalam project, gunakan salah satu perintah berikut.

Jika project Anda adalah milik organisasi:

# 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"

Jika project Anda bukan milik organisasi:

# 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"

Memberikan izin umum seperti kuota, logging, atau akses ke model kepada semua agen dalam project dapat mempermudah deployment. Kemudian, berikan izin terbatas tertentu kepada masing-masing agen untuk izin yang lebih sensitif seperti akses ke data. Pemberian izin tersebut dapat dilakukan kapan saja setelah penggunaan pertama fitur identitas agen dalam organisasi atau project, sehingga dapat dilakukan sebelum deployment agen.

Misalnya, perintah berikut memberikan peran dasar kepada semua agen dalam sebuah project:

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

Untuk memberikan peran kepada semua agen Agent Runtime di seluruh organisasi:

# 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"

Menolak akses ke agen

Untuk menolak akses agen ke resource, Anda dapat menggunakan kebijakan penolakan IAM atau menyiapkan kebijakan batas akses utama.

Tolak akses agen ke resource tertentu menggunakan kebijakan penolakan 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"
      ]
    }
  }
]
}

Siapkan Batas Akses Akun Utama untuk membatasi resource yang dapat diakses agen, meskipun izin lain yang mungkin dimiliki agen:

// 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

Mencatat aktivitas agen

Jika mengaktifkan Cloud Logging, Anda dapat melihat log agen dan pengguna mana yang telah mengakses resource Google Cloud .

Saat agen bertindak atas nama pengguna, log akan menampilkan identitas agen dan pengguna.
Jika agen bertindak atas otoritasnya sendiri, log hanya akan menampilkan identitas agen.

Mencantumkan agen dan identitasnya

Anda dapat melihat daftar identitas agen di Agent Runtime menggunakan konsol Google Cloud dan command line.

Konsol

Di konsol Google Cloud , buka halaman Deployments Agent Platform.

Buka Deployment

Agen yang di-deploy yang merupakan bagian dari project yang dipilih akan muncul dalam daftar. Anda dapat menggunakan kolom Filter untuk memfilter daftar menurut kolom yang Anda tentukan.
Untuk setiap agen, identitas agen dicantumkan di kolom Identitas.

REST API

Anda dapat mengambil identitas agen saat mendapatkan instance Agent Runtime menggunakan REST API.

Respons mencakup identitas agen dalam format berikut:

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

Untuk instance Agent Runtime yang tidak menggunakan identitas agen, kolom effectiveIdentity berisi nama agen layanan atau akun layanan yang terkait dengan instance Agent Runtime.

Memilih tidak menggunakan Akses Kontekstual (CAA)

Secara default, upaya penggunaan token akses di luar runtime Agent Runtime yang dimaksudkan akan menghasilkan error berikut:

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

Untuk kasus-kasus tertentu, seperti persyaratan berbagi token tertentu di antara agen, Anda dapat memilih untuk tidak menggunakan kebijakan CAA default. Tindakan ini sangat tidak disarankan karena membuat agen rentan terhadap pencurian kredensial.

Batalkan keikutsertaan kebijakan Akses Kontekstual (CAA) default dengan menetapkan variabel lingkungan berikut saat Anda membuat instance Agent Runtime:

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

Langkah berikutnya

Panduan

Mengelola agen yang di-deploy

Pelajari cara mengelola agen yang telah di-deploy ke runtime terkelola Agent Platform.