Esegui il deployment di un agente

Il deployment di un agente su Agent Runtime lo rende disponibile da remoto per gestire le richieste. Questo documento spiega i modi per eseguire il deployment di un agente in base al tuo flusso di lavoro di sviluppo: da un oggetto di esecuzione, file di origine locali, un Dockerfile, un'immagine container ospitata in Artifact Registry o direttamente tramite un repository Git connesso.

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

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.

Puoi utilizzare questo metodo di deployment solo con Python.

File di origine

Ideale per workflow automatizzati come pipeline CI/CD e strumenti Infrastructure as Code come Terraform, che consentono deployment completamente dichiarativi e automatizzati. Esegue il deployment dell'agente direttamente dal codice sorgente locale e non richiede un bucket Cloud Storage.

Puoi utilizzare questo metodo di deployment solo con Python.

Dockerfile

Simile al deployment dai file di origine. Esegui il deployment dell'agente direttamente dal codice sorgente locale senza bisogno di un bucket Cloud Storage. Questo metodo è appropriato se devi definire e controllare il server API di cui è stato eseguito il deployment. Il container di cui è stato eseguito il deployment deve rispettare il contratto runtime.

Puoi utilizzare questo metodo di deployment con qualsiasi lingua. Gli esempi in questa pagina utilizzano Python.

Immagine container

Simile al 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 build per l'immagine container e ridurre la latenza di deployment. L'immagine container deve rispettare il contratto runtime.

Puoi utilizzare questo metodo di deployment con qualsiasi lingua. Gli esempi in questa pagina utilizzano Python.

SDK Agent Platform

Ideale per lo sviluppo interattivo in ambienti come Colab, in quanto 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.

Per iniziare:

  1. Completa i prerequisiti
  2. (Facoltativo) Configura l'agente per il deployment
  3. Crea un'istanza di Agent Platform
  4. (Facoltativo) Recuperare l'ID risorsa dell'agente
  5. (Facoltativo) Elenca le operazioni supportate
  6. (Facoltativo) Concedi le autorizzazioni all'agente di cui è stato eseguito il deployment

Prerequisiti

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

  1. Configura l'ambiente
  2. Crea un agente

(Facoltativo) Configura l'agente per il deployment

Puoi effettuare configurazioni facoltative per l'agente. Gli esempi in questa sezione utilizzano Python.

Crea un'istanza di Agent Platform

Questa sezione descrive come creare un'istanza di Agent Platform per il deployment di un agente. Puoi scegliere tra i seguenti metodi:

Developer Connect

Per eseguire il deployment da Developer Connect su Agent Platform, utilizza client.runtimes.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.

Puoi utilizzare questo metodo di deployment solo con Python. 

remote_agent = client.runtimes.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 (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 (str): il nome della risorsa del link al repository Git di Developer Connect.
    • revision (str): la revisione da recuperare (SHA di ramo, tag o commit).
    • dir (str): la directory principale del codice dell'agente all'interno del repository.
  • entrypoint_module (str): il nome del modulo Python contenente il punto di ingresso dell'agente, relativo alla directory specificata in developer_connect_source.dir.
  • entrypoint_object (str): il nome dell'oggetto chiamabile all'interno di entrypoint_module che rappresenta l'applicazione dell'agente (ad esempio, root_agent).
  • requirements_file (str): (facoltativo) 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 Agent Runtime 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.

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 Agent Platform e può essere interrogata o eliminata.

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

File di origine

Per eseguire il deployment dai file di origine su Agent Platform, utilizza client.runtimes.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.

Puoi utilizzare questo metodo di deployment solo con Python. 

# 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.runtimes.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 (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 (str): il nome completo del modulo Python contenente il punto di ingresso dell'agente (ad esempio, agent_dir.agent).
  • entrypoint_object (str): il nome dell'oggetto chiamabile all'interno di entrypoint_module che rappresenta l'applicazione dell'agente (ad esempio, root_agent).
  • class_methods (list[dict]): un elenco di dizionari che definiscono i metodi esposti dell'agente. Ogni dizionario include un campo name, api_mode e un campo parameters facoltativo. Per ulteriori informazioni sui metodi per un agente personalizzato, consulta Elenco delle operazioni supportate.

    Ad esempio:

    class_methods = [
    {
        "name": "method_name",
        "api_mode": "",  # Options: "", "async", "async_stream", "stream", "bidi_stream"
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {"type": "string", "description": "Description of param1"},
                "param2": {"type": "integer"}
            },
            "required": ["param1"]
        }
    }
]
  • requirements_file (str): (facoltativo) il percorso di un file dei requisiti pip all'interno dei percorsi specificati in source_packages. Il valore predefinito è requirements.txt nella directory principale dell'origine del pacchetto.

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

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

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 Agent Platform e può essere interrogata o eliminata.

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

Dockerfile

Il deployment da Dockerfile su Agent Platform segue un approccio simile al deployment dai file di origine, tranne per il fatto che utilizzi image_spec nella configurazione anziché entrypoint_module, entrypoint_object e requirements_file. Il container creato dal Dockerfile deve rispettare il contratto di runtime.

Puoi utilizzare questo metodo di deployment con qualsiasi lingua. L'esempio in questa sezione utilizza Python.

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

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

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

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 Agent Platform e può essere interrogata o eliminata.

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

Immagine container

Per 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. L'immagine container deve rispettare il contratto runtime.

Puoi utilizzare questo metodo di deployment con qualsiasi lingua. L'esempio in questa sezione utilizza Python.

Di seguito è riportato un esempio di deployment di un agente utilizzando un'immagine container:

remote_agent = client.runtimes.create(
    config={
        "container_spec": {
            "image_uri": "CONTAINER_IMAGE_URI",
        },
        # Other optional configs
        "display_name": "Container image agent",
    },
)

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 Agent Platform e può essere interrogata o eliminata.

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

SDK Agent Platform

Per eseguire il deployment dell'agente su Agent Platform, utilizza client.runtimes.create per trasmettere l'oggetto local_agent insieme a eventuali configurazioni facoltative: 

remote_agent = client.runtimes.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 Agent Runtime 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 eseguito il deployment, remote_agent corrisponde a un'istanza di local_agent in esecuzione su Agent Platform e può essere interrogata o eliminata.

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

(Facoltativo) Ottieni 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 AgentRuntime.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. L'insieme delle operazioni supportate dipende dal framework che hai utilizzato per sviluppare l'agente:

(Facoltativo) Concedi le autorizzazioni all'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.

(Facoltativo) Esegui il deployment di agenti con l'infrastruttura aziendale

Per eseguire il deployment dell'agente con un ambiente completo che includa livelli di sicurezza e governance, copia e personalizza i seguenti modelli di App Design Center:

Passaggi successivi

Guida

Scopri come gestire gli agenti di cui è stato eseguito il deployment nel runtime gestito di Agent Platform.

Guida

Utilizza un agente con Agent Platform Runtime.