Esegui il deployment di un agente

Per eseguire il deployment di un agente su Vertex AI Agent Engine, segui questi passaggi:

  1. Configura l'agente per il deployment.
  2. Crea un'istanza AgentEngine.
  3. Concedi le autorizzazioni all'agente di cui è stato eseguito il deployment.
  4. Ottieni l'ID risorsa dell'agente.

Puoi anche utilizzare i modelli Agent Starter Pack per il deployment.

Prima di iniziare

Prima di eseguire il deployment di un agente, assicurati di aver completato le seguenti attività:

  1. Configura l'ambiente.
  2. Sviluppare un agente.

Configura l'agente per il deployment

Puoi effettuare le seguenti configurazioni facoltative:

Definisci i requisiti del pacchetto

Fornisci l'insieme di pacchetti richiesti dall'agente per il deployment. Il set di pacchetti può essere un elenco di elementi da installare con pip o il percorso di un file che segue il formato del file Requirements. Utilizza le seguenti best practice:

  1. Blocca le versioni dei pacchetti per build riproducibili. I pacchetti comuni da monitorare includono i seguenti: google-cloud-aiplatform, cloudpickle, langchain, langchain-core, langchain-google-vertexai e pydantic.

  2. Riduci al minimo il numero di dipendenze nell'agente. In questo modo si riduce il numero di modifiche che causano errori durante l'aggiornamento delle dipendenze e dell'agente.

Se l'agente non ha dipendenze, puoi impostare requirements su None:

requirements = None

Se l'agente utilizza un modello specifico del framework, devi specificare la versione dell'SDK importata (ad esempio 1.77.0) durante lo sviluppo dell'agente.

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

Le seguenti istruzioni si riferiscono alla pipeline di query LlamaIndex:

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

Con il pacchetto requirements puoi anche:

  • Limita o blocca la versione di un determinato pacchetto (ad esempio 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",
]

  • Aggiungi altri pacchetti e vincoli:

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

  • Punta alla versione di un pacchetto su un ramo o una richiesta di pull di GitHub:

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

  • Mantieni l'elenco dei requisiti in un file (ad esempio path/to/requirements.txt):

    requirements = "path/to/requirements.txt"

    dove path/to/requirements.txt è un file di testo conforme al formato del file dei requisiti. Ad esempio:

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

Definisci pacchetti aggiuntivi

Puoi includere file o directory locali che contengono file di origine Python locali richiesti. Rispetto ai requisiti del pacchetto, questo ti consente di utilizzare le utilità private che hai sviluppato e che non sono altrimenti disponibili su PyPI o GitHub.

Se l'agente non richiede pacchetti aggiuntivi, puoi impostare extra_packages su None:

extra_packages = None

Puoi anche fare quanto segue con extra_packages:

  • Includi un singolo file (ad esempio agents/agent.py):

    extra_packages = ["agents/agent.py"]

  • Includi il set di file in un'intera directory (ad esempio, agents/):

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

  • Specifica i file binari wheel di Python (ad esempio, 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

Definisci le variabili di ambiente

Se ci sono variabili di ambiente da cui dipende il tuo agente, puoi specificarle nell'argomento env_vars=. Se l'agente non dipende da alcuna variabile di ambiente, puoi impostarlo su None:

env_vars = None

Per specificare le variabili di ambiente, sono disponibili diverse opzioni:

Dizionario 

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

Per fare riferimento a un secret in Secret Manager e renderlo disponibile come variabile di ambiente (ad esempio, CLOUD_SQL_CREDENTIALS_SECRET), segui prima le istruzioni per creare un secret per CLOUD_SQL_CREDENTIALS_SECRET nel tuo progetto, prima di specificare le variabili di ambiente come:

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

dove

  • SECRET_VERSION_ID è l'ID della versione del secret.
  • SECRET_ID è l'ID del secret.

Nel tuo codice agente, puoi fare riferimento al segreto nel seguente modo:

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)

Elenco 

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

Definisci controlli personalizzati delle risorse

Puoi specificare i controlli delle risorse di runtime per l'agente, ad esempio il numero minimo e massimo di istanze dell'applicazione, i limiti delle risorse per ogni container e la concorrenza per ogni container.

  • min_instances: il numero minimo di istanze dell'applicazione da mantenere in esecuzione in qualsiasi momento, con un intervallo di [0, 10]. Il valore predefinito è 1.

  • max_instances: il numero massimo di istanze dell'applicazione che possono essere avviate per gestire l'aumento del traffico, con un intervallo di [1, 1000]. Il valore predefinito è 100. Se VPC-SC o PSC-I è abilitato, l'intervallo accettabile è [1, 100].

  • resource_limits: Limiti delle risorse per ogni container. Sono supportate solo le chiavi cpu e memory. Il valore predefinito è {"cpu": "4", "memory": "4Gi"}.

  • container_concurrency: Concorrenza per ogni contenitore e server agent. Il valore consigliato è 2 * cpu + 1. Il valore predefinito è 9.

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

Definisci le opzioni di build

Puoi specificare le opzioni di build per l'agente, ad esempio gli script di installazione da eseguire durante la creazione dell'immagine container dell'agente. Ciò è utile per installare dipendenze di sistema (ad esempio, gcloud cli, npx) o altre configurazioni personalizzate. Gli script vengono eseguiti con autorizzazioni root.

Per utilizzare gli script di installazione, crea una directory denominata installation_scripts e inserisci gli script shell al suo interno:

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

Successivamente, specifica la directory installation_scripts in extra_packages e i percorsi degli script in build_options:

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

Puoi utilizzare uno dei seguenti script di installazione comuni:

install_npx.sh 

#!/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

install_uvx.sh 

#!/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

install_gcloud_cli.sh 

#!/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

Definisci una cartella Cloud Storage

Gli artefatti di staging vengono sovrascritti se corrispondono a una cartella esistente in un bucket Cloud Storage. Se necessario, puoi specificare la cartella Cloud Storage per gli artefatti di gestione temporanea. Puoi impostare gcs_dir_name su None se non ti preoccupa la potenziale sovrascrittura dei file nella cartella predefinita:

gcs_dir_name = None

Per evitare di sovrascrivere i file (ad esempio per ambienti diversi come sviluppo, gestione temporanea e produzione), puoi configurare la cartella corrispondente e specificare la cartella in cui preparare l'artefatto:

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

Se vuoi o devi evitare collisioni, puoi generare un uuid casuale:

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

Configurare i metadati delle risorse

Puoi impostare i metadati sulla risorsa ReasoningEngine:

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

Per un insieme completo di parametri, consulta il Riferimento API.

Configura un account di servizio personalizzato

Puoi configurare un account di servizio personalizzato come identità dell'agente di cui è stato eseguito il deployment, anziché l'identità predefinita.

A questo scopo, specifica l'email del tuo account di servizio personalizzato come service_account quando crei o aggiorni l'istanza di Agent Engine, ad esempio:

# Create a new instance
agent_engines.create(
  local_agent=<my-agent>,
  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}"
agent_engines.update(
  resource_name,
  service_account="my-new-custom-service-account@my-project.iam.gserviceaccount.com",
  ...
)

Configura l'interfaccia Private Service Connect

Vertex AI Agent Engine supporta l'interfaccia Private Service Connect e il peering DNS per il traffico in uscita privato e sicuro.

Perché utilizzare un'interfaccia Private Service Connect?

L'agente viene implementato in una rete sicura e gestita da Google senza accesso alla rete Virtual Private Cloud (VPC). Un'interfaccia PSC crea un bridge privato e sicuro alla tua rete, il che la rende la soluzione consigliata per interagire con i servizi ospitati privatamente nei tuoi ambienti VPC, on-premise e multicloud.

Oltre a fornire l'accesso privato, questa connessione è necessaria anche per abilitare l'accesso a internet quando utilizzi i Controlli di servizio VPC. Vedi Accesso a internet pubblico.

Come funziona

Quando configuri un'interfaccia PSC, Agent Engine esegue il provisioning di un'interfaccia in un progetto tenant di proprietà di Google in cui viene eseguito l'agente. Questa interfaccia si connette direttamente a un collegamento di rete nel tuo progetto. Tutto il traffico tra l'agente e il VPC viene trasferito in modo sicuro all'interno della rete di Google, senza mai attraversare la rete internet pubblica.

Accesso a internet pubblico

La capacità dell'agente di accedere a internet pubblico dipende dalla configurazione di sicurezza del tuo progetto, in particolare se utilizzi Controlli di servizio VPC.

Comportamento predefinito (senza Controlli di servizio VPC)
  • Quando configuri l'agente solo con un'interfaccia PSC, mantiene l'accesso a internet predefinito. Questo traffico in uscita esce direttamente dall'ambiente sicuro e gestito da Google in cui viene eseguito l'agente.
Con i Controlli di servizio VPC
  • Quando il progetto fa parte di un perimetro di Controlli di servizio VPC, l'accesso a internet predefinito dell'agente viene bloccato dal perimetro per impedire l'esfiltrazione di dati. Per consentire all'agente di accedere a internet pubblico in questo scenario, devi configurare esplicitamente un percorso di uscita sicuro che indirizzi il traffico tramite il tuo VPC. Il modo consigliato per farlo è configurare un server proxy all'interno del perimetro VPC e creare un gateway Cloud NAT per consentire alla VM proxy di accedere a internet.

Prima di iniziare

Per abilitare la connettività privata per l'agente di cui è stato eseguito il deployment utilizzando l'interfaccia Private Service Connect, devi configurare una rete VPC, una subnet e un collegamento di rete nel tuo progetto utente.

Requisiti per l'intervallo IP della subnet

Agent Engine consiglia una subnet /28.

La subnet dell'allegato di rete supporta indirizzi RFC 1918 e non RFC 1918, ad eccezione delle subnet 100.64.0.0/10 e 240.0.0.0/4. Agent Engine può connettersi solo a intervalli di indirizzi IP RFC 1918 instradabili dalla rete specificata. Agent Engine non può raggiungere un indirizzo IP pubblico utilizzato privatamente o questi intervalli non RFC 1918:

  • 100.64.0.0/10
  • 192.0.0.0/24
  • 192.0.2.0/24
  • 198.18.0.0/15
  • 198.51.100.0/24
  • 203.0.113.0/24
  • 240.0.0.0/4

Per maggiori dettagli sulla configurazione, consulta Configurare un'interfaccia Private Service Connect.

Utilizzo con VPC condiviso

Puoi utilizzare l'interfaccia Private Service Connect con un'architettura VPC condiviso, che ti consente di creare Agent Engine in un progetto di servizio utilizzando una rete di un progetto host centrale.

Quando configuri PSC-I in un ambiente VPC condiviso, crea la subnet nel progetto host, quindi crea il collegamento di rete nel progetto di servizio.

Affinché il progetto di servizio utilizzi la rete del progetto host, devi concedere l'autorizzazione IAM appropriata. L'agente di servizio Vertex AI del tuo progetto di servizio necessita del ruolo Utente di rete Compute (roles/compute.networkUser) nel progetto host.

Deployment di agenti con l'interfaccia Private Service Connect

Una volta configurato l'allegato di rete, puoi specificarlo durante la creazione dell'istanza AgentEngine.

remote_agent = agent_engines.create(
    agent_engine=local_agent,
    psc_interface_config={
      "network_attachment": "NETWORK_ATTACHMENT",
    },
)

dove

  • NETWORK_ATTACHMENT è il nome o il percorso completo del collegamento di rete che hai creato.

Utilizzare i collegamenti di rete con più agenti

Hai la flessibilità di decidere in che modo i tuoi agenti condividono le risorse di rete. Puoi configurare più agenti in modo che utilizzino un singolo collegamento di rete condiviso o collegamenti di rete dedicati univoci.

Per utilizzare un collegamento di rete condiviso, fornisci lo stesso collegamento di rete in psc_interface_config per ogni agente che crei.

Peering DNS

Mentre l'interfaccia Private Service Connect fornisce il percorso di rete sicuro, il peering DNS fornisce il meccanismo di Service Discovery. Con PSC-I, devi comunque conoscere l'indirizzo IP specifico del servizio nella rete VPC. Sebbene sia possibile connettersi ai servizi utilizzando i relativi indirizzi IP interni, questa operazione non è consigliata per i sistemi di produzione in cui gli IP possono cambiare. Con il peering DNS, l'agente di cui è stato eseguito il deployment può connettersi ai servizi nella tua rete VPC utilizzando nomi DNS stabili e leggibili anziché indirizzi IP. Il peering DNS consente agli agenti di cui è stato eseguito il deployment di risolvere i nomi DNS utilizzando i record di una zona privata Cloud DNS nel tuo VPC. Consulta Configurare un peering DNS privato.

Una volta configurato il peering DNS privato, puoi specificarlo durante la creazione dell'istanza AgentEngine.

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

dove

  • NETWORK_ATTACHMENT è il nome o il percorso completo del collegamento di rete che hai creato.
  • DOMAIN_SUFFIX è il nome DNS della zona DNS privata di Cloud DNS che hai creato durante la configurazione del peering DNS privato.
  • TARGET_PROJECT è il progetto che ospita la rete VPC.
  • TARGET_NETWORK è il nome della rete VPC.

Configurare le chiavi di crittografia gestite dal cliente

Puoi utilizzare una chiave personalizzata per criptare i dati dell'agente at-rest. Per saperne di più, consulta Agent Engine Chiavi di crittografia gestite dal cliente (CMEK).

Per configurare la chiave personalizzata (CMEK) per l'agente, devi fornire il nome della risorsa chiave al parametro encryption_spec quando crei l'istanza di Agent Engine.

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

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

Crea un'istanza AgentEngine

Per eseguire il deployment dell'agente su Vertex AI, utilizza agent_engines.create per trasmettere l'oggetto local_agent insieme a eventuali configurazioni facoltative:

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.
    service_account=service_account, # Optional.
    min_instances=min_instances,     # Optional.
    max_instances=max_instances,     # Optional.
    resource_limits=resource_limits, # Optional.
    container_concurrency=container_concurrency, # Optional
    encryption_spec=encryption_spec, # Optional.
)

Il deployment richiede alcuni minuti, durante i quali vengono eseguiti in background i seguenti passaggi:

  1. Viene generato localmente un bundle dei seguenti artefatti:

  2. Il bundle viene caricato in Cloud Storage (nella cartella corrispondente) per la gestione temporanea degli artefatti.

  3. Gli URI Cloud Storage per i rispettivi artefatti sono specificati in PackageSpec.

  4. Il servizio Vertex AI Agent Engine riceve la richiesta, crea i container e avvia i server HTTP sul backend.

La latenza di deployment dipende dal tempo totale necessario per installare i pacchetti richiesti. Una volta eseguito il deployment, remote_agent corrisponde a un'istanza di local_agent in esecuzione su Vertex AI e può essere sottoposta a query o eliminata. È separato dalle istanze locali dell'agente.

Concedi le autorizzazioni dell'agente di cui è stato eseguito il deployment

Se è necessario concedere ulteriori autorizzazioni all'agente di cui è stato eseguito il deployment, segui le istruzioni riportate in Configurare l'identità e le autorizzazioni per l'agente.

Se hai definito i secret come variabili di ambiente, devi concedere la seguente autorizzazione:

  • Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)

Recuperare l'ID risorsa dell'agente

Ogni agente di cui è stato eseguito il deployment ha un identificatore univoco. Puoi eseguire il comando seguente per ottenere l'identificatore resource_name per l'agente di cui è stato eseguito il deployment:

remote_agent.resource_name

La risposta dovrebbe essere simile alla seguente stringa:

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

dove

  • PROJECT_ID è l' Google Cloud ID progetto in cui viene eseguito l'agente di cui è stato eseguito il deployment.

  • LOCATION è la regione in cui viene eseguito l'agente di cui è stato eseguito il deployment.

  • RESOURCE_ID è l'ID dell'agente di cui è stato eseguito il deployment come risorsa reasoningEngine.

Passaggi successivi