Menggunakan identitas agen dengan Vertex AI Agent Engine

Halaman ini menjelaskan cara menggunakan identitas agen Identity Access Management (IAM) untuk menyediakan fitur keamanan dan pengelolaan akses saat menggunakan agen di Vertex AI Agent Engine Runtime.

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.

Halaman ini membahas beberapa topik berikut:

Batasan

Pertimbangkan batasan berikut saat Anda merencanakan project:

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

  • Sebaiknya gunakan identitas agen hanya di lingkungan pengujian.

Membuat agen dengan identitas agen

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

Anda memiliki opsi berikut saat membuat identitas agen:

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

  • Membuat instance Agent Engine saat men-deploy kode agen: Jika Anda ingin menyediakan identitas agen saat men-deploy kode agen, gunakan Vertex AI SDK untuk Python dan tanda identity_type=AGENT_IDENTITY:

    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(
      agent=app,
      config={
          "identity_type": types.IdentityType.AGENT_IDENTITY,
          "requirements": ["google-cloud-aiplatform[adk,agent_engines]"],
          "staging_bucket": f"gs://"BUCKET _NAME",
      },
)

    dengan BUCKET_NAME adalah nama bucket Cloud Storage Anda.

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

# 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 Vertex AI 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.

Anda dapat melihat identitas melalui konsol dan API Vertex AI Agent Engine Google Cloud .

Mengakses API dan layanan menggunakan identitas agen Google Cloud

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

  • 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 Vertex AI SDK.

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 Vertex AI Agent Engine.

  • AGENT_ENGINE_ID: ID resource instance Agent Engine 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 Google Cloud SDK akan otomatis menggunakan identitas agen untuk melakukan autentikasi ke resourceGoogle Cloud .

Menolak akses ke agen

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

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

Mengakses layanan pihak ketiga menggunakan otorisasi yang didelegasikan menggunakan OAuth

Identitas agen dapat memungkinkan agen mengakses layanan pihak ketiga atas nama Anda dengan mengintegrasikan Secret Manager.

Untuk menyiapkan integrasi dengan Secret Manager, Anda harus menyimpan terlebih dahulu kredensial tambahan (ID Klien atau Secret Klien) untuk mengakses layanan pihak ketiga ke Secret Manager (di project konsumen tempat siklus proses agen dikelola) menggunakan langkah-langkah berikut:

  1. Buat penampung baru di Secret Manager.

  2. Dapatkan ID Klien atau Rahasia Klien dari penyedia aplikasi pihak ketiga.

  3. Tambahkan ID Klien atau Rahasia Klien ke Secret Manager.

  4. Membatasi akses ke kredensial ini berdasarkan ID Agen (ID utama):

    # Create the secret container
gcloud secrets create my-app-oauth-secret

# Add the actual client secret to Secret Manager
gcloud secrets versions add my-app-oauth-secret "gcp-client-secret-1a2b3c4d"

# Grant agent identity access to the secret
gcloud secrets add-iam-policy-binding my-app-oauth-secret \
--role='roles/secretmanager.secretAccessor' \
--member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID" \

Setelah rahasia disimpan, agen dapat mengakses kredensial ini selama runtime menggunakan ID utama dan library autentikasi Google Cloud standar secara otomatis sebagai bagian dari Kredensial Default Aplikasi.

# Example: Use agent identity to retrieve third party credentials from Secret Manager
# Use case: Using an agent, the user is trying to post a message on Slack,
# The developer first retrieves secret from Secret Manager using agent identity,
# and then uses it to login to Slack and post a message.

from google.cloud import secretmanager

def access_secret(project_id: str, secret_id: str, version_id: str = "latest") -> str:

      # Application default credential automatically gets token from MDS using agent identity
      agent_identity_credentials = default()

       # Create the Secret Manager client.
       client = secretmanager.SecretManagerServiceClient(credentials=agent_identity_credentials)

       # Build the resource name of the secret version.
       name = f"projects/{project_id}/secrets/{secret_id}/versions/{version_id}"

       # Access the secret version.
       response = client.access_secret_version(request={"name": name})

       # Decode the payload to get the secret string.
       secret_value = response.payload.data.decode("UTF-8")
       return secret_value

Dengan client ID dan rahasia klien, Anda kini dapat membuat alat dan mengonfigurasi autentikasi berbasis OAuth.

Contoh berikut menggunakan agen yang dikembangkan oleh Agent Development Kit (ADK). Autentikasi berbasis OAuth digabungkan ke dalam metode authenticationScheme dan authCredential sebagai bagian dari konstruksi alat:

import os

from google.adk.auth.auth_schemes import OpenIdConnectWithConfig
from google.adk.auth.auth_credential import AuthCredential, AuthCredentialTypes, OAuth2Auth
from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset
from google.adk.agents.llm_agent import LlmAgent

auth_scheme = OpenIdConnectWithConfig(
   authorization_endpoint="https://your-endpoint.slack.com/oauth2/v1/authorize",
   token_endpoint="https://your-token-endpoint.slack.com/oauth2/v1/token",
   scopes=['openid', 'profile', "email"]
)

auth_credential = AuthCredential(
 auth_type=AuthCredentialTypes.OPEN_ID_CONNECT,
 oauth2=OAuth2Auth(
   client_id=access_secret(project_id: 'foo', secret_id: 'slack_oauth_client_id'),
   client_secret=access_secret(project_id: 'foo', secret_id: 'slack_oauth_client_secret'),
 )
)

# --- Slack Toolset Configuration Based On OpenAPI Specification ---

with open(os.path.join(os.path.dirname(__file__), 'spec.yaml'), 'r') as f:
   spec_content = f.read()

slack_toolset = OpenAPIToolset(
  spec_str=spec_content,
  spec_str_type='yaml',

  # ** Crucially, associate the authentication scheme and credentials with these tools. **
  # This tells the ADK that the tools require the defined OIDC/OAuth2 flow.
  auth_scheme=auth_scheme,
  auth_credential=auth_credential,
)

# Configure and create the main LLM Agent.

root_agent = LlmAgent(
   model='gemini-2.0-flash',
   name='enterprise_assistant',
   instruction='Help user integrate with Slack and post messages to Slack.',
   tools=userinfo_toolset.get_tools(),
)

Selama runtime, hal berikut akan terjadi (jika Anda menggunakan ADK secara lokal melalui web ADK, langkah-langkahnya akan otomatis di dalam web ADK dan backend ADK):

  1. Anda mengakses agen, dan agen memutuskan bahwa agen perlu memanggil alat (misalnya, Slack).

  2. Alat yang diprogram di dalam ADK (dengan auth_scheme dan auth_credential) menampilkan objek authConfig ke frontend (yang mencakup URI pengalihan dan ID klien).

  3. Frontend mengurai objek authConfig, dan Anda akan dialihkan ke halaman otorisasi pihak ketiga. Setelah login, Anda akan dialihkan ke frontend agen, dan kode otorisasi akan dikirim ke backend ADK.

  4. Backend menggunakan kode otorisasi untuk mendapatkan token akses bagi layanan pihak ketiga dan terus menjalankan alat.

Jika Anda men-deploy agen ADK ke Vertex AI Agent Engine Runtime, Anda perlu membangun frontend kustom dan memigrasikan kode autentikasi atau pengalihan ADK-web ke frontend Anda untuk melakukan integrasi OAuth yang sama.

Mengakses layanan pihak ketiga menggunakan kunci API

Identitas agen memungkinkan agen mengakses layanan pihak ketiga dan bertindak atas nama Anda menggunakan kunci API. Pertama-tama, Anda perlu menyimpan Kunci API untuk akses ke layanan pihak ketiga ke Secret Manager, lalu mengambil kredensial ini dari Secret Manager.

from google.adk.tools.openapi_tool.auth.auth_helpers import token_to_scheme_credential
from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset

WEATHER_DOT_COM_API_KEY = access_secret(project_id: 'foo', secret_id: 'weather_dot_com_api_key')

auth_scheme, auth_credential = token_to_scheme_credential(
   "apikey", "query", "apikey", WEATHER_DOT_COM_API_KEY
)

sample_api_toolset = OpenAPIToolset(
   spec_str="...",
   spec_str_type="yaml",
   auth_scheme=auth_scheme,
   auth_credential=auth_credential,
)

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 Vertex AI Agent Engine menggunakan konsol dan command line Google Cloud .

Konsol

  1. Di konsol Google Cloud , buka halaman Vertex AI Agent Engine.

    Buka Agent Engine

    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 tercantum di kolom Identitas.

REST API

Anda dapat mengambil identitas agen saat mendapatkan instance Agent Engine 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 Engine yang tidak menggunakan identitas agen, kolom effectiveIdentity berisi nama agen layanan atau akun layanan yang terkait dengan instance Agent Engine.

Langkah berikutnya