Esegui il deployment di un agente

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

1. Completa i prerequisiti.
2. (Facoltativo) Configura l'agente per il deployment.
3. Crea un'istanza AgentEngine.
4. (Facoltativo) Ottieni l'ID risorsa dell'agente.
5. (Facoltativo) Elenca le operazioni supportate.
6. (Facoltativo) Concedi le autorizzazioni all'agente di cui è stato eseguito il deployment.

Puoi anche utilizzare i modelli dello starter pack dell'agente per il deployment.

Nota: il deployment di Vertex AI Agent Engine supporta solo Python.

Prerequisiti

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

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

(Facoltativo) Configurare l'agente per il deployment

Puoi effettuare le seguenti configurazioni facoltative per il tuo agente:

Definisci i requisiti del pacchetto

Fornisci l'insieme di pacchetti richiesti dall'agente per il deployment. L'insieme 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: 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, il numero di modifiche che causano errori durante l'aggiornamento delle dipendenze e dell'agente viene ridotto.

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.112.0) durante lo sviluppo dell'agente.

ADK

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

A2A

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

requirements = [
    "google-cloud-aiplatform[agent_engines]",
    "a2a-sdk>=0.3.4"
    # 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

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Le seguenti istruzioni sono per la 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.112.0",
    ]
    

• Aggiungi altri pacchetti e vincoli:

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

• 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 i file sorgente Python locali richiesti. Rispetto ai requisiti del pacchetto, questo ti consente di utilizzare le utilità private che hai sviluppato e che altrimenti non sono 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 l'agente, puoi specificarle nell'argomento env_vars=. Se l'agente non dipende da alcuna variabile di ambiente, puoi impostarlo su None:

env_vars = None

Avviso:non devi impostare le seguenti variabili di ambiente: GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_QUOTA_PROJECT, GOOGLE_CLOUD_LOCATION, PORT, K_SERVICE, K_REVISION, K_CONFIGURATION e GOOGLE_APPLICATION_CREDENTIALS. Inoltre, devi evitare il prefisso GOOGLE_CLOUD_AGENT_ENGINE per evitare conflitti di denominazione con le variabili di ambiente di Vertex AI Agent Engine.

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.

Nota:puoi fare riferimento solo ai secret (e alle relative versioni) gestiti nello stesso progetto dell'agente di cui è stato eseguito il deployment.

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

Nota:questa opzione non supporta l'integrazione di Secret Manager. Se devi specificare i secret gestiti, devi specificare le variabili di ambiente come dizionario.

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

Devi anche seguire le istruzioni riportate in Configurare l'identità e le autorizzazioni per l'agente per concedere all'agente l'autorizzazione Secret Manager Secret Accessor (roles/secretmanager.secretAccessor).

Definisci controlli personalizzati delle risorse

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

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.

  Nota: mentre questa funzionalità è in anteprima, anche se configuri un numero minimo di istanze più elevato, non ti verrà addebitato il tempo in cui un agente è inattivo. Questo comportamento di fatturazione è soggetto a modifiche in futuro.

• 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 supportati solo i tasti cpu e memory. Il valore predefinito è {"cpu": "4", "memory": "4Gi"}.

  • Gli unici valori supportati per cpu sono 1, 2, 4, 6 e 8. Per saperne di più, consulta Configurare l'allocazione della CPU.

  • Gli unici valori supportati per memory sono 1Gi, 2Gi, ... 32Gi.

  • Per la CPU richiesta per diversi valori di memoria, consulta Configurare i limiti di memoria.

• container_concurrency: Concorrenza per ogni container e server agente. Il valore consigliato è 2 * cpu + 1. Il valore predefinito è 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
    }
)

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 le 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 organizzare temporaneamente 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())

Definisci il nome visualizzato

Puoi impostare il nome visualizzato per la risorsa ReasoningEngine:

display_name = "Currency Exchange Rate Agent (Staging)"

Definisci la descrizione

Puoi impostare la descrizione della risorsa ReasoningEngine:

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

Definisci le etichette

Puoi impostare le etichette della risorsa ReasoningEngine come dizionario di coppie di stringhe chiave-valore. Di seguito è riportato un esempio:

labels = {"author": "username", "version": "latest"}

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 durante la creazione o l'aggiornamento dell'istanza di Agent Engine, ad esempio:

# Create a new instance
client.agent_engines.create(
    agent=local_agent,
    config={
        "service_account": "[e-mail]",
        # ...
    },
)

# 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": "[e-mail]",
        # ...
    },
)

Nota:specifica solo l'email del account di servizio, non l'URI della risorsa completo, ad esempio projects/{project_id}/serviceAccounts/{service_account_email}.

Configura l'interfaccia Private Service Connect

Se hai configurato l'interfaccia Private Service Connect e il peering DNS, puoi specificare l'allegato di rete e il peering DNS privato durante il deployment dell'agente:

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

dove

• NETWORK_ATTACHMENT è il nome o il percorso completo del collegamento di rete. Se il collegamento di rete viene creato in un progetto (ad esempio il progetto host VPC condiviso) diverso da quello in cui utilizzi Agent Engine, devi passare il percorso completo del collegamento di rete.
• 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. Può essere diverso dal progetto di collegamento alla rete.
• TARGET_NETWORK è il nome della rete VPC.

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.

Configurare le chiavi di crittografia gestite dal cliente

Puoi utilizzare una chiave personalizzata per criptare i dati dell'agente at-rest. Per ulteriori dettagli, consulta la sezione 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 = client.agent_engines.create(
    agent=local_agent,
    config={
        "encryption_spec": {"kms_key_name": kms_key_name},
        # ... other parameters
    },
)

Crea un'istanza AgentEngine

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

remote_agent = client.agent_engines.create(
    agent=local_agent,                                  # Optional.
    config={
        "requirements": requirements,                   # Optional.
        "extra_packages": extra_packages,               # Optional.
        "gcs_dir_name": gcs_dir_name,                   # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # 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:

   • *.pkl un file pickle corrispondente a local_agent.
   • requirements.txt un file di testo contenente i requisiti del pacchetto.
   • dependencies.tar.gz un file tar contenente eventuali pacchetti aggiuntivi.

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.

L'oggetto remote_agent corrisponde a una classe AgentEngine che contiene i seguenti attributi:

• un remote_agent.api_resource con informazioni sull'agente di cui è stato eseguito il deployment. Puoi anche chiamare agent.operation_schemas() per restituire l'elenco delle operazioni supportate dall'agente. Per maggiori dettagli, vedi Elenco delle operazioni supportate.
• un remote_agent.api_client che consente interazioni di servizio sincrone.
• un remote_agent.async_api_client che consente interazioni di servizio asincrone.

(Facoltativo) Recupera l'ID risorsa agente

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

remote_agent.api_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.

(Facoltativo) Elenca le operazioni supportate

Ogni agente di cui è stato eseguito il deployment ha un elenco di operazioni supportate. Puoi eseguire questo comando per ottenere l'elenco delle operazioni supportate dall'agente di cui è stato eseguito il deployment:

remote_agent.operation_schemas()

Lo schema di ogni operazione è un dizionario che documenta le informazioni di un metodo per l'agente che puoi chiamare. Il set di operazioni supportate dipende dal framework che hai utilizzato per sviluppare l'agente:

• Agent Development Kit
• Agent2Agent
• LangChain
• LangGraph
• AG2
• LlamaIndex
• Personalizzato

(Facoltativo) 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.

Passaggi successivi

• Utilizzare l'agente.
• Gestisci gli agenti di cui è stato eseguito il deployment.
• Risolvi i problemi relativi al deployment di un agente.
• Richiedere assistenza.