Esegui il deployment di un agente

Per eseguire il deployment di un agente su Vertex AI Agent Engine, scegli tra due metodi principali:

  • 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 sorgente: questo metodo è ideale per i workflow 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.

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) Configurare 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 dai file di origine per workflow automatizzati basati su file.

Da un oggetto agente

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

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 ulteriori dettagli, consulta 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.

Dai 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 gli 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.

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 dell'applicazione agente in esecuzione su Vertex AI e può essere interrogata o eliminata.

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 ulteriori dettagli, consulta 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.

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

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

(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