Auf dieser Seite wird beschrieben, wie Sie einen einzelnen Agenten in Ihrem Projekt freigeben, indem Sie Nutzern oder Dienstkonten Identity and Access Management-Berechtigungen gewähren.
Wenn Sie einen Agenten freigeben möchten, gewähren Sie die Berechtigung aiplatform.reasoningEngines.query für die entsprechende Agentenressource.
Wann sollte ein Agent freigegeben werden?
Wenn Sie einen Agenten freigeben, können mehrere Nutzer oder automatisierte Systeme Anfragen an den Agenten senden. Häufige Anwendungsfälle für die Freigabe eines Agenten sind:
- Zusammenarbeit: Geben Sie einen Agenten für andere Mitglieder Ihres Teams oder Ihrer Organisation frei, damit diese ihn für ihre Aufgaben verwenden können.
- Anwendungsintegration: Gewähren Sie Zugriff auf ein Dienstkonto, damit eine benutzerdefinierte Anwendung wie ein interner Chatbot oder ein Kundensupport portal den Agenten aufrufen kann, um bestimmte Nutzeranfragen zu bearbeiten.
- Agent-zu-Agent-Kommunikation: In einem Multi-Agenten-System muss ein Agent möglicherweise einen anderen Agenten aufrufen, um Informationen zu erhalten oder eine Unteraufgabe zu delegieren.
- Informationszugriff: Gewähren Sie Nutzern kontrollierten Zugriff auf Daten über eine Konversationsschnittstelle, ohne ihnen direkten Zugriff auf die zugrunde liegenden Datenquellen zu gewähren. Geben Sie beispielsweise einen Agenten, der mit einer Wissensdatenbank (z. B. HR-Richtlinien oder technische Dokumentation) verbunden ist, für alle Mitarbeiter frei.
Hinweis
- Identifizieren Sie den Agenten, den Sie freigeben möchten. Sie benötigen die Projekt-ID und die ID der Reasoning Engine des Agenten.
- Identifizieren Sie die Nutzer oder Dienstkonten, denen Sie Zugriff gewähren möchten.
Schritt 1: Benutzerdefinierte Rolle erstellen
Um dem Prinzip der geringsten Berechtigung zu folgen, erstellen Sie eine benutzerdefinierte Rolle, die nur die Berechtigung aiplatform.reasoningEngines.query enthält.
gcloud
Führen Sie den folgenden Befehl aus, um eine benutzerdefinierte Rolle im Projekt zu erstellen:
gcloud iam roles create ROLE_ID --project=PROJECT_ID \ --title="ROLE_TITLE" \ --description="ROLE_DESCRIPTION" \ --permissions=aiplatform.reasoningEngines.query
Alternativ können Sie die Rolle für die gesamte Organisation erstellen:
gcloud iam roles create ROLE_ID --organization=ORGANIZATION_ID \ --title="ROLE_TITLE" \ --description="ROLE_DESCRIPTION" \ --permissions=aiplatform.reasoningEngines.query
Ersetzen Sie Folgendes:
ROLE_ID: Die ID der Rolle, z. B.agentUser.ROLE_TITLE: Ein Titel für die Rolle, z. B.Agent runtime user.ROLE_DESCRIPTION: Eine kurze Beschreibung der Rolle, z. B.Allows querying agents.PROJECT_ID: Die Projekt-ID.ORGANIZATION_ID: Die Organisations-ID.
Terraform
Verwenden Sie die Ressource google_project_iam_custom_role, um die benutzerdefinierte Rolle mit Terraform zu erstellen:
resource "google_project_iam_custom_role" "reasoning_engine_query" {
role_id = "ROLE_ID"
title = "ROLE_TITLE"
project = "PROJECT_ID"
permissions = ["aiplatform.reasoningEngines.query"]
}
Ersetzen Sie Folgendes:
ROLE_ID: Die ID der Rolle, z. B.agentUser.ROLE_TITLE: Ein Titel für die Rolle, z. B.Agent runtime user.PROJECT_ID: Die Projekt-ID.
Der Name der benutzerdefinierten Rolle ist projects/PROJECT_ID/roles/ROLE_ID oder organizations/ORGANIZATION_ID/roles/ROLE_ID.
Schritt 2: Rolle für den Agenten gewähren
Nachdem die Rolle erstellt wurde, binden Sie sie an einen Agenten und geben Sie den Nutzer oder das Dienstkonto an, dem Sie die Berechtigung gewähren möchten.
Python
Verwenden Sie die Bibliothek google-cloud-aiplatform, um die Rolle mit Python zu gewähren:
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})
Ersetzen Sie Folgendes:
LOCATION: Die Region, in der der Agent bereitgestellt wird, z. B.us-central1.PROJECT_ID: Die Projekt-ID.REASONING_ENGINE_ID: Die ID der Reasoning Engine des Agenten.ROLE_ID: Die ID der Rolle, z. B.agentUser.USER_OR_SA: Die E-Mail-Adresse des Nutzers oder das Dienstkonto, z. B.user:someone@example.comoderserviceAccount:my-sa@my-project.iam.gserviceaccount.com.
Terraform
Verwenden Sie die Ressource google_vertex_ai_reasoning_engine_iam_member, um die Rolle mit Terraform zu gewähren:
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"
}
Ersetzen Sie Folgendes:
PROJECT_ID: Die Projekt-ID.REGION: Die Region.USER_OR_SA: Der Nutzer oder das Dienstkonto.
Sicherheitsaspekte
Wenn Sie Zugriff auf den Agenten gewähren, erhalten Sie direkten Zugriff, um Nachrichten an den FastAPI-Endpunkt des Agenten zu senden. Die Sicherheitsgarantien werden durch den Code des empfangenden Agenten bestimmt.
- Vertrauenswürdiges Frontend: Die meisten Standard-ADK-Agenten werden über ein vertrauenswürdiges Frontend ausgeführt. Der Agent vertraut den Frontend-Befehlen, wodurch das Frontend die vollständige Kontrolle über Sitzungen und Nutzer erhält. Gewähren Sie in diesen Fällen nicht vertrauenswürdigen Entitäten direkten Zugriff auf den Agenten.
- A2A-Agenten: Andere Agenten wie Agent2Agent-Agenten (A2A) können für nicht vertrauenswürdige Entitäten zugänglich gemacht werden, wenn sie ihre eigene Authentifizierung und Autorisierung implementieren. Die Agentenlaufzeit bietet nur eine grobe Zugriffssteuerung für die Agentenschnittstelle.