Mengautentikasi menggunakan otoritas agen itu sendiri

Agen dapat mengakses Google Cloud API dan resource lainnya menggunakan otoritasnya sendiri. Sebaiknya gunakan metode ini untuk agen yang dihosting di Google Cloud untuk berinteraksi dengan layanan Google Cloud lainnya.

Saat bertindak atas otoritasnya sendiri, agen menggunakan identitas SPIFFE utamanya untuk meminta token akses. Google Cloud

Sebelum memulai

Verifikasi bahwa Anda telah memilih metode autentikasi yang benar.
Buat dan deploy agen dengan Identitas Agen diaktifkan.
Pastikan Anda memiliki peran yang diperlukan untuk menyelesaikan tugas ini.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk memberikan akses agen ke Google Cloud layanan, minta administrator untuk memberi Anda peran IAM berikut pada resource target:

Untuk memberikan akses ke agen:
- Project IAM Admin (roles/resourcemanager.projectIamAdmin)
- Security Admin (roles/iam.securityAdmin)
Peran yang direkomendasikan untuk identitas agen:
- Agent Context Editor (roles/aiplatform.agentContextEditor)
- Akses Default Agen (roles/aiplatform.agentDefaultAccess)
- Vertex AI User (roles/aiplatform.user)
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
- Browser (roles/browser)
- Storage Object Viewer (roles/storage.objectViewer)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Memberikan akses ke agen

Agar agen Anda dapat mengakses layanan Google Cloud , Anda harus memberikan peran yang diperlukan pada identitas agen di resource target.

Dalam kebijakan izin IAM, identitas agen menggunakan ID akun utama.

Untuk memberikan akses agen ke resource, gunakan konsol Google Cloud atau gcloud CLI.

Konsol

Di konsol Google Cloud , buka halaman IAM untuk resource yang ingin Anda beri akses.
- Untuk project, buka halaman IAM:
  Buka halaman IAM
- Untuk resource lainnya, buka halaman resource tersebut, lalu klik tab Permissions atau IAM.
Klik Berikan Akses.
Di kolom New principals, masukkan ID akun utama yang cocok dengan tingkat akses yang ingin Anda berikan:
- Satu agen: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
- Semua agen dalam project: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
- Semua agen dalam organisasi: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
Di kolom Select a role, telusuri dan pilih peran yang ingin Anda berikan.
Klik Simpan.

Google Cloud CLI

Untuk memberikan akses agen ke resource, jalankan perintah berikut:

gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

Ganti kode berikut:

SERVICE: Layanan Google Cloud (misalnya, storage atau bigquery).
RESOURCE_NAME: Nama resource (misalnya, nama bucket atau ID set data).
PRINCIPAL_IDENTIFIER: ID akun utama yang cocok dengan tingkat akses yang ingin Anda berikan:
- Satu agen: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
- Semua agen dalam project: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
- Semua agen dalam organisasi: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
ORGANIZATION_ID: ID Google Cloud organisasi Anda.
PROJECT_NUMBER: Nomor project Google Cloud Anda.
LOCATION: Lokasi agen Anda (misalnya, us-central1). (Hanya diperlukan untuk akses agen tunggal.)
ENGINE_ID: ID mesin penalaran Anda. (Hanya diperlukan untuk akses agen tunggal.)
ROLE: Peran IAM yang ingin Anda berikan.

Merujuk identitas agen dalam kode Anda

Library klien Google Cloud secara otomatis menggunakan Identitas Agen saat agen Anda di-deploy ke lingkungan yang didukung Google Cloud .

Cuplikan Python berikut menunjukkan cara menggunakan kredensial Identitas Agen secara manual untuk memanggil Cloud Vision API menggunakan Agent Development Kit (ADK).

from google.cloud import vision
from google.auth import default
from google.adk.tools import tool

@tool
def analyze_image_from_gcs(gcs_uri: str) -> dict:
    # Application default credentials automatically retrieve the
    # Agent Identity token from the metadata server.
    agent_identity_credentials, project_id = default()

    client = vision.ImageAnnotatorClient(
        credentials=agent_identity_credentials,
        project=project_id
    )

    # Prepare the image object with the Cloud Storage URI.
    image = vision.Image()
    image.source.image_uri = gcs_uri

    # Perform label detection on the image.
    response = client.label_detection(image=image)

    # Check for any errors returned by the API.
    if response.error.message:
        return {"status": "failure", "error_message": response.error.message}

    labels = response.label_annotations
    return {"status": "success", "labels": [label.description for label in labels]}

Opsional: Memilih tidak menggunakan Akses Kontekstual

Kebijakan Akses Kontekstual yang dikelola Google secara default membantu mengamankan kredensial Identitas Agen. Selain Agent Gateway, kebijakan ini menerapkan Bukti Kepemilikan yang Dapat Ditunjukkan (DPoP) dengan mengautentikasi token akses agen. Kebijakan ini juga memastikan bahwa mTLS digunakan untuk mengakses Agent Gateway. Hal ini memastikan bahwa token yang terikat dengan sertifikat hanya dapat digunakan dari lingkungan runtime yang tepercaya dan ditujukan (misalnya, container Cloud Run). Dasar keamanan ini membuat kredensial yang dicuri tidak dapat diputar ulang, sehingga membantu melindungi dari pencurian kredensial dan pengambilalihan akun (ATO).

Dalam kasus yang jarang terjadi, seperti persyaratan berbagi token tertentu di antara agen, jika Anda perlu menyuntikkan token langsung di header, atau jika agen Anda tidak dapat mengautentikasi dengan error 401 UNAUTHENTICATED, Anda dapat memilih untuk tidak menggunakan kebijakan Akses Kontekstual default. Memilih untuk tidak menggunakan token binding akan menghilangkan perlindungan token binding, sehingga membuat token akses sementara ini rentan terhadap pencurian atau serangan replay. Oleh karena itu, tidak disarankan untuk memilih tidak ikut.

Untuk memilih tidak ikut, tetapkan variabel lingkungan berikut saat Anda men-deploy agen:

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

Men-deploy agen

Saat men-deploy agen Anda ke Google Cloud, pastikan Identitas Agen diaktifkan. Jika Anda men-deploy ke Agent Runtime, gunakan flag identity_type=AGENT_IDENTITY:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Vertex AI 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 (e.g., AdkApp)
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)