Esegui il deployment di un agente

Per eseguire il deployment di un agente su Agent Engine:

  1. (Facoltativo) Definisci i requisiti del pacchetto
  2. (Facoltativo) Definisci i file di origine
  3. (Facoltativo) Organizza la directory Cloud Storage
  4. (Facoltativo) Definisci i metadati della risorsa
  5. Crea un'istanza AgentEngine

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.

Passaggio 1: definisci i requisiti del pacchetto

Fornisci l'insieme di pacchetti richiesti dall'agente per il deployment. Può essere un elenco di elementi da installare tramite pip o il percorso di un file che segue il formato del file dei requisiti.

Se l'agente non ha dipendenze, puoi impostarlo su Nessuno:

requirements = None

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

LangChain 

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

LangGraph 

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

[Facoltativo] Vincoli di versione

Se vuoi o devi impostare un limite superiore o bloccare la versione di un determinato pacchetto (ad es. google-cloud-aiplatform):

requirements = [
    # See https://pypi.org/project/google-cloud-aiplatform for the latest version.
    "google-cloud-aiplatform[agent_engines,langgraph]==1.77.0",
]

Puoi aggiungere altri pacchetti e vincoli all'elenco:

requirements = [
    "google-cloud-aiplatform[agent,langgraph]==1.75.0",
    "cloudpickle==3.0", # new
]

[Facoltativo] Branch di sviluppo

Puoi fare riferimento alla versione di un pacchetto che si trova in un ramo o in una richiesta di pull di GitHub, ad esempio:

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

[Facoltativo] Formato del file dei requisiti

Puoi gestire l'elenco dei requisiti in un file (ad es. 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,langchain]
cloudpickle==3.0

Passaggio 2: pacchetti extra

Puoi includere file o directory locali contenenti i file di codice sorgente Python locali richiesti. Rispetto ai requisiti del pacchetto, questo ti consentirà di utilizzare utilità private che hai sviluppato e che non sono altrimenti disponibili su PyPI o GitHub.

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

extra_packages = None

[Facoltativo] File e directory

Per includere un singolo file (ad es. agents/agent.py), puoi aggiungerlo all'elenco:

extra_packages = ["agents/agent.py"]

Per includere l'insieme di file di un'intera directory (ad es. agents/), puoi specificare la directory:

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

[Facoltativo] Binari della ruota

Puoi includere i binari di Python Wheel (ad es. path/to/python_package.whl) e specificarli nei requisiti del pacchetto:

requirements = [
    "google-cloud-aiplatform[agent,langgraph]",
    "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

Passaggio 3: directory Cloud Storage

Gli artefatti di staging verranno sovrascritti se corrispondono a un sottobucket esistente (una cartella in un bucket Cloud Storage). Se necessario, puoi specificare il sottobucket per gli elementi di staging. Questo passaggio è facoltativo e puoi impostarlo su None se non ti dispiace la potenziale sovrascrittura dei file nel subbucket predefinito:

gcs_dir_name = None

Per evitare di sovrascrivere i file (ad es. per ambienti diversi come dev, staging e prod), puoi configurare i sottobucket corrispondenti e specificare il sottobucket in cui eseguire lo staging dell'elemento, ad esempio:

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

Se vuoi o devi evitare collisioni, puoi generare un UUID casuale, ad esempio:

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

Passaggio 4: metadati delle risorse

Puoi impostare i metadati sulla risorsa ReasoningEngine che viene creata in Vertex AI, ad esempio:

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

Passaggio 5: crea un'istanza AgentEngine

Per eseguire il deployment dell'applicazione su Vertex AI, utilizza agent_engines.create e passa l'oggetto come parametro:

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

L'esecuzione del deployment richiede alcuni minuti. Quando esegui il deployment dell'agente,

  1. Viene generato localmente un insieme di elementi, tra cui:
  2. Il bundle viene caricato su Cloud Storage (nel sottobucket corrispondente) per l'implementazione degli elementi.
  3. Gli URI Cloud Storage per i rispettivi artefatti sono specificati in PackageSpec.
  4. Il servizio 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 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.

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

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'applicazione. In questo modo si riduce il numero di modifiche che comportano interruzioni durante l'aggiornamento delle dipendenze e diventa più facile aggiornare l'applicazione nel tempo per le funzionalità più recenti.

Esegui il deployment in produzione con Agent Starter Pack

L'Agent Starter Pack è una raccolta di modelli di agenti di IA generativa pronti per la produzione creati per Vertex AI Agent Engine. Accelera il deployment fornendo:

  • Modelli di agenti predefiniti: ReAct, RAG, multi-agente e altro ancora.
  • Playground interattivo: testa e interagisci con il tuo agente.
  • Infrastruttura automatizzata: utilizza Terraform per una gestione semplificata delle risorse.
  • Pipeline CI/CD: workflow di deployment automatico che sfruttano Cloud Build.
  • Osservabilità: include il supporto integrato per Cloud Trace e Cloud Logging.

Per iniziare: Guida rapida

Passaggi successivi