Traffic der Laufzeit für KI-Agenten über das Agent Gateway weiterleiten

Auf dieser Seite wird beschrieben, wie Sie den Traffic der Agent-Laufzeit über das Agent Gateway weiterleiten. Das Agent Gateway ist eine zentrale Netzwerk- und Sicherheitskomponente des Ökosystems der Gemini Enterprise Agent Platform. Es bietet sichere und verwaltete Verbindungen für alle Interaktionen mit KI-Agenten, unabhängig davon, ob sie zwischen Nutzern und KI-Agenten, zwischen KI-Agenten und Tools oder zwischen KI-Agenten selbst stattfinden.

Hinweis

  • Machen Sie sich mit der Bereitstellung von Agenten in der Laufzeit für KI-Agenten vertraut.

  • Weitere Informationen zum Agent Gateway Sie können Agent Gateway im Agent-to-Anywhere-Modus (Egress) verwenden, um die gesamte ausgehende Kommunikation mit ausgehendem Traffic zu Tools, Modellen, APIs und anderen Agents zu sichern und zu steuern. Sie verwenden das Gateway im Client-to-Agent-Modus (Ingress), um zu steuern, welche Clients auf Ihre Agents zugreifen können. Über das Gateway können Sie auswählen, welche IAP-Richtlinien und Model Armor-Vorlagen auf diese Interaktionen angewendet werden müssen.

  • Erstellen Sie ein dediziertes Testprojekt, um diesen Workflow auszuprobieren. Vermeiden Sie die Verwendung von Projekten, die auch für andere kritische Arbeitslasten vorgesehen sind.

Beschränkungen

  • Pro Projekt und Region kann es nur eine Agent-to-Anywhere-Instanz (Egress) und eine Client-to-Agent-Instanz (Ingress) von Agent Gateway geben. Alle Agent Runtime-Agents im selben Projekt und in derselben Region, die für die Verwendung von Agent Gateway konfiguriert sind, müssen diese bestimmten Gateway-Instanzen verwenden.
  • Der Dienst Security Command Center Agent Engine Threat Detection ist nicht verfügbar, wenn Agent Gateway für einen Agent aktiviert ist.
  • Sie können einen Runtime-Agent nicht von einer Agent Gateway-Ressource trennen. Verwenden Sie daher ein dediziertes Testprojekt.

Erforderliche Berechtigungen

Sie müssen dem Reasoning Engine-Dienst-Agent die Berechtigung erteilen, die von Ihnen erstellte Agent Gateway-Ressource zu verwenden.

  1. Wenn es noch nicht vorhanden ist, erstellen Sie das Dienstkonto. Das Reasoning Engine-Dienstkonto wird in der Regel automatisch erstellt, wenn Sie Reasoning Engine zum ersten Mal verwenden.

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

    Ersetzen Sie AGENT_PROJECT_ID durch die Projekt-ID des Projekts, in dem Sie den Agent bereitstellen möchten.

  2. Für die Verwendung des Gateways benötigen Sie die folgenden Berechtigungen:

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

    Erstellen Sie eine benutzerdefinierte Rolle mit allen diesen Berechtigungen und weisen Sie sie dann dem Reasoning Engine-Dienstkonto zu.

    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"

    Ersetzen Sie Folgendes:

    • AGENT_GATEWAY_ROLE_ID: Die ID der benutzerdefinierten Rolle.
    • AGENT_PROJECT_ID: Die Projekt-ID des Projekts, in dem Sie den Agent bereitstellen möchten.

  3. Weisen Sie dem Dienstkonto für die Agent-Laufzeit die Rolle zu.

    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"

    Ersetzen Sie Folgendes:

    • AGENT_PROJECT_ID: Die Projekt-ID des Projekts, in dem Sie den Agent bereitstellen möchten.
    • AGENT_PROJECT_NUMBER: Die Projektnummer des Projekts, in dem Sie den Agent bereitstellen möchten.
    • AGENT_GATEWAY_ROLE_ID: Die ID der benutzerdefinierten Rolle, die Sie erstellt haben.

  4. Wenn Sie Model Armor-Vorlagen für die Inhaltsautorisierung verwenden möchten, müssen Sie dem Reasoning Engine-Dienst-Agent und dem Agent Gateway-Dienstkonto die folgenden Berechtigungen erteilen:

    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

    Ersetzen Sie Folgendes:

    • AGENT_PROJECT_ID: Die Projekt-ID des Projekts, in dem Sie den Agent bereitstellen möchten.
    • AGENT_PROJECT_NUMBER: Die Projektnummer des Projekts, in dem Sie den Agent bereitstellen möchten.
    • MODEL_ARMOR_PROJECT_ID: Die Projekt-ID des Projekts, in dem die Model Armor-Vorlagen erstellt werden.

Traffic der Laufzeit für KI-Agenten über das Agent Gateway weiterleiten

So leiten Sie den Agent Runtime-Traffic über das Agent Gateway weiter:

  1. Erstellen Sie eine Agent Gateway-Ressource und hängen Sie bei Bedarf Autorisierungsrichtlinien an. Sie können ein Gateway entweder im Agent-to-Anywhere-Modus (Ausgang) oder im Client-to-Agent-Modus (Eingang) erstellen. Der Agent und das Gateway müssen im selben Projekt und in derselben Region erstellt werden. Eine Anleitung finden Sie unter Agent Gateway einrichten.

    Achten Sie darauf, dass das Gateway entsprechend den Anforderungen Ihrer Bereitstellung konfiguriert ist. Wenn Ihr Agent beispielsweise LLM-Zugriff benötigt, konfigurieren Sie das Gateway so, dass dieser Zugriff zulässig ist, um potenzielle Fehler bei der Bereitstellung der Agent Runtime zu vermeiden.

  2. Geben Sie die Gateway-Ressource beim Bereitstellen des Agents an. Wenn Sie den Agenten beispielsweise in der Agent Runtime bereitstellen möchten, verwenden Sie client.agent_engines.create, um das local_agent-Objekt zusammen mit allen optionalen Konfigurationen zu übergeben.

    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,
      }
  },
)

    Ersetzen Sie AGENT_GATEWAY_TO_ANYWHERE_NAME durch den vollständigen Pfad des Agent Gateway, das Sie im Modus „Agent-to-Anywhere“ (Egress) erstellt haben. Beispiel: projects/PROJECT/locations/REGION/agentGateways/AGENT_GATEWAY_ID

    Wenn Sie ein Gateway im Client-to-Agent-Modus (Ingress) erstellt haben, verwenden Sie stattdessen das Feld client_to_agent_config und ersetzen Sie AGENT_GATEWAY_CLIENT_TO_AGENT_NAME durch den vollständigen Pfad des Agent-Gateways, das Sie für den Ingress erstellt haben.

  3. Registrieren Sie Ihren Agenten bei der Agent Registry-Instanz im selben Projekt und in derselben Region wie der Agent und das Gateway. Weitere Informationen finden Sie unter Agent registrieren.

Agent Runtime auf genehmigte Agent Gateways beschränken

Sie können benutzerdefinierte Einschränkungen für Organisationsrichtlinien erstellen, um die Gruppe der infrage kommenden Agent Gateway-Ressourcen zu definieren, die beim Bereitstellen von Agenten verwendet werden können.

Benutzerdefinierte Einschränkungen für Organisationsrichtlinien erstellen

In diesem Beispiel werden benutzerdefinierte Einschränkungen erstellt, die nur Traffic zu und von einer vorab genehmigten Liste von Gateways zulassen.

Agent zu beliebigem Ziel

  1. Wenn Sie eine benutzerdefinierte Einschränkung für den Agent-to-Anywhere-Modus (Ausgang) definieren möchten, erstellen Sie eine Datei mit dem Namen constraint-agent-gateway-egress.yaml.

    Im folgenden Beispiel gibt das Feld condition an, dass der Vorgang nur zulässig ist, wenn eine Agent Gateway-Ressource angegeben ist (Feld ist vorhanden und nicht leer) und wenn das angegebene Gateway in der vorab genehmigten Liste enthalten ist.

    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.

    Ersetzen Sie Folgendes:

    • ORGANIZATION_ID: Ihre Organisations-ID.
    • AGENT_PROJECT_ID: Ihre Projekt-ID.
    • REGION: die Region, in der das Gateway erstellt wurde.
    • AGENT_GATEWAY_ID: Ihre Gateway-ID.

  2. Wenden Sie die benutzerdefinierte Einschränkung an.

    gcloud alpha org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH

    Ersetzen Sie EGRESS_CONSTRAINT_PATH durch den vollständigen Pfad zur benutzerdefinierten Einschränkungsdatei, die Sie im vorherigen Schritt erstellt haben.

  3. Erstellen Sie die Organisationsrichtlinie, um die Einschränkung zu erzwingen. Erstellen Sie eine YAML-Richtliniendatei mit dem Namen policy-agent-gateway-egress.yaml, um die Organisationsrichtlinie zu definieren. In diesem Beispiel wird diese Einschränkung auf Projektebene erzwungen. Sie können diese Einschränkung aber auch auf Organisations- oder Ordnerebene festlegen.

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

    Ersetzen Sie AGENT_PROJECT_ID durch Ihre Projekt-ID.

  4. Organisationsrichtlinie erzwingen

    gcloud alpha org-policies set-policy EGRESS_POLICY_PATH

    Ersetzen Sie EGRESS_POLICY_PATH durch den vollständigen Pfad zur YAML-Datei der Organisationsrichtlinie, die Sie im vorherigen Schritt erstellt haben. Es kann bis zu 15 Minuten dauern, bis die Richtlinie wirksam wird.

Client zu Agent

  1. Wenn Sie eine benutzerdefinierte Einschränkung für den Client-to-Agent-Modus (eingehender Traffic) definieren möchten, erstellen Sie eine Datei mit dem Namen constraint-agent-gateway-ingress.yaml.

    Im folgenden Beispiel gibt das Feld condition an, dass der Vorgang nur zulässig ist, wenn eine Agent Gateway-Ressource angegeben ist (Feld ist vorhanden und nicht leer) und wenn das angegebene Gateway in der vorab genehmigten Liste enthalten ist.

    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.

    Ersetzen Sie Folgendes:

    • ORGANIZATION_ID: Ihre Organisations-ID.
    • AGENT_PROJECT_ID: Ihre Projekt-ID.
    • REGION: die Region, in der das Gateway erstellt wurde.
    • AGENT_GATEWAY_ID: Ihre Gateway-ID.

  2. Wenden Sie die benutzerdefinierte Einschränkung an.

    gcloud alpha org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH

    Ersetzen Sie INGRESS_CONSTRAINT_PATH durch den vollständigen Pfad zur benutzerdefinierten Einschränkungsdatei, die Sie im vorherigen Schritt erstellt haben.

  3. Erstellen Sie die Organisationsrichtlinie, um die Einschränkung zu erzwingen. Erstellen Sie eine YAML-Richtliniendatei mit dem Namen policy-agent-gateway-ingress.yaml, um die Organisationsrichtlinie zu definieren. In diesem Beispiel wird diese Einschränkung auf Projektebene erzwungen. Sie können diese Einschränkung aber auch auf Organisations- oder Ordnerebene festlegen.

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

    Ersetzen Sie AGENT_PROJECT_ID durch Ihre Projekt-ID.

  4. Organisationsrichtlinie erzwingen

    gcloud alpha org-policies set-policy INGRESS_POLICY_PATH

    Ersetzen Sie INGRESS_POLICY_PATH durch den vollständigen Pfad zur YAML-Datei der Organisationsrichtlinie, die Sie im vorherigen Schritt erstellt haben. Es kann bis zu 15 Minuten dauern, bis die Richtlinie wirksam wird.

Weitere Informationen zur Verwendung benutzerdefinierter Einschränkungen für Organisationsrichtlinien finden Sie unter Benutzerdefinierte Einschränkungen erstellen.

Nächste Schritte