Esegui il deployment di un agente

Per eseguire il deployment di un agente su Vertex AI Agent Engine, scegli uno dei seguenti metodi:

  • Deployment da un oggetto agente: ideale per lo sviluppo interattivo in ambienti come Colab, che consente il deployment di oggetti local_agent in memoria. Questo metodo è più adatto agli agenti con strutture che non contengono componenti complessi e non serializzabili.
  • Deployment dai file di origine: questo metodo è ideale per i flussi di lavoro automatizzati, come le pipeline CI/CD e gli strumenti Infrastructure as Code come Terraform, consentendo deployment completamente dichiarativi e automatizzati. Esegue il deployment dell'agente direttamente dal codice sorgente locale e non richiede un bucket Cloud Storage.
  • Esegui il deployment da Dockerfile: questo metodo è simile a quello per il deployment dai file di origine. Esegui il deployment dell'agente direttamente dal codice sorgente locale. Non hai bisogno di un bucket Cloud Storage. Questo metodo è appropriato se devi definire e controllare il server API di cui viene eseguito il deployment.
  • Deployment dall'immagine container: questo metodo è simile a quello per il deployment da Dockerfile. Esegui il deployment di un'immagine container ospitata in Artifact Registry. Utilizza questo metodo se hai bisogno di controllare il processo di compilazione per l'immagine container e ridurre la latenza di deployment.
  • Esegui il deployment da Developer Connect: consigliato per i progetti gestiti in un repository Git collegato tramite Developer Connect. Questo metodo semplifica il deployment degli agenti direttamente dal codice sorgente e supporta in modo nativo il controllo delle versioni, la collaborazione del team e le pipeline CI/CD. Prima di utilizzare questo metodo, configura il link al repository Git seguendo le istruzioni riportate in Configurare il link al repository Git di Developer Connect.

Per iniziare:

  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.

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) Configura l'agente per il deployment

Puoi effettuare le seguenti configurazioni facoltative per il tuo agente:

Crea un'istanza AgentEngine

Questa sezione descrive come creare un'istanza AgentEngine per il deployment di un agente.

Per eseguire il deployment di un agente su Vertex AI Agent Engine, puoi scegliere uno dei seguenti metodi:

  • Deployment da un oggetto agente per lo sviluppo interattivo.
  • Deployment da Developer Connect per i workflow basati su Git.
  • Deployment dai file sorgente o da Dockerfile per i flussi di lavoro basati su file.

  • Deployment dall'immagine container per i workflow basati su immagini.

Oggetto Python

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.
        "identity_type": identity_type,                 # 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.
        "agent_framework": agent_framework,             # 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.

Developer Connect

Per il deployment da Developer Connect su Vertex AI, utilizza client.agent_engines.create fornendo developer_connect_source, entrypoint_module e entrypoint_object nel dizionario di configurazione, insieme ad altre configurazioni facoltative. Questo metodo ti consente di eseguire il deployment del codice direttamente da un repository Git connesso.

remote_agent = client.agent_engines.create(
    config={
        "developer_connect_source": {                   # Required.
            "git_repository_link": "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID/gitRepositoryLinks/REPO_ID",
            "revision": "main",
            "dir": "path/to/dir",
        },
        "entrypoint_module": "agent",                   # Required.
        "entrypoint_object": "root_agent",              # Required.
        "requirements_file": "requirements.txt",        # Optional.
        # Other optional configs:
        # "env_vars": {...},
        # "service_account": "...",
    },
)

I parametri per il deployment di Developer Connect sono:

  • developer_connect_source (obbligatorio, dict): la configurazione per il recupero del codice sorgente. Per maggiori dettagli, consulta Configurare il link al repository Git di Developer Connect.
    • git_repository_link (obbligatorio, str): il nome della risorsa del link al repository Git di Developer Connect.
    • revision (obbligatorio, str): la revisione da recuperare (branch, tag o SHA di commit).
    • dir (obbligatorio, str): la directory principale del codice dell'agente all'interno del repository.
  • entrypoint_module (obbligatorio, str): il nome del modulo Python contenente l'entry point dell'agente, relativo alla directory specificata in developer_connect_source.dir.
  • entrypoint_object (obbligatorio, str): il nome dell'oggetto chiamabile all'interno di entrypoint_module che rappresenta l'applicazione dell'agente (ad esempio, root_agent).
  • requirements_file (facoltativo, str): il percorso di un file dei requisiti pip relativo alla radice dell'origine. Il valore predefinito è requirements.txt.

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

  1. Il servizio Vertex AI Agent Engine recupera il codice sorgente dalla revisione del repository Git specificata.
  2. Il servizio installa le dipendenze da requirements_file (se fornito).
  3. Il servizio avvia l'applicazione agente utilizzando entrypoint_module e entrypoint_object specificati.

File di origine

Per il deployment dai file di origine su Vertex AI, utilizza client.agent_engines.create fornendo source_packages, entrypoint_module, entrypoint_object e class_methods nel dizionario di configurazione, insieme ad altre configurazioni facoltative. Con questo metodo, non è necessario passare un oggetto agente o un bucket Cloud Storage.

remote_agent = client.agent_engines.create(
    config={
        "source_packages": source_packages,             # Required.
        "entrypoint_module": entrypoint_module,         # Required.
        "entrypoint_object": entrypoint_object,         # Required.
        "class_methods": class_methods,                 # Required.
        "requirements_file": requirements_file,         # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # 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.
        "agent_framework": agent_framework,             # Optional.
    },
)

I parametri per il deployment dell'origine in linea sono:

  • source_packages (obbligatorio, list[str]): un elenco di percorsi di file o directory locali da includere nel deployment. Le dimensioni totali dei file e delle directory in source_packages non devono superare 8 MB.
  • entrypoint_module (obbligatorio, str): il nome completo del modulo Python contenente l'entry point dell'agente (ad esempio, agent_dir.agent).
  • entrypoint_object (obbligatorio, str): il nome dell'oggetto chiamabile all'interno di entrypoint_module che rappresenta l'applicazione dell'agente (ad esempio, root_agent).

  • class_methods (obbligatorio, list[dict]): un elenco di dizionari che definiscono i metodi esposti dell'agente. Ogni dizionario include un campo name (obbligatorio), un campo api_mode (obbligatorio) e un campo parameters. Per ulteriori informazioni sui metodi per un agente personalizzato, consulta Elenco delle operazioni supportate.

    Ad esempio:

      "class_methods": [
      {
          "name": "method_name",
          "api_mode": "", # Possible options are: "", "async", "async_stream", "stream", "bidi_stream"
          "parameters": {
              "type": "object",
              "properties": {
                  "param1": {"type": "string", "description": "Description of param1"},
                  "param2": {"type": "integer"}
              },
              "required": ["param1"]
          }
      }
  ]
  ```

  • requirements_file (facoltativo, str): il percorso di un file dei requisiti pip all'interno dei percorsi specificati in source_packages. Il valore predefinito è requirements.txt nella directory radice dell'origine pacchettizzata.

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

  1. L'SDK Vertex AI crea un archivio tar.gz dei percorsi specificati in source_packages.
  2. Questo archivio viene codificato e inviato direttamente all'API Vertex AI.
  3. Il servizio Vertex AI Agent Engine riceve l'archivio, lo estrae, installa le dipendenze da requirements_file (se fornito) e avvia l'applicazione dell'agente utilizzando entrypoint_module e entrypoint_object specificati.

Di seguito è riportato un esempio di deployment di un agente dai file di origine:

from google.cloud.aiplatform import vertexai

# Example file structure:
# /agent_directory
#     ├── agent.py
#     ├── requirements.txt

# Example agent_directory/agent.py:
# class MyAgent:
#     def ask(self, question: str) -> str:
#         return f"Answer to {question}"
# root_agent = MyAgent()

remote_agent = client.agent_engines.create(
  config={
      "display_name": "My Agent",
      "description": "An agent deployed from a local source.",
      "source_packages": ["agent_directory"],
      "entrypoint_module": "agent_directory.agent",
      "entrypoint_object": "root_agent",
      "requirements_file": "requirements.txt",
      "class_methods": [
          {"name": "ask", "api_mode": "", "parameters": {
              "type": "object",
              "properties": {
                  "question": {"type": "string"}
              },
              "required": ["question"]
          }},
      ],
      # Other optional configs:
      # "env_vars": {...},
      # "service_account": "...",
  }
)

Dockerfile

Per eseguire il deployment da Dockerfile su Vertex AI, segui un approccio simile all'esecuzione del deployment dai file di origine. L'unico punto che cambia durante il deployment è la sostituzione di entrypoint_module, entrypoint_object e (facoltativamente) requirements_file nella configurazione con un image_spec.

Di seguito è riportato un esempio di deployment di un agente utilizzando un Dockerfile:

from google.cloud.aiplatform import vertexai

# Example file structure:
# /current_directory
#     ├── agent.py
#     ├── main.py
#     ├── requirements.txt
#     ├── Dockerfile

remote_agent = client.agent_engines.create(
    config={
        "source_packages": [
            "agent.py",
            "main.py",
            "requirements.txt",
            "Dockerfile",
        ],
        "image_spec": {},  # tells AgentEngine to use the Dockerfile
        # Other optional configs
    }
)

Immagine container

Per eseguire il deployment da un'immagine container, segui innanzitutto le istruzioni di configurazione per Bring your own container, assicurandoti di installare una versione di google-cloud-aiplatform che soddisfi >=1.144. Quindi, esegui il seguente codice:

remote_agent = client.agent_engines.create(
    config={
        "container_spec": {
            "image_uri": "CONTAINER_IMAGE_URI",
        },
        # Other optional configs
    },
)

Dove CONTAINER_IMAGE_URI corrisponde all'URI dell'immagine container in Artifact Registry (ad esempio us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag).

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 interrogata o eliminata.

L'oggetto remote_agent corrisponde a una classe AgentEngine che contiene quanto segue:

(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 utilizzare AgentEngine.operation_schemas 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:

(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