Agent bereitstellen

Paketanforderungen definieren

Geben Sie die Menge der Pakete an, die für die Bereitstellung des Agents erforderlich sind. Die Gruppe von Paketen kann entweder eine Liste von Elementen sein, die von pip installiert werden sollen, oder der Pfad zu einer Datei, die dem Format der Anforderungsdatei entspricht. Beachten Sie die folgenden Best Practices:

1. Pinnen Sie Ihre Paketversionen für reproduzierbare Builds. Zu den gängigen Paketen, die Sie im Blick behalten sollten, gehören: google-cloud-aiplatform, cloudpickle, langchain, langchain-core, langchain-google-vertexai und pydantic.
2. Minimieren Sie die Anzahl der Abhängigkeiten in Ihrem Agent. Dadurch wird die Anzahl der funktionsgefährdenden Änderungen beim Aktualisieren Ihrer Abhängigkeiten und Ihres Agents reduziert.

Wenn der Agent keine Abhängigkeiten hat, können Sie requirements auf None setzen:

requirements = None

Wenn der Agent eine frameworkspezifische Vorlage verwendet, sollten Sie bei der Entwicklung des Agents die importierte SDK-Version angeben (z. B. 1.112.0).

requirements = [
    "google-cloud-aiplatform[agent_engines,adk]",
    # any other dependencies
]

requirements = [
    "google-cloud-aiplatform[agent_engines]",
    "a2a-sdk>=0.3.4"
    # any other dependencies
]

requirements = [
    "google-cloud-aiplatform[agent_engines,langchain]",
    # any other dependencies
]

requirements = [
    "google-cloud-aiplatform[agent_engines,langgraph]",
    # any other dependencies
]

requirements = [
    "google-cloud-aiplatform[agent_engines,ag2]",
    # any other dependencies
]

requirements = [
    "google-cloud-aiplatform[agent_engines,llama_index]",
    # any other dependencies
]

Mit dem Paket requirements haben Sie außerdem folgende Möglichkeiten:

• Obergrenze für die Version eines bestimmten Pakets festlegen oder die Version eines bestimmten Pakets fixieren (z. B. google-cloud-aiplatform):

    requirements = [
        # See https://pypi.org/project/google-cloud-aiplatform for the latest version.
        "google-cloud-aiplatform[agent_engines,adk]==1.112.0",
    ]
    

• Zusätzliche Pakete und Einschränkungen hinzufügen:

    requirements = [
        "google-cloud-aiplatform[agent_engines,adk]==1.112.0",
        "cloudpickle==3.0", # new
    ]
    

• Auf die Version eines Pakets in einem GitHub-Branch oder einer Pull-Anfrage verweisen:

    requirements = [
        "google-cloud-aiplatform[agent_engines,adk] @ git+https://github.com/googleapis/python-aiplatform.git@BRANCH_NAME", # new
    ]
    

• Führen Sie die Liste der Anforderungen in einer Datei (z. B. path/to/requirements.txt):

    requirements = "path/to/requirements.txt"
    

  Dabei ist path/to/requirements.txt eine Textdatei, die dem Format der Anforderungsdatei entspricht. Beispiel:

    google-cloud-aiplatform[agent_engines,adk]
    cloudpickle==3.0
    

Zusätzliche Pakete definieren

Sie können lokale Dateien oder Verzeichnisse einfügen, die erforderliche lokale Python-Quelldateien enthalten. Im Vergleich zu Paketanforderungen können Sie so private Dienstprogramme verwenden, die Sie entwickelt haben und die sonst nicht auf PyPI oder GitHub verfügbar sind.

Wenn für den Agent keine zusätzlichen Pakete erforderlich sind, können Sie extra_packages auf None festlegen:

extra_packages = None

Mit extra_packages haben Sie auch folgende Möglichkeiten:

• Eine einzelne Datei einfügen (z. B. agents/agent.py):

    extra_packages = ["agents/agent.py"]
    

• Fügen Sie die Dateien eines gesamten Verzeichnisses ein (z. B. agents/):

    extra_packages = ["agents"] # directory that includes agents/agent.py
    

• Geben Sie Python-Rad-Binärdateien an (z. B. path/to/python_package.whl):

    requirements = [
        "google-cloud-aiplatform[agent_engines,adk]",
        "cloudpickle==3.0",
        "python_package.whl",  # install from the whl file that was uploaded
    ]
    extra_packages = ["path/to/python_package.whl"]  # bundle the whl file for uploading
    

Umgebungsvariablen definieren

Wenn Ihr Agent von Umgebungsvariablen abhängt, können Sie diese im Argument env_vars= angeben. Wenn der Agent nicht von Umgebungsvariablen abhängt, können Sie ihn auf None setzen:

env_vars = None

Es gibt verschiedene Möglichkeiten, die Umgebungsvariablen anzugeben:

env_vars = {
  "VARIABLE_1": "VALUE_1",
  "VARIABLE_2": "VALUE_2",
}
# These environment variables will become available in Vertex AI Agent Engine
# through `os.environ`, e.g.
#
#   import os
#   os.environ["VARIABLE_1"] # will have the value "VALUE_1"
#
# and
#
#   os.environ["VARIABLE_2"] # will have the value "VALUE_2"
#

env_vars = {
  # ... (other environment variables and their values)
  "CLOUD_SQL_CREDENTIALS_SECRET": {"secret": SECRET_ID, "version": SECRET_VERSION_ID},
}

secret = os.environ.get("CLOUD_SQL_CREDENTIALS_SECRET")
if secret:
  # Secrets are stored as strings, so use json.loads to parse JSON
  # payloads.
  return json.loads(secret)

env_vars = ["VARIABLE_1", "VARIABLE_2"]
# This corresponds to the following code snippet:
#
#   import os
#
#   env_vars = {
#     "VARIABLE_1": os.environ["VARIABLE_1"],
#     "VARIABLE_2": os.environ["VARIABLE_2"],
#   }

Außerdem müssen Sie die Anleitung unter Identität und Berechtigungen für Ihren Agent einrichten befolgen, um Ihrem Agent die Berechtigung „Secret Manager Secret Accessor“ (roles/secretmanager.secretAccessor) zu erteilen.

Benutzerdefinierte Ressourcenkontrollen definieren

Sie können Laufzeitressourcen für den Agenten festlegen, z. B. die Mindest- und Höchstanzahl von Anwendungsinstanzen, Ressourcenlimits für jeden Container und die Nebenläufigkeit für jeden Container.

• min_instances: Die Mindestanzahl der Anwendungsinstanzen, die jederzeit ausgeführt werden sollen, mit einem Bereich von [0, 10]. Der Standardwert ist 1.

• max_instances: Die maximale Anzahl von Anwendungsinstanzen, die gestartet werden können, um mehr Traffic zu bewältigen. Der Bereich liegt zwischen [1, 1000]. Der Standardwert ist 100. Wenn VPC-SC oder PSC-I aktiviert ist, liegt der zulässige Bereich bei [1, 100].

• resource_limits: Ressourcenlimits für jeden Container. Es werden nur cpu- und memory-Schlüssel unterstützt. Der Standardwert ist {"cpu": "4", "memory": "4Gi"}.

  • Die einzigen unterstützten Werte für cpu sind 1, 2, 4, 6 und 8. Weitere Informationen finden Sie unter CPU-Zuweisung konfigurieren.

  • Die einzigen unterstützten Werte für memory sind 1Gi, 2Gi, … 32Gi.

  • Informationen zur erforderlichen CPU für verschiedene Speicherwerte finden Sie unter Arbeitsspeicherlimits konfigurieren.

• container_concurrency: Gleichzeitigkeit für jeden Container und Agent-Server. Der empfohlene Wert ist 2 * cpu + 1. Der Standardwert ist 9.

remote_agent = client.agent_engines.create(
    agent=local_agent,
    config={
        "min_instances": 1,
        "max_instances": 10,
        "resource_limits": {"cpu": "4", "memory": "8Gi"},
        "container_concurrency": 9,
        # ... other configs
    }
)

Build-Optionen definieren

Sie können Build-Optionen für den Agent angeben, z. B. Installationsskripts, die beim Erstellen des Container-Images des Agents ausgeführt werden sollen. Das ist nützlich, um Systemabhängigkeiten (z. B. gcloud cli, npx) oder andere benutzerdefinierte Setups zu installieren. Die Skripts werden mit Root-Berechtigungen ausgeführt.

Wenn Sie Installationsskripts verwenden möchten, erstellen Sie ein Verzeichnis mit dem Namen installation_scripts und legen Sie Ihre Shell-Skripts in diesem Verzeichnis ab:

.
├── ...
└── installation_scripts/
    └── install.sh

Geben Sie als Nächstes das Verzeichnis installation_scripts in extra_packages und die Skriptpfade in build_options an:

extra_packages = [..., "installation_scripts/install.sh"]
build_options = {"installation_scripts": ["installation_scripts/install.sh"]}

Sie können eines der folgenden gängigen Installationsskripts verwenden:

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

echo "--- Installing System-Wide Node.js v20.x ---"

# 1. Install prerequisites
apt-get update
apt-get install -y ca-certificates curl gnupg

# 2. Add the NodeSource repository GPG key
mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

# 3. Add the NodeSource repository for Node.js v20
NODE_MAJOR=20
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list

# 4. Update package lists again and install Node.js
apt-get update
apt-get install nodejs -y

echo "--- System-wide Node.js installation complete ---"
echo "Verifying versions:"

# These commands will now work for ANY user because node and npx
# are installed in /usr/bin/ which is in everyone's default PATH.
node -v
npm -v
npx -v

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

echo "Starting setup..."

# Install uv
apt-get update
apt-get install -y curl
curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/usr/local/bin" sh

# These commands will now work for ANY user because uv and uvx
# are installed in /usr/local/bin/ which is in everyone's default PATH.
uv --version
uvx --version

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

apt-get install -y curl gpg
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
apt-get update -y && apt-get install google-cloud-cli -y

gcloud --version

Cloud Storage-Ordner definieren

Staging-Artefakte werden überschrieben, wenn sie einem vorhandenen Ordner in einem Cloud Storage-Bucket entsprechen. Bei Bedarf können Sie den Cloud Storage-Ordner für die Staging-Artefakte angeben. Sie können gcs_dir_name auf None festlegen, wenn Sie nichts dagegen haben, dass die Dateien im Standardordner möglicherweise überschrieben werden:

gcs_dir_name = None

Damit die Dateien nicht überschrieben werden (z. B. für verschiedene Umgebungen wie Entwicklung, Staging und Produktion), können Sie einen entsprechenden Ordner einrichten und den Ordner angeben, in dem das Artefakt bereitgestellt werden soll:

gcs_dir_name = "dev" # or "staging" or "prod"

Wenn Sie Kollisionen vermeiden möchten oder müssen, können Sie eine zufällige uuid generieren:

import uuid
gcs_dir_name = str(uuid.uuid4())

Ressourcenmetadaten konfigurieren

Sie können Metadaten für die ReasoningEngine-Ressource festlegen:

display_name = "Currency Exchange Rate Agent (Staging)"

description = """
An agent that has access to tools for looking up the exchange rate.

If you run into any issues, please contact the dev team.
"""

Eine vollständige Liste der Parameter finden Sie in der API-Referenz.

Benutzerdefiniertes Dienstkonto konfigurieren

Sie können ein benutzerdefiniertes Dienstkonto als Identität Ihres bereitgestellten Agents konfigurieren, anstatt die Standardidentität zu verwenden.

Geben Sie dazu die E-Mail-Adresse Ihres benutzerdefinierten Dienstkontos als service_account an, wenn Sie die Agent Engine-Instanz erstellen oder aktualisieren, z. B.:

# Create a new instance
client.agent_engines.create(
    agent=local_agent,
    config={
        "service_account": "my-custom-service-account@my-project.iam.gserviceaccount.com",
        # ...
    },
)

# Update an existing instance
resource_name = "projects/{project_id}/locations/{location}/reasoningEngines/{reasoning_engine_id}"
client.agent_engines.update(
    name=resource_name,
    agent=local_agent,
    config={
        "service_account": "my-new-custom-service-account@my-project.iam.gserviceaccount.com",
        # ...
    },
)

Private Service Connect-Schnittstelle konfigurieren

Wenn Sie Private Service Connect-Schnittstelle und DNS-Peering eingerichtet haben, können Sie beim Bereitstellen des Agents die Netzwerkanbindung und das private DNS-Peering angeben:

remote_agent = client.agent_engines.create(
    agent=local_agent,
    config={
        "psc_interface_config": {
            "network_attachment": "NETWORK_ATTACHMENT",
            "dns_peering_configs": [
                {
                    "domain": "DOMAIN_SUFFIX",
                    "target_project": "TARGET_PROJECT",
                    "target_network": "TARGET_NETWORK",
                },
            ],
        },
    },
)

Dabei gilt:

• NETWORK_ATTACHMENT ist der Name oder vollständige Pfad Ihres Netzwerk-Anhangs. Wenn die Netzwerkverbindung in einem anderen Projekt als dem, in dem Sie Agent Engine verwenden, erstellt wird (z. B. im freigegebene VPC-Hostprojekt), müssen Sie den vollständigen Pfad der Netzwerkverbindung übergeben.
• DOMAIN_SUFFIX ist der DNS-Name der privaten Cloud DNS-Zone, die Sie beim Einrichten des privaten DNS-Peerings erstellt haben.
• TARGET_PROJECT ist das Projekt, in dem das VPC-Netzwerk gehostet wird.
• TARGET_NETWORK ist der Name des VPC-Netzwerk.

Sie können mehrere Agents so konfigurieren, dass sie entweder einen einzelnen, freigegebenen Netzwerkanhang oder eindeutige, dedizierte Netzwerkanhänge verwenden. Wenn Sie einen freigegebenen Netzwerkanhang verwenden möchten, geben Sie für jeden erstellten Agent denselben Netzwerkanhang in psc_interface_config an.

Vom Kunden verwaltete Verschlüsselungsschlüssel konfigurieren

Sie können einen benutzerdefinierten Schlüssel verwenden, um die ruhenden Daten Ihres Agents zu verschlüsseln. Weitere Informationen finden Sie unter Vom Kunden verwaltete Verschlüsselungsschlüssel (CMEK).

Wenn Sie den benutzerdefinierten Schlüssel (CMEK) für Ihren Agent konfigurieren möchten, müssen Sie beim Erstellen der Agent Engine-Instanz den Schlüsselressourcennamen für den Parameter encryption_spec angeben.

# The fully qualified key name
kms_key_name = "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"

remote_agent = client.agent_engines.create(
    agent=local_agent,
    config={
        "encryption_spec": {"kms_key_name": kms_key_name},
        # ... other parameters
    },
)