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 dell'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. Sviluppa un agente.

Configurare l'agente per il deployment

Puoi apportare le seguenti configurazioni facoltative:

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

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 tramite pip o il percorso di un file che segue il formato del file dei requisiti. Segui queste best practice:

1. Blocca le versioni dei pacchetti per le 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, si riduce il numero di modifiche che causano interruzioni 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 per il framework, devi specificare la versione dell'SDK importata (ad esempio 1.77.0) durante lo sviluppo dell'agente.

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

Con il pacchetto requirements puoi anche:

• Imposta un limite superiore 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
  ]
  

• Fai riferimento alla versione di un pacchetto in un ramo o in 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
  

Definire pacchetti aggiuntivi

Puoi includere file o directory locali contenenti file di codice sorgente Python obbligatori locali. Rispetto ai requisiti del pacchetto, questa opzione consente di utilizzare utilità private sviluppate che non sono disponibili su PyPI o GitHub.

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

extra_packages = None

Con extra_packages puoi anche:

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

  extra_packages = ["agents/agent.py"]
  

• Includi l'insieme di file di un'intera directory (ad esempio agents/):

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

• Specifica i 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 il tuo agente dipende da variabili di ambiente, 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:

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

Definire 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 elementi di staging. Puoi impostare gcs_dir_name su None se non ti dispiace 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 eseguire la gestione temporanea dell'elemento:

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

Configura 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 dei parametri, consulta il riferimento all'API.

Crea un'istanza AgentEngine

Per eseguire il deployment dell'agente su Vertex AI, utilizza agent_engines.create per passare 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.
)

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

1. Viene generato localmente un bundle dei seguenti elementi:

   • *.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 su Cloud Storage (nella cartella corrispondente) per l'implementazione degli elementi.

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 contenitori e avvia i server HTTP sul backend.

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

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

Se è necessario concedere all'agente di servizio altre autorizzazioni, 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 seguente comando per recuperare l'identificatore resource_name dell'agente di cui è stato eseguito il deployment:

remote_agent.resource_name

La risposta dovrebbe avere il seguente aspetto:

"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

• Utilizza l'agente.
• Gestire gli agenti di cui è stato eseguito il deployment.
• Risolvi i problemi di implementazione di un agente.
• Richiedi assistenza.