Schnellstart: Computernutzung

Vorschau

Diese Funktion unterliegt den "Bedingungen für Pre-GA-Angebote" im Abschnitt "Allgemeine Dienstbedingungen" der dienstspezifischen Nutzungsbedingungen. Diese Funktion bietet eine Sandbox-Umgebung für KI-Agents. Daher gelten die dienstspezifischen Nutzungsbedingungen für „agentische KI-Dienste“. Wenn Sie diese Funktion nutzen möchten, müssen Sie den vollständigen Netzwerkzugriff für Ihren KI-Agent aktivieren. Berücksichtigen Sie daher die geltenden Sicherheitsmaßnahmen (einschließlich menschlicher Aufsicht) und die Richtlinien Ihrer Organisation, bevor Sie dies tun. Informationen zu integrierten Sicherheitsmaßnahmen für die Computernutzung finden Sie im Tool zur Computernutzung der Agent Platform .

Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie in den Beschreibungen der Produkteinführungsphasen.

Auf dieser Seite wird gezeigt, wie Sie direkte API-Aufrufe ausführen, um eine Sandbox-Umgebung für die Computernutzung zu erstellen und zu verwenden. In dieser Kurzanleitung führen Sie die folgenden Aufgaben aus:

• Erstellen Sie eine Agent Platform-Instanz, um auf die Sandbox zuzugreifen.
• Erstellen Sie eine Sandbox für die Computernutzung.
• Generieren Sie ein Zugriffstoken für die Sandbox.
• Senden Sie eine Anfrage, um den Status zu prüfen.
• Bereinigen Sie die Ressourcen.

Hinweis

Richten Sie Ihr Projekt und Ihre Umgebung ein.

Projekt einrichten

Melden Sie sich in Ihrem Google Cloud Konto an. Wenn Sie noch nicht mit Google Cloudvertraut sind, erstellen Sie ein Konto, um die Leistung unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Gemini Enterprise Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Gemini Enterprise Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Erforderliche Rollen abrufen

Um die Sandbox zu verwenden und Tokens zu generieren, benötigen Sie die folgenden Rollen:

• Agent Platform User (roles/aiplatform.user) für das Projekt.
• Ersteller von Dienstkonto-Tokens (roles/iam.serviceAccountTokenCreator) für das Dienstkonto, das für die Tokenerstellung verwendet wird.
• Das für die Tokenerstellung verwendete Dienstkonto muss außerdem die Rolle Agent Platform User (roles/aiplatform.user) für das Projekt haben.

Bibliotheken installieren

Installieren Sie das Agent Platform SDK: posix-terminal pip install google-cloud-aiplatform>=1.112.0

Agent Platform-Instanz erstellen

Wenn Sie die Sandbox verwenden möchten, erstellen Sie zuerst eine Agent Platform-Instanz.

import vertexai
client = vertexai.Client(
    project='PROJECT_ID',
    location='LOCATION',
    http_options={
        "api_version": "v1beta1",
    }
)
agent_instance = client.agent_engines.create()
agent_instance_name = agent_instance.api_resource.name

Ersetzen Sie Folgendes:

• PROJECT_ID: Ihre Google Cloud Projekt-ID
• LOCATION: Die Region für Ihre Instanz, z. B. us-central1.

Vorlage für die Computernutzung erstellen

Erstellen Sie eine Sandbox-Vorlage, die Sie beim Erstellen einer Sandbox für die Computernutzung verwenden.

# Create a default Computer Use sandbox template
templates_client = client.agent_engines.sandboxes.templates
tmplt_operation = templates_client.create(
    name=agent_instance_name,
    display_name='DISPLAY_NAME',
    config={
        "default_container_environment": {
            "default_container_category": "DEFAULT_CONTAINER_CATEGORY_COMPUTER_USE",
        },
        "egress_control_config": {
            "internet_access": True,
        },
    },
)
template_name = tmplt_operation.response.name
print(f"Created template: {template_name}")

Sandbox für die Computernutzung erstellen

Erstellen Sie eine Sandbox-Umgebung aus der Vorlage.

Hinweis: Sandboxes laufen standardmäßig nach 2 Stunden ab. Sie können die Lebensdauer der Sandbox anpassen, indem Sie beim Erstellen einer Sandbox das Feld ttl festlegen.

# Create a sandbox environment referencing the template.
# To customize the lifetime, set `ttl` to a duration string in seconds (for example, "3600s" for 1 hour).
create_operation = client.agent_engines.sandboxes.create(
    name=agent_instance_name,
    config={
        "sandbox_environment_template": template_name,
        "display_name": 'DISPLAY_NAME',
        "ttl": "3600s",  # Optional. Overrides the default 2-hour sandbox lifetime.
    }
)
sandbox = create_operation.response
print(f"Created sandbox environment: {sandbox.name}")
print(f"Sandbox will expire at: {sandbox.expire_time}")

Zugriffstoken generieren

Um mit der Sandbox zu interagieren, generieren Sie mit einem Dienstkonto ein JSON Web Token (JWT)-Zugriffstoken.

service_account_email = "SERVICE_ACCOUNT_EMAIL"
access_token = client.agent_engines.sandboxes.generate_access_token(
    service_account_email=service_account_email,
)

Ersetzen Sie SERVICE_ACCOUNT_EMAIL durch die E-Mail-Adresse des Dienstkontos mit der Rolle Ersteller von Dienstkonto-Tokens.

Anfrage an die Sandbox senden

Senden Sie eine HTTP-GET-Anfrage an den Sandbox-API-Server, um den Status zu prüfen.

response = client.agent_engines.sandboxes.send_command(
    http_method="GET",
    access_token=access_token,
    sandbox_environment=sandbox
)
print(f"Sandbox response: {response.body}")

Senden Sie eine HTTP-POST-Anfrage, um zu einer bestimmten Seite zu wechseln.

data = {"command": "Page.navigate", "params": {"url": "https://example.com"}}

response = client.agent_engines.sandboxes.send_command(
    http_method="POST",
    path="cdp",
    access_token=access_token,
    request_dict=data,
    sandbox_environment=sandbox
)

In der folgenden Tabelle sind zusätzliche Methoden und Pfade aufgeführt, die Sie an Ihre Sandbox senden können:

Methode	Pfad	Beschreibung
GET	/	Ruft den Gesundheitscheck der Sandbox ab
POST	/tabs	Erstellt einen neuen Tab und gibt die Details zurück.
GET	/tabs	Listet Details für alle geöffneten Tabs auf.
POST	/tabs/{tab_id}/activate	Legt einen Tab als aktiv fest und bringt ihn in den Vordergrund.
LÖSCHEN	/tabs/{tab_id}	Schließt einen bestimmten Tab.
GET	/cdp_ws_endpoint	Gibt den CDP-WebSocket-Endpunktpfad zurück.
POST	/cdp	Führt einen CDP-Befehl auf dem aktiven Tab aus.
POST	/cdps	Führt mehrere CDP-Befehle auf dem aktiven Tab aus.

Weitere Informationen zu den unterstützten CDP-Befehlen und -Formaten finden Sie auf der CDP-Website.

Bereinigen

Löschen Sie die in dieser Kurzanleitung erstellten Ressourcen, um Gebühren zu vermeiden.

client.agent_engines.sandboxes.delete(name=sandbox.name)
agent_instance.delete()

Nächste Schritte

• Informationen zu Snapshots für die Lebenszyklusverwaltung von Sandboxes