A partire dal 29 aprile 2025, i modelli Gemini 1.5 Pro e Gemini 1.5 Flash non sono disponibili nei progetti che non li hanno mai utilizzati, inclusi i nuovi progetti. Per maggiori dettagli, vedi Versioni e ciclo di vita dei modelli.

Questa pagina è stata tradotta dall'API Cloud Translation.

Esegui il deployment di un agente

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

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

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

Prima di iniziare

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

Configura l'agente per il deployment

Puoi effettuare le seguenti configurazioni facoltative:

Requisiti del pacchetto
Pacchetti aggiuntivi
Variabili di ambiente
Opzioni di creazione
Cartella Cloud Storage
Metadati delle risorse

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:

Blocca le versioni dei pacchetti per build riproducibili. I pacchetti comuni da tenere sotto controllo includono i seguenti: google-cloud-aiplatform, cloudpickle, langchain, langchain-core, langchain-google-vertexai e pydantic.
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 Python wheel (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 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.

Per utilizzare gli script di installazione, crea una directory denominata installation_scripts e inserisci gli script shell all'interno della directory:

.
├── ...
└── 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"]}

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 staging. 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 la documentazione di riferimento dell'API.

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

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

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.
Il bundle viene caricato in Cloud Storage (nella cartella corrispondente) per la gestione temporanea degli artefatti.
Gli URI Cloud Storage per i rispettivi artefatti sono specificati in PackageSpec.
Il servizio Vertex AI Agent Engine riceve la richiesta, crea i container e avvia i server HTTP sul backend.

La latenza del 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 all'agente di cui è stato eseguito il deployment devono essere concesse autorizzazioni aggiuntive, segui le istruzioni riportate in Configurare le autorizzazioni dell'agente di servizio.

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"