Agent bereitstellen

So stellen Sie einen Agenten in Vertex AI Agent Engine bereit:

  1. Agent für die Bereitstellung konfigurieren
  2. AgentEngine-Instanz erstellen
  3. Bereitgestelltem Agent Berechtigungen erteilen
  4. Agent-Ressourcen-ID abrufen

Sie können auch Agent Starter Pack-Vorlagen für die Bereitstellung verwenden.

Hinweise

Bevor Sie einen Agent bereitstellen, müssen Sie die folgenden Aufgaben ausführen:

  1. Richten Sie die Umgebung ein.
  2. Agent entwickeln

Agent für die Bereitstellung konfigurieren

Sie können die folgenden optionalen Konfigurationen vornehmen:

Paketanforderungen definieren

Geben Sie die Gruppe von Paketen 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 Requirements File Format 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.77.0).

ADK 

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

LangChain 

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

LangGraph 

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

AG2 

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

LlamaIndex

Die folgende Anleitung gilt für die LlamaIndex-Abfragepipeline:

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.88.0",
]

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

    requirements = [
    "google-cloud-aiplatform[agent_engines,adk]==1.88.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
    "cloudpickle==3.0",
]

  • 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 Anforderungsdateiformat 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"]

  • So nehmen Sie alle Dateien in einem gesamten Verzeichnis auf (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ängig ist, können Sie ihn auf None festlegen:

env_vars = None

Es gibt verschiedene Möglichkeiten, die Umgebungsvariablen anzugeben:

Wörterbuch 

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"
#

Wenn Sie auf ein Secret in Secret Manager verweisen und es als Umgebungsvariable (z. B. CLOUD_SQL_CREDENTIALS_SECRET) verfügbar machen möchten, folgen Sie zuerst der Anleitung zum Erstellen eines Secrets für CLOUD_SQL_CREDENTIALS_SECRET in Ihrem Projekt, bevor Sie die Umgebungsvariablen so angeben:

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

Dabei gilt:

  • SECRET_VERSION_ID ist die ID der Secret-Version.
  • SECRET_ID ist die ID des Secrets.

Im Agent-Code können Sie dann so auf das Secret verweisen:

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)

Liste 

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"],
#   }

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.

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"]}

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.

AgentEngine-Instanz erstellen

Wenn Sie den Agent in Vertex AI bereitstellen möchten, verwenden Sie agent_engines.create, um das local_agent-Objekt zusammen mit allen optionalen Konfigurationen zu übergeben:

remote_agent = agent_engines.create(
    local_agent,                    # Optional.
    requirements=requirements,      # Optional.
    extra_packages=extra_packages,  # Optional.
    gcs_dir_name=gcs_dir_name,      # Optional.
    display_name=display_name,      # Optional.
    description=description,        # Optional.
    env_vars=env_vars,              # Optional.
    build_options=build_options,    # Optional.
)

Die Bereitstellung dauert einige Minuten. In dieser Zeit werden die folgenden Schritte im Hintergrund ausgeführt:

  1. Ein Bundle der folgenden Artefakte wird lokal generiert:

    • *.pkl ist eine Pickle-Datei, die dem local_agent entspricht.
    • requirements.txt – eine Textdatei mit den Paketanforderungen.
    • dependencies.tar.gz eine TAR-Datei mit allen zusätzlichen Paketen.

  2. Das Bundle wird in Cloud Storage (im entsprechenden Ordner) hochgeladen, um die Artefakte bereitzustellen.

  3. Die Cloud Storage-URIs für die jeweiligen Artefakte werden in der PackageSpec angegeben.

  4. Der Vertex AI Agent Engine-Dienst empfängt die Anfrage, erstellt Container und startet HTTP-Server im Backend.

Die Bereitstellungslatenz hängt von der Gesamtzeit ab, die für die Installation der erforderlichen Pakete benötigt wird. Nach der Bereitstellung entspricht remote_agent einer Instanz von local_agent, die auf Vertex AI ausgeführt wird und abgefragt oder gelöscht werden kann. Es ist von lokalen Instanzen des Agents getrennt.

Berechtigungen für den bereitgestellten Agent erteilen

Wenn dem bereitgestellten Agent zusätzliche Berechtigungen erteilt werden müssen, folgen Sie der Anleitung unter Berechtigungen für Dienst-Agent einrichten.

Wenn Sie Secrets als Umgebungsvariablen definiert haben, müssen Sie die folgende Berechtigung erteilen:

  • Zugriffsperson für Secret Manager-Secret (roles/secretmanager.secretAccessor)

Agent-Ressourcen-ID abrufen

Jeder bereitgestellte Agent hat eine eindeutige Kennung. Führen Sie den folgenden Befehl aus, um die resource_name-ID für Ihren bereitgestellten Agent abzurufen:

remote_agent.resource_name

Die Antwort sollte in etwa so aussehen:

"projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"

Dabei gilt:

  • PROJECT_ID ist die Google Cloud Projekt-ID, in der der bereitgestellte Agent ausgeführt wird.

  • LOCATION ist die Region, in der der bereitgestellte Agent ausgeführt wird.

  • RESOURCE_ID ist die ID des bereitgestellten Agents als reasoningEngine-Ressource.

Nächste Schritte