Menggunakan Identitas Agen dengan Runtime Agen

Penggunaan identitas agen di Agent Runtime menyediakan identitas per agen yang aman dan memungkinkan pendekatan hak istimewa terendah untuk pengelolaan akses. Dokumen ini menjelaskan cara membuat agen dengan identitas agen, mengotorisasi akses ke Google Cloud API, dan mengelola kredensial untuk layanan pihak ketiga.

Ringkasan

Identitas agen menyediakan identitas per agen yang memungkinkan pendekatan hak istimewa terendah dan terikat 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 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). Baseline keamanan ini membuat 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 sehingga agen secara otomatis menerima identitas unik saat Anda men-deploy ke Agent Runtime.

• Mengotorisasi akses ke Google Cloud API menggunakan identitas agen: Gunakan identitas agen yang disediakan untuk memberikan atau menolak akses agen ke Google Cloud's alat, API, dan resource pihak pertama. Hal ini juga mencakup akses ke agen lain yang dihosting di Agent Runtime menggunakan Protokol Agent2Agent (A2A).

• Mencatat aktivitas agen: Lihat identitas agen dalam log di seluruh Google Cloud layanan. Untuk alur yang didelegasikan pengguna, log akan menampilkan identitas pengguna dan identitas agen.

• Mencantumkan agen dan identitas agen: Lihat daftar agen Anda dan identitasnya di Agent Runtime.

• Menonaktifkan Akses Kontekstual (tidak direkomendasikan): Menonaktifkan kebijakan Akses Kontekstual (CAA) default.

Batasan

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

Membuat agen dengan identitas agen

Anda dapat menyediakan agen yang Anda deploy ke Agent Runtime dengan identitas unik saat membuat instance Agent Runtime. Identitas ini terikat dengan ID resource agen Agent Runtime dan independen dari 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={
      "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 agent_engine.update(...).

• Membuat instance Agent Runtime saat men-deploy kode agen: Jika 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 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 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-identity
  

• Men-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 hanya baca dan diuji sistem (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 otomatis untuk Anda sebagai bagian dari identitas agen:

• TRUST_DOMAIN: Domain tepercaya disediakan untuk Anda saat mengaktifkan Agent Platform API:

  • Jika Anda memiliki organisasi, domain tepercaya akan 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: Yang tidak dapat diubah agent-reasoning-engine-id.

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 (Pratinjau) miliknya sendiri.

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 .

Catatan: Jika flag identitas tidak dikonfigurasi, instance Agent Runtime akan terus menggunakan akun layanan. Hal ini memastikan kompatibilitas mundur jika Anda telah menerapkan deployment berbasis Infrastructure-as-Code di agen Anda.

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 izin: 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. Kami merekomendasikan peran berikut:

• roles/aiplatform.expressUser: Memberikan akses untuk menjalankan inferensi, sesi, dan memori.

• roles/serviceusage.serviceUsageConsumer: Memberikan izin agen untuk menggunakan kuota project dan Agent Platform SDK.

• roles/browser: Memberikan akses ke fungsi dasar Google Cloud .

Izin tambahan mungkin diperlukan jika Anda menggunakan logging, metrik, dan registry Cloud API, serta untuk resource lain yang ingin Anda ekspos ke agen Anda. Lihat nanti 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:

• 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 Google Cloud resource.

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 termasuk dalam 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 tidak termasuk dalam 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"

Akan lebih mudah untuk memberikan izin umum seperti kuota, logging, atau akses ke model kepada semua agen dalam project untuk menyederhanakan deployment. Kemudian, berikan izin sempit tertentu kepada setiap 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 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 akun 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 agen mungkin memiliki izin lain:

  // 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 yang telah mengakses Google Cloud resource.

• Saat agen bertindak atas nama pengguna, log akan menampilkan identitas agen dan pengguna.

• Saat 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 Google Cloud konsol dan command line.

Konsol

1. Di Google Cloud konsol, buka halaman Deployment 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.

2. Untuk setiap agen, identitas agen akan tercantum di kolom Identity.

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.

Menonaktifkan Akses Kontekstual (CAA)

Secara default, upaya untuk menggunakan 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 ekstrem, seperti persyaratan berbagi token tertentu di antara agen, Anda dapat menonaktifkan kebijakan CAA default. Tindakan ini sangat tidak disarankan, karena membuat agen rentan terhadap pencurian kredensial.

Nonaktifkan 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.

Panduan

Menggunakan agen

Gunakan agen dengan Agent Platform Runtime.