Connettere gli agenti dell'Agent Development Kit a Cloud Storage

Puoi connettere gli agenti Agent Development Kit (ADK) a Cloud Storage per consentire ai workload degli agenti di accedere ai dati archiviati e ai set di strumenti ADK integrati. Questa integrazione ti consente di mantenere lo stato, la memoria e i checkpoint per le attività a lunga esecuzione e di condividere file intermedi tra i workflow multi-agente.

Per istruzioni sulla configurazione ed esempi di codice, consulta la guida all'integrazione dell'ADK.

Vantaggi dell'integrazione di Cloud Storage con ADK

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

• Espansione dinamica del contesto: offri agli agenti l'accesso a set di dati, manuali o file multimediali di grandi dimensioni senza raggiungere i limiti di lettura di un LLM in una sola volta.
• Persistenza degli artefatti durevole: archivia file temporanei, log o elementi generati (come report o immagini) in modo affidabile 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 granulare dell'accesso: controlla l'accesso degli agenti a Cloud Storage con precisione utilizzando i ruoli IAM. ADK utilizza l'autenticazione Cloud de Confiance by S3NS standard per garantire che gli agenti dispongano solo delle autorizzazioni minime necessarie per accedere ai dati o eseguire un'attività.

Casi d'uso

Dotando i tuoi agenti delle funzionalità di Cloud Storage, puoi gestire 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 automatizzata delle risorse

Recupero dinamico del contesto tramite RAG

Gli agenti possono agire come ricercatori, individuando 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 policy: puoi fare in modo che un agente elenchi e legga i manuali PDF più recenti in un bucket compliance-docs per rispondere alle domande degli utenti sulle policy aziendali.
• Sintesi di più oggetti: puoi creare un agente per recuperare e combinare 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 l'audit.

• Report automatici: puoi creare un agente che analizza le metriche del database, genera un report riepilogativo e lo carica in un bucket reports-archive.
• Archivia i media generati: puoi configurare un sistema multi-agente per salvare le immagini create dall'AI 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 dei file) anziché incollare i contenuti completi dei 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 di 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 chunk o ispezionando i metadati e restituire una dashboard di riepilogo.
• Flussi di lavoro disaccoppiati: puoi progettare un agente che agisca come supervisore e 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 servizi basati su eventi come Cloud Run Functions o Cloud Run per elaborare i dati in modo asincrono.

Gestione automatizzata delle risorse

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

• Controllo dell'infrastruttura: puoi creare un agente per analizzare le configurazioni dei bucket (come la località o la classe di archiviazione) e suggerire ottimizzazioni o identificare 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.

Set di strumenti ADK per Cloud Storage

ADK fornisce i seguenti set di strumenti in Python per Cloud Storage. Comprendere entrambi ti aiuta a definire i ruoli degli agenti e a limitare le loro autorizzazioni.

GCSToolset per la gestione dei dati

Il set di strumenti GCSToolset consente all'agente di manipolare i file all'interno dei bucket esistenti. Utilizzalo per attività come la lettura di documenti, il caricamento di 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.
• Caricamento e persistenza: crea nuovi oggetti utilizzando create_object.
• Rimuovi gli oggetti: rimuovi gli oggetti temporanei utilizzando delete_objects.

GCSAdminToolset per l'infrastruttura

Utilizza il set di strumenti 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.
• Esegui il provisioning dello spazio di archiviazione: crea nuovi bucket utilizzando create_bucket.
• Riconfigura lo spazio di archiviazione: modifica le configurazioni utilizzando update_bucket.
• Esegui il 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 file di grandi dimensioni direttamente all'agente. Archiviali in Cloud Storage e invia 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 eseguire le sue attività. Evita ruoli generici come roles/storage.admin, a meno che non gestisci l'infrastruttura. Per le operazioni su file standard, utilizza ruoli mirati come roles/storage.objectUser o roles/storage.objectViewer limitati a bucket specifici.
• Gestisci le configurazioni centralmente: evita di impostare come hardcoded i nomi dei bucket o i percorsi dei nomi degli oggetti nella logica dell'agente. Utilizza variabili di ambiente o 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 suddividi 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 di artefatti durevoli e payload di grandi dimensioni. Tuttavia, l'utilizzo di Cloud Storage per aggiornamenti di stato ad alta frequenza e bassa latenza può introdurre latenza. Ad esempio, monitorare ogni turno di una conversazione rapida potrebbe essere più lento rispetto all'utilizzo di database o memoria cache.
• Mancanza di atomicità multi-oggetto: le operazioni di Cloud Storage si applicano ai 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 set di strumenti di Cloud Storage nella tua applicazione Python, consulta la guida all'integrazione dell'ADK.
• Per utilizzare le competenze degli agenti predefiniti con gli agenti ADK o gli assistenti al coding AI, consulta Competenze degli agenti Cloud Storage.