Merutekan traffic Runtime Agen melalui Gateway Agen

Halaman ini menjelaskan cara merutekan traffic Agent Runtime melalui Agent Gateway. Agent Gateway adalah komponen jaringan dan keamanan pusat dari ekosistem Platform Agen Gemini Enterprise. Fitur ini menyediakan konektivitas yang aman dan diatur untuk semua interaksi agentic, baik yang terjadi antara pengguna dan agen, agen dan alat, atau antar-agen itu sendiri.

Sebelum memulai

  • Pastikan Anda memahami cara men-deploy agen di Agent Runtime.

  • Pelajari Agent Gateway. Anda dapat menggunakan Agent Gateway dalam mode Agent-to-Anywhere (keluar) untuk mengamankan dan mengatur semua komunikasi keluar dengan traffic keluar ke alat, model, API, dan agen lainnya. Anda menggunakan gateway dalam mode Client-to-Agent (masuk) untuk mengontrol klien mana yang dapat mengakses agen Anda. Gateway ini memungkinkan Anda memilih kebijakan IAP dan template Model Armor mana yang harus diterapkan ke interaksi ini.

  • Buat project pengujian khusus untuk mencoba alur kerja ini. Hindari penggunaan project yang juga ditujukan untuk beban kerja penting lainnya.

Batasan

  • Untuk project dan region tertentu, hanya boleh ada satu instance Agent-to-Anywhere (keluar) dan satu instance Client-to-Agent (masuk) dari Agent Gateway. Semua agen Agent Runtime dalam project dan region yang sama yang dikonfigurasi untuk menggunakan Agent Gateway harus menggunakan instance gateway tertentu ini.
  • Layanan Security Command Center Agent Engine Threat Detection tidak tersedia saat Agent Gateway diaktifkan untuk agen.
  • Anda tidak dapat melepaskan binding agen Runtime dari resource Agent Gateway. Karena alasan ini, pastikan Anda menggunakan project pengujian khusus.

Izin diperlukan

Anda harus memberikan izin kepada Agen Layanan Reasoning Engine untuk menggunakan resource Agent Gateway yang akan Anda buat.

  1. Buat akun layanan jika belum ada. Akun layanan Reasoning Engine biasanya dibuat secara otomatis saat Anda pertama kali menggunakan Reasoning Engine.

    gcloud beta services identity create --service=aiplatform.googleapis.com --project=AGENT_PROJECT_ID

    Ganti AGENT_PROJECT_ID dengan project ID project tempat Anda ingin men-deploy agen.

  2. Untuk menggunakan gateway, Anda memerlukan izin berikut:

    • networkservices.agentGateways.get
    • networkservices.agentGateways.use
    • networkservices.operations.get

    Buat peran kustom dengan semua izin ini, lalu berikan peran tersebut ke akun layanan Reasoning Engine.

    gcloud alpha iam roles create AGENT_GATEWAY_ROLE_ID \
  --project=AGENT_PROJECT_ID \
  --title="Custom Agent Gateway access role" \
  --description="Custom role for Agent Gateway" \
  --permissions="networkservices.operations.get,networkservices.agentGateways.get,networkservices.agentGateways.use"

    Ganti kode berikut:

    • AGENT_GATEWAY_ROLE_ID: ID untuk peran kustom.
    • AGENT_PROJECT_ID: Project ID project tempat Anda ingin men-deploy agen.

  3. Tetapkan peran ke akun layanan Agent Runtime.

    gcloud alpha projects add-iam-policy-binding AGENT_PROJECT_ID \
    --member="serviceAccount:service-AGENT_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com" \
    --role="projects/AGENT_PROJECT_ID/roles/AGENT_GATEWAY_ROLE_ID"

    Ganti kode berikut:

    • AGENT_PROJECT_ID: Project ID project tempat Anda ingin men-deploy agen.
    • AGENT_PROJECT_NUMBER: Nomor project project tempat Anda ingin men-deploy agen.
    • AGENT_GATEWAY_ROLE_ID: ID peran kustom yang Anda buat.

  4. Selain itu, jika Anda ingin menggunakan template Model Armor untuk otorisasi konten, Anda harus memberikan izin berikut kepada Agen Layanan Reasoning Engine dan akun layanan Agent Gateway:

    gcloud alpha projects add-iam-policy-binding AGENT_PROJECT_ID \
    --member=serviceAccount:service-AGENT_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud alpha projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-AGENT_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com \
    --role=roles/modelarmor.user
 gcloud alpha projects add-iam-policy-binding AGENT_PROJECT_ID \
     --member=serviceAccount:service-AGENT_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
     --role=roles/modelarmor.calloutUser
 gcloud alpha projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
     --member=serviceAccount:service-AGENT_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
     --role=roles/modelarmor.user

    Ganti kode berikut:

    • AGENT_PROJECT_ID: Project ID project tempat Anda ingin men-deploy agen.
    • AGENT_PROJECT_NUMBER: Nomor project project tempat Anda ingin men-deploy agen.
    • MODEL_ARMOR_PROJECT_ID: Project ID project tempat template Model Armor dibuat.

Merutekan traffic Agent Runtime melalui Agent Gateway

Untuk merutekan traffic Agent Runtime melalui Agent Gateway, lakukan langkah-langkah berikut:

  1. Buat resource Agent Gateway dan lampirkan kebijakan otorisasi sesuai kebutuhan. Anda dapat membuat gateway dalam mode Agent-to-Anywhere (keluar) atau mode Client-to-Agent (masuk). Perhatikan bahwa agen dan gateway harus dibuat dalam project dan region yang sama. Untuk mengetahui petunjuknya, lihat Menyiapkan Agent Gateway.

    Pastikan gateway dikonfigurasi untuk memenuhi kebutuhan deployment Anda. Misalnya, jika agen Anda memerlukan akses LLM, konfigurasi gateway untuk mengizinkan akses ini guna mencegah potensi kegagalan deployment Agent Runtime.

  2. Tentukan resource gateway saat men-deploy agen Anda. Misalnya, untuk men-deploy agen di Agent Runtime, gunakan client.agent_engines.create untuk meneruskan objek local_agent beserta konfigurasi opsional.

    remote_agent = client.agent_engines.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "agent_to_anywhere_config": {"agent_gateway": AGENT_GATEWAY_TO_ANYWHERE_NAME},
        # "client_to_agent_config": {"agent_gateway": AGENT_GATEWAY_CLIENT_TO_AGENT_NAME}
      },
      "identity_type": types.IdentityType.AGENT_IDENTITY,
      # Other optional configuration ...
      # "requirements": requirements,
      # "gcs_dir_name": gcs_dir_name,
      # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa
      "env_vars": {
        "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
      }
  },
)

    Ganti AGENT_GATEWAY_TO_ANYWHERE_NAME dengan jalur lengkap Agent Gateway yang Anda buat dalam mode Agent-to-Anywhere (keluar). Misalnya, projects/PROJECT/locations/REGION/agentGateways/AGENT_GATEWAY_ID.

    Jika Anda membuat gateway dalam mode Client-to-Agent (masuk), gunakan kolom client_to_agent_config dan ganti AGENT_GATEWAY_CLIENT_TO_AGENT_NAME dengan jalur lengkap Agent Gateway yang Anda buat untuk masuk.

  3. Daftarkan agen Anda dengan instance Agent Registry di project dan region yang sama dengan agen dan gateway. Untuk mengetahui informasi selengkapnya, lihat Mendaftarkan agen.

Membatasi Agent Runtime ke Agent Gateway yang disetujui

Anda dapat membuat batasan kebijakan organisasi kustom untuk menentukan kumpulan resource Agent Gateway yang memenuhi syarat dan dapat digunakan saat men-deploy agen.

Membuat batasan kebijakan organisasi kustom

Contoh ini membuat batasan kustom yang hanya mengizinkan traffic ke dan dari daftar gateway yang telah disetujui sebelumnya.

Agent-to-Anywhere

  1. Untuk menentukan batasan kustom untuk mode Agent-to-Anywhere (keluar), buat file bernama constraint-agent-gateway-egress.yaml.

    Dalam contoh berikut, kolom condition menentukan bahwa operasi hanya diizinkan jika resource Agent Gateway ditentukan (kolom ada dan tidak kosong) dan jika gateway yang ditentukan ada dalam daftar yang telah disetujui sebelumnya.

    name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedEgressAgentGatewaysForAgentEngine
resource_types:
- aiplatform.googleapis.com/ReasoningEngine
condition: >-
has(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway) &&
resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway != '' &&
(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway in [
  'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
  'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
])
method_types:
- CREATE
- UPDATE
action_type: ALLOW
display_name: Restrict Reasoning Engine Egress to Approved Agent Gateways
description: Reasoning Engines can only be bound to a pre-approved list of
Agent Gateway instances. Binding to any other gateway is denied.

    Ganti kode berikut:

    • ORGANIZATION_ID: ID organisasi Anda.
    • AGENT_PROJECT_ID: project ID Anda.
    • REGION: region tempat gateway dibuat.
    • AGENT_GATEWAY_ID: ID gateway Anda.

  2. Terapkan batasan kustom.

    gcloud alpha org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH

    Ganti EGRESS_CONSTRAINT_PATH dengan jalur lengkap ke file batasan kustom yang dibuat pada langkah sebelumnya.

  3. Buat kebijakan organisasi untuk menerapkan batasan. Untuk menentukan kebijakan organisasi, buat file YAML kebijakan bernama policy-agent-gateway-egress.yaml. Dalam contoh ini, kami menerapkan batasan ini di level project, tetapi Anda juga dapat menetapkannya di level organisasi atau folder.

    name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedEgressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true

    Ganti AGENT_PROJECT_ID dengan project ID Anda.

  4. Terapkan kebijakan organisasi.

    gcloud alpha org-policies set-policy EGRESS_POLICY_PATH

    Ganti EGRESS_POLICY_PATH dengan jalur lengkap ke file YAML kebijakan organisasi yang dibuat pada langkah sebelumnya. Kebijakan ini memerlukan waktu hingga 15 menit untuk diterapkan.

Client-to-Agent

  1. Untuk menentukan batasan kustom untuk mode Client-to-Agent (masuk), buat file bernama constraint-agent-gateway-ingress.yaml.

    Dalam contoh berikut, kolom condition menentukan bahwa operasi hanya diizinkan jika resource Agent Gateway ditentukan (kolom ada dan tidak kosong) dan jika gateway yang ditentukan ada dalam daftar yang telah disetujui sebelumnya.

    name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedIngressAgentGatewaysForAgentEngine
resource_types:
- aiplatform.googleapis.com/ReasoningEngine
condition: >-
has(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway) &&
resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway != '' &&
(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway in [
  'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
  'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
])
method_types:
- CREATE
- UPDATE
action_type: ALLOW
display_name: Restrict Reasoning Engine Ingress to Approved Agent Gateways
description: Reasoning Engines can only be bound to a pre-approved list of
Agent Gateway instances. Binding to any other gateway is denied.

    Ganti kode berikut:

    • ORGANIZATION_ID: ID organisasi Anda.
    • AGENT_PROJECT_ID: project ID Anda.
    • REGION: region tempat gateway dibuat.
    • AGENT_GATEWAY_ID: ID gateway Anda.

  2. Terapkan batasan kustom.

    gcloud alpha org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH

    Ganti INGRESS_CONSTRAINT_PATH dengan jalur lengkap ke file batasan kustom yang dibuat pada langkah sebelumnya.

  3. Buat kebijakan organisasi untuk menerapkan batasan. Untuk menentukan kebijakan organisasi, buat file YAML kebijakan bernama policy-agent-gateway-ingress.yaml. Dalam contoh ini, kami menerapkan batasan ini di level project, tetapi Anda juga dapat menetapkannya di level organisasi atau folder.

    name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedIngressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true

    Ganti AGENT_PROJECT_ID dengan project ID Anda.

  4. Terapkan kebijakan organisasi.

    gcloud alpha org-policies set-policy INGRESS_POLICY_PATH

    Ganti INGRESS_POLICY_PATH dengan jalur lengkap ke file YAML kebijakan organisasi yang dibuat pada langkah sebelumnya. Kebijakan ini memerlukan waktu hingga 15 menit untuk diterapkan.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan batasan kebijakan organisasi kustom, lihat Membuat batasan kustom.

Langkah berikutnya