Membagikan agen

Halaman ini menjelaskan cara membagikan satu agen di project Anda dengan memberikan izin Identity and Access Management kepada pengguna atau akun layanan.

Untuk membagikan agen, Anda memberikan izin aiplatform.reasoningEngines.query pada resource agen tertentu.

Kapan harus membagikan agen

Dengan membagikan agen, beberapa pengguna atau sistem otomatis dapat membuat kueri agen. Skenario umum untuk membagikan agen mencakup hal berikut:

  • Kolaborasi: Bagikan agen dengan anggota tim atau organisasi Anda lainnya untuk menggunakannya dalam tugas mereka.
  • Integrasi aplikasi: Berikan akses ke akun layanan sehingga aplikasi kustom, seperti chatbot internal atau portal dukungan pelanggan, dapat memanggil agen untuk menangani permintaan pengguna tertentu.
  • Komunikasi antar-agen: Dalam sistem multi-agen, satu agen mungkin perlu memanggil agen lain untuk mendapatkan informasi atau mendelegasikan sub-tugas.
  • Akses informasi: Berikan pengguna akses terkontrol ke data melalui antarmuka percakapan tanpa memberi mereka akses langsung ke sumber data yang mendasarinya. Misalnya, bagikan agen yang terhubung ke basis pengetahuan (seperti kebijakan SDM atau dokumentasi teknis) kepada semua karyawan.

Sebelum memulai

  1. Identifikasi agen yang ingin Anda bagikan. Anda memerlukan project ID dan ID mesin penalaran agen.
  2. Identifikasi pengguna atau akun layanan yang ingin Anda beri akses.

Langkah 1: Buat peran khusus

Untuk mengikuti prinsip hak istimewa terendah, buat peran khusus yang hanya berisi izin aiplatform.reasoningEngines.query.

gcloud

Untuk membuat peran khusus di project, jalankan perintah berikut:

gcloud iam roles create ROLE_ID  --project=PROJECT_ID \
  --title="ROLE_TITLE" \
  --description="ROLE_DESCRIPTION" \
  --permissions=aiplatform.reasoningEngines.query

Atau, untuk membuat peran bagi seluruh organisasi:

gcloud iam roles create ROLE_ID --organization=ORGANIZATION_ID \
  --title="ROLE_TITLE" \
  --description="ROLE_DESCRIPTION" \
  --permissions=aiplatform.reasoningEngines.query

Ganti kode berikut:

  • ROLE_ID: ID peran, seperti agentUser.
  • ROLE_TITLE: Judul untuk peran, seperti Agent runtime user.
  • ROLE_DESCRIPTION: Deskripsi singkat tentang peran, seperti Allows querying agents.
  • PROJECT_ID: ID project.
  • ORGANIZATION_ID: ID organisasi.

Terraform

Untuk membuat peran khusus menggunakan Terraform, gunakan resource google_project_iam_custom_role:

resource "google_project_iam_custom_role" "reasoning_engine_query" {
role_id     = "ROLE_ID"
title       = "ROLE_TITLE"
project     = "PROJECT_ID"
permissions = ["aiplatform.reasoningEngines.query"]
}

Ganti kode berikut:

  • ROLE_ID: ID peran, seperti agentUser.
  • ROLE_TITLE: Judul untuk peran, seperti Agent runtime user.
  • PROJECT_ID: project ID.

Nama peran khusus akan menjadi projects/PROJECT_ID/roles/ROLE_ID atau organizations/ORGANIZATION_ID/roles/ROLE_ID.

Langkah 2: Berikan peran pada agen

Setelah peran dibuat, ikat peran ke agen dan tentukan pengguna atau akun layanan yang akan diberi izin.

Python

Untuk memberikan peran menggunakan Python, gunakan library google-cloud-aiplatform:

from google.cloud.aiplatform_v1 import ReasoningEngineServiceClient
from google.api_core.client_options import ClientOptions

# Initialize the client
client = ReasoningEngineServiceClient(
  client_options=ClientOptions(api_endpoint="LOCATION-aiplatform.googleapis.com")
)

# Define the resource path
resource = "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID"

# Get the current IAM policy and add the new binding
policy = client.get_iam_policy(request={"resource": resource})
binding = policy.bindings.add()
binding.role = "projects/PROJECT_ID/roles/ROLE_ID"
binding.members.append("USER_OR_SA")

# Update the IAM policy on the resource
client.set_iam_policy(request={"resource": resource, "policy": policy})

Ganti kode berikut:

  • LOCATION: Region tempat agen di-deploy, seperti us-central1.
  • PROJECT_ID: project ID.
  • REASONING_ENGINE_ID: ID mesin penalaran agen.
  • ROLE_ID: ID peran, seperti agentUser.
  • USER_OR_SA: Email pengguna atau akun layanan, seperti user:someone@example.com atau serviceAccount:my-sa@my-project.iam.gserviceaccount.com.

Terraform

Untuk memberikan peran menggunakan Terraform, gunakan resource google_vertex_ai_reasoning_engine_iam_member:

resource "google_vertex_ai_reasoning_engine_iam_member" "example" {
project          = "PROJECT_ID"
region           = "REGION"
reasoning_engine = google_vertex_ai_reasoning_engine.my_engine.name
role             = google_project_iam_custom_role.reasoning_engine_query.name
member           = "USER_OR_SA"
}

Ganti kode berikut:

  • PROJECT_ID: project ID.
  • REGION: Region.
  • USER_OR_SA: Pengguna atau akun layanan.

Pertimbangan keamanan

Memberikan akses ke agen akan memberikan akses langsung untuk mengirim pesan ke endpoint FastAPI agen. Jaminan keamanan ditentukan oleh kode agen penerima.

  • Frontend tepercaya: Sebagian besar agen ADK default beroperasi dari frontend tepercaya. Agen mempercayai perintah frontend, yang memberi frontend kontrol penuh atas sesi dan pengguna. Dalam kasus ini, jangan berikan akses langsung ke agen kepada entity yang tidak tepercaya.
  • Agen A2A: Agen lain, seperti agen Agent2Agent (A2A), dapat diekspos ke entity yang tidak tepercaya jika mereka menerapkan autentikasi dan otorisasi sendiri. Runtime agen hanya menyediakan kontrol akses kasar ke antarmuka agen.