Menggunakan Identitas Agen dengan Runtime Agen

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

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:

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-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 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-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 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 memberikan roles/secretmanager.secretAccessor ke 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, projects atau organizations).

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

  1. Buat peran khusus agentInvoker dengan izin yang diperlukan:

    gcloud iam roles create agentInvoker --project=PROJECT_ID \
      --permissions=aiplatform.reasoningEngines.query,aiplatform.reasoningEngines.get \
      --stage=GA
    
  2. Ikat 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"
    
  3. 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.effectiveIdentity dari 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 gcloud menggunakan 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_engine yang 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 principalSets cakupan project untuk izin dasar pengukuran: Karena binding principalSet menargetkan 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) ke principalSet seluruh project, bukan ke entitas agen individual. Batasi binding principal:// 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

  1. Di konsol Google Cloud , buka halaman Deployments Agent Platform.

    Buka Deployment

    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.

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

Panduan

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

Panduan

Menggunakan agen dengan Agent Platform Runtime.