Connettere gli agenti dell'Agent Development Kit a Cloud Storage

Puoi connettere gli agenti dell'Agent Development Kit (ADK) a Cloud Storage. Questa connessione consente agli agenti di utilizzare i toolset ADK integrati.

In qualità di sviluppatore di AI, puoi integrare ADK con Cloud Storage per connettere gli agenti ai dati archiviati. Questa integrazione ti aiuta a scalare i carichi di lavoro degli agenti. Puoi utilizzare Cloud Storage per rendere persistenti lo stato, la memoria e i checkpoint per le attività a lunga esecuzione. Puoi anche utilizzare Cloud Storage per condividere i file intermedi in un workflow multi-agente.

Questo documento descrive i vantaggi dell'integrazione di Cloud Storage con ADK. Vengono trattati i casi d'uso comuni e le funzionalità dei toolset disponibili. Per istruzioni dettagliate sulla configurazione ed esempi di codice, consulta la guida all'integrazione di ADK.

Vantaggi dell'integrazione di Cloud Storage con ADK

Quando integri Cloud Storage con gli agenti, questi possono gestire file di grandi dimensioni, mantenere la cronologia delle conversazioni e riutilizzare l'infrastruttura di archiviazione esistente.

• Espansione dinamica del contesto: consenti agli agenti di accedere a set di dati di grandi dimensioni, manuali o file multimediali senza superare i limiti di lettura simultanea di un LLM.
• Persistenza durevole degli artefatti: archivia in modo affidabile file temporanei, log o elementi generati (come report o immagini) al di fuori della cronologia delle conversazioni.
• Supporto per qualsiasi tipo di artefatto: elabora e genera diversi formati, tra cui testo, immagini, audio e video, utilizzando Cloud Storage come spazio di archiviazione condiviso.
• Controllo dell'accesso granulare: controlla con precisione l'accesso degli agenti a Cloud Storage utilizzando i ruoli IAM. ADK utilizza l'autenticazione standard Google Cloud per garantire che gli agenti dispongano solo delle autorizzazioni minime necessarie per accedere ai dati o eseguire un'attività.

Casi d'uso

Dotando gli agenti delle funzionalità di Cloud Storage, puoi affrontare i seguenti casi d'uso:

• Recupero dinamico del contesto, noto anche come Retrieval-Augmented Generation (RAG)
• Persistenza e archiviazione degli artefatti
• Elaborazione di payload di grandi dimensioni
• Gestione automatica delle risorse

Recupero dinamico del contesto tramite RAG

Gli agenti possono fungere da ricercatori scoprendo e leggendo i documenti in Cloud Storage per rispondere alle domande in tempo reale. Questo approccio è utile per le knowledge base interne o i bot di assistenza.

• Ricerca delle norme: puoi fare in modo che un agente elenchi e legga gli ultimi manuali in formato PDF in un bucket compliance-docs per rispondere alle query degli utenti sulle norme aziendali.
• Sintesi multi-oggetto: puoi creare un agente per recuperare e combinare le informazioni da più oggetti di archiviazione per sintetizzare un riepilogo unificato.

Persistenza e archiviazione degli artefatti

Salva in modo affidabile grandi quantità di dati generati dagli agenti per la revisione umana, altri sistemi o audit.

• Report automatici: puoi creare un agente che analizzi le metriche del database, generi un report riassuntivo e lo carichi in un bucket reports-archive.
• Archiviazione dei contenuti multimediali generati: puoi configurare un sistema multi-agente per salvare le immagini o gli oggetti audio generati in Cloud Storage e restituire solo l'URI di archiviazione o un URL firmato.

Elaborazione di payload di grandi dimensioni

Progetta gli agenti in modo che utilizzino gli URI di archiviazione (percorsi file) anziché incollare l'intero contenuto del file nella chat. In questo modo si evitano i costi elevati e l'inefficienza dell'invio di file CSV o codebase di grandi dimensioni all'LLM.

• Gestori della pipeline di dati: puoi fare in modo che l'agente riceva un URI di archiviazione anziché utilizzare un file CSV di grandi dimensioni. L'agente può quindi eseguire l'analisi elaborando i blocchi o ispezionando i metadati e restituire una dashboard di riepilogo.
• Workflow disaccoppiati: puoi progettare un agente che funga da supervisore e che riceva un URI di archiviazione per un prefisso, una cartella o un bucket Cloud Storage. L'agente può passare questo URI ai worker di backend per elaborare gli oggetti e scrivere i risultati finali nello spazio di archiviazione. Questo pattern è compatibile con i servizi basati su eventi, come le funzioni Cloud Run o Cloud Run, per elaborare i dati in modo asincrono.

Gestione automatica delle risorse

Gli agenti possono aiutarti a ottimizzare l'utilizzo dello spazio di archiviazione, automatizzare le attività amministrative e applicare la governance su più bucket. Questa funzionalità è particolarmente utile per i team che gestiscono un'infrastruttura di archiviazione estesa.

• Audit dell'infrastruttura: puoi creare un agente per analizzare le configurazioni dei bucket (ad esempio la località o la classe di archiviazione) e suggerire ottimizzazioni o identificare le impostazioni non conformi.
• Pulizia delle risorse: puoi creare un agente per identificare i bucket vuoti o obsoleti e automatizzare il processo di pulizia in base alle tue policy di conservazione.

Toolset ADK per Cloud Storage

ADK fornisce i seguenti toolset in Python per Cloud Storage. La comprensione di entrambi ti aiuta a definire i ruoli degli agenti e a limitarne le autorizzazioni.

GCSToolset per la gestione dei dati

Il toolset GCSToolset consente all'agente di manipolare i file all'interno dei bucket esistenti. Utilizzalo per attività come la lettura di documenti, il caricamento dei risultati o l'eliminazione di oggetti temporanei.

• Leggi oggetti: recupera i contenuti direttamente utilizzando get_object_data.
• Scopri i contenuti: elenca gli oggetti disponibili utilizzando list_objects.
• Ispeziona le proprietà degli oggetti: controlla le dimensioni degli oggetti o i metadati Content-Type utilizzando get_object_metadata.
• Carica e rendi persistenti: crea nuovi oggetti utilizzando create_object.
• Rimuovi oggetti: rimuovi gli oggetti temporanei utilizzando delete_objects.

GCSAdminToolset per l'infrastruttura

Utilizza il toolset GCSAdminToolset per gestire l'infrastruttura di archiviazione, ad esempio per creare bucket o automatizzare le attività amministrative.

• Scopri l'infrastruttura: elenca i bucket in un progetto utilizzando list_buckets.
• Provisioning dello spazio di archiviazione: crea nuovi bucket utilizzando create_bucket.
• Riconfigura lo spazio di archiviazione: modifica le configurazioni utilizzando update_bucket.
• Deprovisioning dello spazio di archiviazione: rimuovi i bucket utilizzando delete_bucket.
• Ispeziona il contesto del bucket: recupera i metadati del bucket utilizzando get_bucket per controllare la località, la classe di archiviazione o i controlli di accesso del bucket.

Best practice

Per ottimizzare le prestazioni e la sicurezza degli agenti durante l'integrazione con Cloud Storage, tieni presente le seguenti best practice:

• Disaccoppia i payload di grandi dimensioni dalla cronologia delle conversazioni: evita di passare direttamente i file di grandi dimensioni all'agente. Archiviali in Cloud Storage e invia invece i riferimenti ai file (URI). In questo modo si riducono i costi dei token e si evita di raggiungere i limiti di contesto.
• Applica il principio del privilegio minimo: concedi all'agente solo le autorizzazioni minime necessarie per svolgere le sue attività. Evita i ruoli generici come roles/storage.admin, a meno che non gestisci l'infrastruttura. Per le operazioni standard sui file, utilizza ruoli mirati come roles/storage.objectUser o roles/storage.objectViewer limitati a bucket specifici.
• Gestisci le configurazioni in modo centralizzato: evita di codificare i nomi dei bucket o i percorsi dei nomi degli oggetti nella logica dell'agente. Utilizza le variabili di ambiente o i gestori della configurazione per passare da un ambiente di archiviazione di sviluppo, test e produzione all'altro.
• Implementa strategie di recupero efficienti: quando utilizzi Cloud Storage come livello per il recupero delle conoscenze, non caricare interi documenti di grandi dimensioni nel contesto dell'agente. Pre-elabora e suddivide i documenti in blocchi oppure utilizza strumenti di ricerca dedicati per recuperare solo i segmenti pertinenti.

Limitazioni

Quando integri Cloud Storage con ADK, tieni presente le seguenti limitazioni:

• Oggetti immutabili: gli oggetti Cloud Storage sono immutabili. Non puoi aggiungere dati a un oggetto esistente. Se l'agente deve registrare continuamente gli eventi in un singolo file, deve sovrascrivere completamente l'oggetto o creare più oggetti di piccole dimensioni e comporli in un secondo momento.
• Latenza nella gestione dello stato ad alta frequenza: Cloud Storage è adatto per l'archiviazione durevole di artefatti e payload di grandi dimensioni. Tuttavia, l'utilizzo di Cloud Storage per gli aggiornamenti dello stato ad alta frequenza e a bassa latenza può introdurre latenza. Ad esempio, il monitoraggio di ogni turno in uno scambio di conversazioni rapido potrebbe essere più lento rispetto all'utilizzo di cache o database in memoria.
• Mancanza di atomicità multi-oggetto: le operazioni di Cloud Storage si applicano a singoli oggetti. Se l'agente richiede aggiornamenti atomici su più file contemporaneamente, devi implementare la logica di coordinamento all'interno dell'applicazione.

Passaggi successivi

Per visualizzare esempi di codice dettagliati, istruzioni di configurazione e riferimenti ai parametri per inizializzare i toolset di Cloud Storage nell'applicazione Python, consulta la guida all'integrazione di ADK.