Ringkasan
Identitas agen memberikan identitas per agen yang memungkinkan pendekatan hak istimewa terendah dan terkait dengan siklus proses agen, sehingga menjadikan identitas agen sebagai entitas keamanan 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 binding mTLS untuk memastikan bahwa kredensial agen dalam bentuk token terikat sertifikat hanya dapat digunakan dari lingkungan runtime tepercaya yang dimaksudkan (misalnya, container Cloud Run). Dengan dasar pengukuran keamanan ini, kredensial yang dicuri tidak dapat diputar ulang, sehingga melindungi dari Pencurian Kredensial dan Pengambilalihan Akun (ATO).
Halaman ini membahas beberapa topik berikut:
Membuat agen dengan identitas agen: Buat agen sedemikian rupa sehingga agen otomatis menerima identitas unik saat Anda men-deploy ke Agent Runtime.
Mengizinkan 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 Protokol Agent2Agent (A2A).
Mencatat aktivitas agen ke dalam log: Melihat identitas agen di 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 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 agentplatform from agentplatform import types client = agentplatform.Client( project=PROJECT_ID, location=LOCATION, http_options=dict(api_version="v1beta1") ) remote_app = client.runtimes.create( config={ "display_name": "identity-for-agent", "identity_type": types.IdentityType.AGENT_IDENTITY, }, )Setelah membuat instance Agent Runtime dengan identitas agen, Anda dapat menambahkan kode agen menggunakan
client.runtimes.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 untuk Python dan flag
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 agentplatform from agentplatform import types from agentplatform.frameworks import AdkApp # Initialize the Agent Platform client with v1beta1 API for agent identity support client = agentplatform.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.runtimes.create( agent=app, config={ "display_name": "running-agent-with-identity", "identity_type": types.IdentityType.AGENT_IDENTITY, "requirements": ["google-cloud-agentplatform[adk,runtimes]"], "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 ideal untuk pelajar, pembuatan prototipe, dan pengujian cepat, karena menawarkan solusi deployment cepat dengan resource dasar untuk pemantauan. Perintah berikut men-deploy agen Anda:
agents-cli deploy --agent-identityMen-deploy agen dengan Identitas Agen menggunakan ADK deploy: 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 diuji sistem dan hanya baca (ID akun 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 kepercayaan disediakan untuk Anda saat Anda mengaktifkan Agent Platform API:
Jika Anda memiliki organisasi, domain kepercayaan akan dibuat di tingkat organisasi dengan format
agents.global.org-ORGANIZATION_ID.system.id.goog.Jika project Anda tidak memiliki organisasi, domain kepercayaan akan dibuat di level project dengan format
agents.global.proj-PROJECT_NUMBER.system.id.goog.
NAMESPACE: Jalur resource agen yang tidak dapat diubah.
AGENT_NAME:
agent-reasoning-engine-idyang 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 logging, 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 API dan layanan Google Cloud menggunakan kebijakan IAM berikut:
Kebijakan izin: Memberikan akses kepada agen ke resource Google Cloud .
Kebijakan penolakan: Menolak akses agen ke resource Google Cloud .
Memberikan akses ke agen
Memberikan izin IAM ke identitas agen.
Sebaiknya gunakan peran berikut:
roles/serviceusage.serviceUsageConsumer: Memberikan izin kepada agen untuk menggunakan kuota project dan Agent Platform SDK.roles/browser: Memberikan akses ke fungsi Google Cloud dasar.roles/secretmanager.secretAccessor: Memberikan akses kepada agen ke secret di Secret Manager. Jika Anda mereferensikan secret sebagai variabel lingkungan, Anda juga harus memberikanroles/secretmanager.secretAccessorke Agen Layanan Agent Platform (service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) agar dapat mengambil nilai secret selama deployment.
Izin tambahan mungkin diperlukan jika Anda menggunakan logging, metrik, dan registry Cloud API, serta untuk resource lain yang ingin Anda ekspos ke agen. Lihat bagian selanjutnya untuk contoh lainnya.
Buat kebijakan izin IAM untuk memberikan peran IAM kepada agen:
# 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:
RESOURCE_TYPE: Jenis resource (misalnya,
projectsatauorganizations).RESOURCE_ID: ID resource yang ingin Anda beri akses.
ORGANIZATION_ID: ID untuk organisasi Anda.
PROJECT_NUMBER: Nomor project Anda.
LOCATION: Region Anda. Lihat wilayah 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 untuk delegasi Agent-to-Agent (A2A)
Saat Anda mendesain sistem multi-agen tempat agen induk memanggil sub-agen jarak jauh yang terdaftar di Agent Registry, identitas agen induk harus memiliki izin untuk menemukan sub-agen di Agent Registry dan untuk memanggil endpoint-nya.
Untuk memastikan bahwa identitas agen induk memiliki izin yang diperlukan untuk menemukan dan memanggil sub-agen jarak jauh, minta administrator untuk memberikan peran IAM berikut kepada identitas agen induk:
-
Mengizinkan agen induk mencari endpoint sub-agen saat runtime:
Agent Registry API Viewer (
roles/agentregistry.viewer) di project induk atau resource registry -
Izinkan agen induk mengirim pesan ke sub-agen:
Agent Platform User (
roles/aiplatform.user) pada resource mesin penalaran sub-agen target
Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.
Administrator Anda mungkin juga dapat memberikan izin yang diperlukan kepada identitas agen induk melalui peran khusus atau peran bawaan lainnya.
Misalnya, untuk memberikan peran roles/agentregistry.viewer pada project, Anda dapat menggunakan perintah Google Cloud CLI berikut:
gcloud projects add-iam-policy-binding PROJECT_NUMBER \
--member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/PARENT_AGENT_ENGINE_ID" \
--role="roles/agentregistry.viewer"
Ganti kode berikut:
ORGANIZATION_ID: ID untuk organisasi Anda.PROJECT_NUMBER: Nomor project Anda.LOCATION: Region tempat agen induk Anda di-deploy.PARENT_AGENT_ENGINE_ID: ID resource instance Agent Runtime agen induk Anda.
Memberikan akses ke beberapa agen
Anda dapat memberikan peran IAM ke semua agen Agent Runtime dalam project tertentu atau di seluruh organisasi.
Untuk memberikan peran ke semua agen Agent Runtime dalam sebuah project, gunakan salah satu perintah berikut.
Jika project Anda 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.proj-PROJECT_NUMBER.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER" \
--role="ROLE_NAME"
Akan lebih mudah untuk memberikan izin umum seperti kuota, logging, atau akses ke model untuk semua agen dalam project guna menyederhanakan deployment. Kemudian, berikan izin khusus yang terbatas 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/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 ke 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"
Memberikan akses untuk panggilan agen ke agen (A2A)
Jika agen (Agen A) perlu memanggil agen lain (Agen B), jangan berikan izin di seluruh project. Sebagai gantinya, berikan peran khusus yang hanya berisi aiplatform.reasoningEngines.query dan aiplatform.reasoningEngines.get, yang terikat ke jalur resource Agen B.
Buat peran khusus
agentInvokerdengan izin yang diperlukan:gcloud iam roles create agentInvoker --project=PROJECT_ID \ --permissions=aiplatform.reasoningEngines.query,aiplatform.reasoningEngines.get \ --stage=GAIkat peran khusus ke resource Agen B untuk memberikan akses ke identitas Agen A:
gcloud beta ai reasoning-engines add-iam-policy-binding AGENT_B_ID \ --region=LOCATION \ --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_A_ID" \ --role="projects/PROJECT_ID/roles/agentInvoker"Untuk mencegah identitas agen melakukan operasi pengelolaan sensitif pada agen lain, buat kebijakan penolakan IAM untuk
reasoningEngines.create,.delete, dan.update:deniedPrincipals: - principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/* deniedPermissions: - aiplatform.googleapis.com/reasoningEngines.create - aiplatform.googleapis.com/reasoningEngines.delete - aiplatform.googleapis.com/reasoningEngines.update
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 principal access boundary untuk membatasi resource yang dapat diakses agen, terlepas dari 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
Panduan CI/CD dan otomatisasi
Pipeline deployment otomatis yang menghapus dan membuat ulang agen (seperti blue-green deployment, lingkungan pengujian sementara, atau alur kerja Terraform) dapat mengalami kehilangan akses runtime secara senyap. Karena setiap deployment ulang membuat resource reasoningEngines baru dengan ID unik, agen akan menerima ID akun utama baru. Izin IAM sebelumnya yang diberikan kepada akun utama sebelumnya tidak diwarisi oleh akun utama baru.
Untuk mengelola izin di pipeline otomatis, gunakan strategi berikut:
Mengambil ID akun utama baru secara dinamis: Ambil nilai
spec.effectiveIdentitydari respons deployment, atau buat kueri REST API setelah deployment untuk mendapatkan identitas aktif agen. Terapkan binding IAM yang diperlukan ke akun utama baru ini sebagai langkah pasca-deployment.Misalnya, Anda dapat mengkueri identitas aktif dengan
gcloudmenggunakan perintah berikut:gcloud ai reasoning-engines describe RESOURCE_ID \ --project=PROJECT_ID \ --location=LOCATION \ --format="value(spec.effectiveIdentity)"Di Terraform, Anda dapat membuat akun utama identitas agen secara dinamis dari ID resource
google_vertex_ai_reasoning_engineyang di-deploy dan mereferensikannya dalam binding IAM:resource "google_vertex_ai_reasoning_engine" "reasoning_engine" { provider = google-beta project = var.project_id region = var.region display_name = var.display_name description = var.agent_description spec { agent_framework = "google-adk" identity_type = "AGENT_IDENTITY" source_code_spec { inline_source { source_archive = filebase64(data.archive_file.agent_tarball.output_path) } python_spec { entrypoint_module = var.agent_python_spec.entrypoint_module entrypoint_object = var.agent_python_spec.entrypoint_object requirements_file = var.agent_python_spec.requirements_path version = var.agent_python_spec.version } } deployment_spec { env { name = "GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY" value = "true" } env { name = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT" value = "true" } } } } locals { agent_resource_id = element(split("/", google_vertex_ai_reasoning_engine.reasoning_engine.id), -1) agent_identity_principal = "principal://agents.global.org-${data.google_organization.org.org_id}.system.id.goog/resources/aiplatform/projects/${data.google_project.project.number}/locations/${var.region}/reasoningEngines/${local.agent_resource_id}" }Gunakan
principalSetscakupan project untuk izin dasar pengukuran: Karena bindingprincipalSetmenargetkan semua agen dalam project, binding tersebut akan tetap ada meskipun agen dihapus dan dibuat ulang. Berikan peran umum yang tidak sensitif (seperti penggunaan layanan, logging, dan inferensi model umum) keprincipalSetseluruh project, bukan ke entitas agen individual. Batasi bindingprincipal://individual ke sumber data yang sangat sensitif.
Mencatat aktivitas agen ke dalam log
Jika mengaktifkan Cloud Logging, Anda dapat melihat log yang menunjukkan agen dan pengguna yang telah mengakses resource Google Cloud .
Saat agen bertindak atas nama pengguna, log akan menampilkan identitas agen dan pengguna.
Saat agen bertindak atas otoritasnya sendiri, log hanya menampilkan identitas agen.
Mencantumkan agen dan identitasnya
Anda dapat melihat daftar identitas agen di Agent Runtime menggunakan konsol dan command line Google Cloud .
Konsol
- Di konsol Google Cloud , buka halaman Deployments Agent Platform.
Agen yang di-deploy dan merupakan bagian dari project yang dipilih akan muncul dalam daftar. Anda dapat menggunakan kolom Filter untuk memfilter daftar menurut kolom yang ditentukan.
Untuk setiap agen, identitas agen tercantum di kolom Identity.
REST API
Anda dapat mengambil identitas agen saat mendapatkan instance Agent Runtime menggunakan REST API.
Responsnya 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 untuk menggunakan token akses di luar runtime Agent Runtime yang dimaksud akan menghasilkan error berikut:
Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"
Untuk kasus khusus, 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.
Tolak 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
Mengelola agen yang di-deploy
Pelajari cara mengelola agen yang telah di-deploy ke runtime terkelola Agent Platform.