Sistema di AI con un singolo agente che utilizza l'ADK e Cloud Run

Last reviewed 2025-12-09 UTC

Questo documento fornisce un'architettura di riferimento per aiutarti a progettare un sistema di AI agentica con un singolo agente su Google Cloud. Il sistema con un singolo agente in questa architettura è creato utilizzando Agent Development Kit (ADK) ed è implementato su Cloud Run. Puoi anche eseguire il deployment dell'agente su Agent Runtime su Gemini Enterprise Agent Platform o Google Kubernetes Engine (GKE). L'architettura utilizza il Model Context Protocol (MCP), che consente all'agente di accedere ed elaborare informazioni da più fonti in modo da fornire insight ricchi di contesto.

Questo documento è rivolto ad architetti, sviluppatori e amministratori di applicazioni di AI. Presuppone che tu abbia una conoscenza di base dei concetti di AI, machine learning (ML) e modelli linguistici di grandi dimensioni (LLM). Il documento presuppone inoltre che tu abbia una conoscenza di base degli agenti e dei modelli di AI. Non fornisce indicazioni specifiche per la progettazione e la codifica di agenti AI.

La sezione Deployment di questo documento elenca gli esempi di codice che puoi utilizzare per scoprire come creare ed eseguire il deployment di sistemi AI ad agente singolo.

Architettura

Il seguente diagramma mostra un'architettura per un sistema di AI ad agente singolo di cui è stato eseguito il deployment su Cloud Run:

Un'architettura ad agente singolo di cui è stato eseguito il deployment su Cloud Run. Architettura per un sistema di AI multi-agente in Google Cloud.

Componenti dell'architettura

L'architettura di esempio è costituita dai seguenti componenti:

Componente Descrizione
Frontend Gli utenti interagiscono con l'agente tramite un frontend, ad esempio un'interfaccia di chat, che viene eseguita come servizio Cloud Run serverless.
Agente L'agente riceve le richieste degli utenti, interpreta lo user intent, seleziona gli strumenti appropriati e poi sintetizza le informazioni per rispondere alle query.
Agent Runtime L'agente viene creato utilizzando l'ADK e viene eseguito il deployment come servizio Cloud Run serverless. Puoi anche eseguire il deployment dell'agente su Agent Runtime su Gemini Enterprise Agent Platform o come app containerizzata su GKE. Per informazioni su come scegliere un Agent Runtime, vedi Scegliere i componenti dell'architettura dell'AI agentica.
ADK ADK fornisce strumenti e un framework per sviluppare, testare ed eseguire il deployment degli agenti. ADK astrae la complessità della creazione di agenti e consente agli sviluppatori di AI di concentrarsi sulla logica e sulle funzionalità dell'agente. Quando sviluppi agenti utilizzando l'ADK, puoi configurarli in modo che accedano e utilizzino strumenti integrati come la Ricerca Google.
Modello di AI e runtime del modello Per il servizio di inferenza, l'agente in questa architettura di esempio utilizza il modello AI Gemini su Gemini Enterprise Agent Platform.
MCP Toolbox MCP Toolbox for Databases fornisce strumenti specifici per il database per l'agente. Può gestire complessità come il pooling delle connessioni e l'autenticazione.
Client, server e strumenti MCP MCP facilita l'accesso agli strumenti standardizzando l'interazione tra agenti e strumenti. Per ogni coppia agente-strumento, un client MCP invia richieste a un server MCP tramite il quale l'agente accede a uno strumento, ad esempio un file system o un'API. Ad esempio, strumenti esterni come lo strumento LangChain di StackOverflow e lo strumento della Ricerca Google possono fornire dati e grounding.
Osservabilità L'agente viene monitorato utilizzando Google Cloud Observability per logging, monitoraggio e tracciamento.

Flusso agentico

Il sistema di esempio con un singolo agente nell'architettura precedente ha il seguente flusso:

  1. Un utente inserisce un prompt tramite un frontend, ad esempio un'interfaccia di chat, che viene eseguito come servizio Cloud Run serverless.
  2. Il frontend inoltra il prompt all'agente.
  3. L'agente utilizza il modello di AI per ragionare sul prompt dell'utente e sintetizzare una risposta:
    • Il modello di AI determina quali strumenti utilizzare per raccogliere informazioni contestuali o per eseguire un'attività.
    • L'agente esegue chiamate di strumenti e aggiunge la risposta al contesto.
    • L'agente esegue il grounding e la convalida intermedia.

Prodotti utilizzati

Questa architettura di riferimento utilizza i seguenti prodotti e strumenti Google Cloud e open source:

Casi d'uso

Questa sezione descrive i possibili casi d'uso per l'architettura descritta in questo documento.

Classificazione automatica delle segnalazioni di bug

Puoi adattare questa architettura di riferimento per automatizzare la valutazione dei report sui bug in arrivo: comprendere il problema, cercare duplicati, raccogliere il contesto tecnico pertinente e quindi creare un bug nel sistema. Un agente basato sull'AI può fungere da assistente intelligente in grado di eseguire l'indagine iniziale, consentendo agli esperti umani di concentrarsi sulla risoluzione di problemi più complessi.

Per questo caso d'uso, l'architettura offre i seguenti vantaggi:

  • Tempi di risoluzione più rapidi: l'agente automatizza la ricerca iniziale e la raccolta del contesto, il che può ridurre significativamente il tempo necessario per assegnare e risolvere i ticket di bug.
  • Maggiore accuratezza e coerenza: l'agente può eseguire ricerche sistematiche in più origini dati (database interni, repository di codice e web pubblico). Questa funzionalità fornisce un'analisi più completa e coerente di quella che potrebbe consentire il triage manuale.
  • Riduzione del carico di lavoro manuale: l'agente può scaricare le attività di triage ripetitive dai team di assistenza IT e ingegneria, consentendo loro di concentrarsi su attività di valore superiore.

Questa architettura è ideale per qualsiasi organizzazione che sviluppa software e che vuole migliorare l'efficienza e l'efficacia del processo di risoluzione dei bug. Per ulteriori informazioni e opzioni di deployment, vedi Software Bug Assistant - ADK Python Sample Agent e Tools Make an Agent: From Zero to Assistant with ADK.

Assistenza clienti

Puoi adattare questa architettura di riferimento per offrire ai clienti un'esperienza di acquisto fluida e personalizzata. Un agente basato sull'AI può fornire assistenza clienti, consigliare prodotti, gestire ordini e programmare servizi, consentendo ai rappresentanti umani di concentrarsi su altre attività.

Per questo caso d'uso, l'architettura offre i seguenti vantaggi:

  • Upselling e promozioni: l'agente può contribuire ad aumentare le vendite suggerendo prodotti, servizi e promozioni. I suggerimenti dell'agente si basano sull'ordine attuale del cliente e sulle vendite pertinenti, sulla cronologia degli ordini del cliente e sugli articoli presenti nel carrello.

  • Gestione e pianificazione degli ordini: l'agente può aumentare l'efficienza e ridurre le difficoltà dei clienti gestendo i contenuti del carrello degli acquisti di un cliente e facilitando la pianificazione autonoma dei servizi.

  • Riduzione del carico di lavoro manuale: l'agente gestisce le richieste generali, gli ordini e la pianificazione, consentendo agli agenti dell'assistenza clienti di concentrarsi su problemi più complessi dei clienti.

Questa architettura è ideale per qualsiasi organizzazione retail che voglia migliorare la customer experience, aumentare le vendite e semplificare la gestione e la pianificazione degli ordini. Per ulteriori informazioni e opzioni di deployment, consulta Agente dell'assistenza clienti Cymbal Home & Garden.

Previsione di serie temporali

Puoi adattare questa architettura di riferimento per prevedere i risultati, ad esempio la previsione della domanda, la previsione dei modelli di traffico o l'analisi e la previsione dei guasti delle macchine. Un agente basato sull'AI può analizzare dati in tempo reale, tendenze storiche ed eventi imminenti. L'agente può utilizzare queste analisi per prevedere i risultati per un periodo di tempo specificato. Queste previsioni possono aiutarti a pianificare e ridurre il tempo dedicato all'analisi dei dati da parte di data analyst.

Questo caso d'uso può essere utile alle organizzazioni in molti scenari, ad esempio:

  • Gestione dell'inventario: utilizzando l'analisi avanzata combinata con i dati storici sulle vendite e le tendenze del mercato, l'agente può aiutarti a pianificare gli ordini di riassortimento in modo da prepararti a picchi o cali della domanda dei clienti.
  • Percorsi di viaggio: l'agente può aiutare a risparmiare tempo e ridurre i costi di viaggio per i fornitori di servizi e consegne analizzando i pattern di traffico in tempo reale e storici, nonché eventi come lavori in corso o chiusure stradali.
  • Evita interruzioni: l'agente può aiutarti a evitare potenziali interruzioni del servizio identificando la causa principale delle interruzioni storiche. Può anche aiutare a prevedere potenziali stati di errore futuri, in modo da poter mitigare un problema prima che diventi un problema.

Questa architettura è ideale per qualsiasi organizzazione che deve adattarsi a pattern mutevoli in base alle tendenze consolidate. È ideale anche per le organizzazioni i cui clienti possono trarre vantaggio da insight proattivi che li aiutano a pianificare il futuro. Per ulteriori informazioni e opzioni di deployment, consulta Time Series Forecasting Agent con ADK e MCP Toolbox di Google.

Recupero dei documenti

Puoi adattare questa architettura di riferimento per utilizzare RAG Engine su Gemini Enterprise Agent Platform e creare un agente per gestire il recupero dei dati contestuali. Un agente di recupero dei documenti può recuperare i dati pertinenti da un insieme di documenti selezionati per fornire risposte oggettive con citazioni del materiale di origine.

Con un agente di recupero dei documenti, puoi contribuire a garantire che clienti e utenti interni ricevano risposte informate e sensibili al contesto alle loro query. Questa implementazione può contribuire a ridurre errori e imprecisioni, contribuendo a garantire che le risposte si basino sulle informazioni che hai convalidato.

Un'architettura di recupero dei documenti è ideale per le knowledge base su norme e processi, infrastruttura tecnica, conoscenza del prodotto e altra documentazione basata su fatti. Per informazioni su come sviluppare un agente di recupero dei documenti basato sulla generazione augmented retrieval (RAG), consulta Agente di recupero della documentazione.

Alternative di design

Questa sezione presenta approcci di progettazione alternativi che puoi prendere in considerazione per il deployment dell'agente AI in Google Cloud.

Agent Runtime

Nell'architettura descritta in questo documento, l'agente e i relativi strumenti vengono implementati su Cloud Run. Puoi anche utilizzare GKE o Agent Runtime come runtime alternativo. Per informazioni su come scegliere un Agent Runtime, consulta Agent Runtime in "Scegli i componenti dell'architettura di AI agentica".

Runtime del modello di AI

Nell'architettura descritta in questo documento, il runtime del modello di AI è Agent Platform. Puoi anche utilizzare Cloud Run o GKE come runtime alternativo. Per informazioni su come scegliere un runtime del modello, consulta Runtime del modello in "Scegli i componenti dell'architettura di AI agentica".

Considerazioni sulla progettazione

Questa sezione fornisce indicazioni per aiutarti a utilizzare questa architettura di riferimento per sviluppare un'architettura che soddisfi i tuoi requisiti specifici di sicurezza, affidabilità, costi, efficienza operativa e prestazioni.

Progettazione del sistema

Questa sezione fornisce indicazioni per aiutarti a scegliere le Google Cloud regioni per il deployment e a selezionare i prodotti e gli strumenti Google Cloud appropriati.

Selezione delle regioni

Quando selezioni le regioni Google Cloud per le tue applicazioni di AI, tieni presente i seguenti fattori:

Per selezionare le località Google Cloud appropriate per le tue applicazioni, utilizza i seguenti strumenti:

  • Google Cloud Selettore di regioni: uno strumento interattivo basato sul web per selezionare la regione Google Cloud ottimale per le tue applicazioni e i tuoi dati in base a fattori come impronta di carbonio, costo e latenza.
  • API Cloud Location Finder: un'API pubblica che fornisce un modo programmatico per trovare le località di deployment in Google Cloud, Google Distributed Cloud e altri cloud provider.

Progettazione di agenti

Questa sezione fornisce suggerimenti generali per la progettazione di agenti AI. Le indicazioni dettagliate sulla scrittura del codice e della logica dell'agente non rientrano nell'ambito di questo documento.

  • Definizione e progettazione dell'agente:
    • Definisci chiaramente l'obiettivo commerciale del sistema di AI agentica e l'attività che ogni agente svolge.
    • Scegli un pattern di progettazione di agenti che soddisfi al meglio i tuoi requisiti.
    • Utilizza ADK per creare, eseguire il deployment e gestire in modo efficiente la tua architettura basata su agenti.
  • Interazioni con l'agente:
    • Progetta gli agenti rivolti agli utenti nell'architettura per supportare le interazioni in linguaggio naturale.
    • Assicurati che ogni agente comunichi chiaramente le proprie azioni e il proprio stato ai client dipendenti.
    • Progetta gli agenti in modo che rilevino e gestiscano query ambigue e interazioni sfumate.
  • Contesto, strumenti e dati:
    • Assicurati che gli agenti abbiano un contesto sufficiente per monitorare le interazioni a più turni e i parametri di sessione.
    • Descrivi chiaramente lo scopo, gli argomenti e l'utilizzo degli strumenti che gli agenti possono utilizzare.
    • Assicurati che le risposte degli agenti siano basate su origini dati affidabili per ridurre le allucinazioni.
    • Implementa la logica per gestire le situazioni di mancata corrispondenza, ad esempio quando un prompt è fuori tema.

Memoria e spazio di archiviazione della sessione

L'architettura di esempio mostrata in questo documento non include lo spazio di archiviazione della memoria o della sessione. In un ambiente di produzione, puoi migliorare le risposte e aggiungere la personalizzazione integrando stato e memoria nell'agente.

  • Sessione: Una sessione è il thread conversazionale tra un utente e l'agente, dall'interazione iniziale alla fine del dialogo.
  • Stato: Lo stato è l'insieme dei dati che l'agente utilizza e raccoglie all'interno di una sessione specifica. I dati di stato raccolti includono la cronologia dei messaggi che l'utente e l'agente si sono scambiati, i risultati di eventuali chiamate di strumenti e altre variabili di cui l'agente ha bisogno per comprendere il contesto della conversazione.

ADK può monitorare le sessioni nella memoria a breve termine utilizzando l'oggetto Session e gli attributi state. ADK supporta anche la memoria a lungo termine tra le sessioni con lo stesso utente, anche tramite Memory Bank. Per archiviare lo stato della sessione, puoi anche utilizzare servizi come Memorystore for Redis.

Per informazioni sulle opzioni di memoria dell'agente, consulta Scegli i componenti dell'architettura di AI agentica.

Sicurezza

Questa sezione descrive le considerazioni e i suggerimenti per la progettazione di una topologia in Google Cloud che soddisfi i requisiti di sicurezza del tuo workload.

Considerazioni sulla sicurezza per gli agenti

Gli agenti AI introducono alcuni rischi per la sicurezza unici e critici che le pratiche di sicurezza convenzionali e deterministiche potrebbero non essere in grado di mitigare in modo adeguato. Google consiglia un approccio che combini i punti di forza dei controlli di sicurezza deterministici con difese dinamiche basate sul ragionamento. Questo approccio si basa su tre principi fondamentali: la supervisione umana, l'autonomia dell'agente definita con attenzione e l'osservabilità. Di seguito sono riportati consigli specifici in linea con questi principi fondamentali.

  • Supervisione umana: un sistema di AI agentica a volte potrebbe non funzionare o non comportarsi come previsto. Ad esempio, il modello potrebbe generare contenuti imprecisi o un agente potrebbe selezionare strumenti inappropriati. Nei sistemi di AI agentica fondamentali per l'attività, incorpora un flusso human-in-the-loop per consentire ai supervisori umani di monitorare, ignorare e mettere in pausa gli agenti. Ad esempio, gli utenti umani possono esaminare l'output degli agenti, approvarlo o rifiutarlo e fornire ulteriori indicazioni per correggere gli errori o prendere decisioni strategiche. Questo approccio combina l'efficienza dei sistemi di AI agentica con il pensiero critico e l'esperienza nel settore degli utenti umani.
  • Agent Identity e accesso con privilegi minimi:
  • Governance del traffico in entrata e in uscita: indirizza il traffico dell'agente tramite Agent Gateway per applicare le policy di sicurezza di runtime ai limiti in entrata e in uscita. Per informazioni sulle piattaforme di runtime che supportano Agent Gateway, consulta Runtime degli agenti supportati.
    • Da client ad agente (in entrata): esegui il deployment di Agent Gateway davanti all'Agent Runtime. Il gateway aiuta ad autenticare i chiamanti e a ispezionare i prompt in entrata in tempo reale utilizzando Model Armor.
    • Da agente a ovunque (in uscita):
      • Instrada le richieste in uscita da agente ad agente (A2A) e da agente a strumento (MCP) tramite Agent Gateway in modalità in uscita.
      • Applica policy di accesso con rifiuto predefinito utilizzando le policy di accesso IAM e Identity-Aware Proxy (IAP).
      • Verifica che gli agenti e gli strumenti di destinazione siano registrati in Agent Registry.
      • Ispeziona le chiamate e le risposte degli strumenti in uscita con Model Armor per contribuire a prevenire l'esfiltrazione di dati, il prompt injection indiretto e l'uso improprio degli strumenti.
  • Monitoraggio: monitora il comportamento degli agenti utilizzando funzionalità di tracciamento complete che ti offrono visibilità su ogni azione intrapresa da un agente, tra cui il processo di ragionamento, la selezione degli strumenti e i percorsi di esecuzione. Per maggiori informazioni, consulta Connessione di un agente in Agent Runtime e Connessione in ADK.

Per saperne di più sulla protezione degli agenti AI, consulta Sicurezza per gli agenti AI.

Considerazioni sulla sicurezza di Agent Platform

Per contribuire a garantire che le configurazioni e l'utilizzo della piattaforma dell'agente soddisfino i tuoi requisiti di sicurezza, valuta i seguenti suggerimenti:

  • Responsabilità condivisa: la sicurezza è una responsabilità condivisa. Agent Platform protegge l'infrastruttura sottostante e fornisce strumenti e controlli di sicurezza per aiutarti a proteggere i tuoi dati, il tuo codice e i tuoi modelli. Sei responsabile della corretta configurazione dei tuoi servizi, della gestione dei controlli di accesso e della protezione delle tue applicazioni. Per saperne di più, consulta Responsabilità condivisa di Agent Platform.
  • Controlli di sicurezza: Agent Platform supporta Google Cloud controlli di sicurezza che puoi utilizzare per soddisfare i tuoi requisiti di residenza dei dati, chiavi di crittografia gestite dal cliente (CMEK), sicurezza di rete utilizzando i Controlli di servizio VPC e Access Transparency. Per saperne di più, consulta la seguente documentazione:
  • Sicurezza: i modelli di AI potrebbero produrre risposte dannose, a volte in risposta a prompt dannosi.
    • Per migliorare la sicurezza e mitigare il potenziale uso improprio del sistema di AI agentica, puoi configurare i filtri dei contenuti in modo che fungano da barriere per input e risposte dannosi. Per saperne di più, consulta Filtri di sicurezza e dei contenuti.
    • Per ispezionare e sanificare le richieste di inferenza, i prompt degli agenti, le chiamate degli strumenti e le risposte per rilevare minacce come prompt injection e contenuti dannosi, puoi utilizzare Model Armor per le chiamate API dirette al modello e per le richieste instradate tramite Agent Gateway. Model Armor ti aiuta a prevenire input dannosi, verificare la sicurezza dei contenuti, proteggere i dati sensibili, mantenere la conformità e applicare in modo coerente le policy di sicurezza.
  • Accesso ai modelli: puoi configurare policy dell'organizzazione per limitare il tipo e le versioni dei modelli di AI che possono essere utilizzati in un progetto Google Cloud . Per saperne di più, consulta Controlla l'accesso ai modelli di Model Garden.
  • Protezione dei dati: per rilevare e anonimizzare i dati sensibili nei prompt e nelle risposte e nei dati di log, utilizza l'API Cloud Data Loss Prevention. Per saperne di più, guarda questo video: Protezione dei dati sensibili nelle app di AI.

Considerazioni sulla sicurezza di MCP

Per assicurarti che l'implementazione di MCP soddisfi i tuoi requisiti di sicurezza, tieni presente i seguenti suggerimenti:

  • Registrazione e rilevamento degli strumenti: registra i server e gli strumenti MCP in Agent Registry in modo che gli agenti si connettano solo agli endpoint MCP inventariati e approvati dall'amministratore.
  • Controllo degli accessi e ispezione del traffico: instrada il traffico dall'agente all'MCP tramite Agent Gateway in modalità Agent-to-Anywhere (traffico in uscita) e proteggi i server MCP (ad esempio i server MCP ospitati su Cloud Run) utilizzando IAP e le policy di accesso IAM. Configura Model Armor o le norme di governance semantica su Agent Gateway per ispezionare gli input e gli output dello strumento MCP per l'esposizione dei dati sensibili e il prompt injection indiretto.
  • Sicurezza generale dell'MCP: quando configuri gli agenti per l'utilizzo dell'MCP, assicurati che l'accesso a dati e strumenti esterni sia autorizzato, implementa controlli per la privacy come la crittografia, applica filtri per proteggere i dati sensibili e monitora le interazioni degli agenti. Per maggiori informazioni, consulta MCP e sicurezza.

Considerazioni sulla sicurezza A2A

Per assicurarti che l'implementazione A2A soddisfi i tuoi requisiti di sicurezza, tieni presente i seguenti consigli:

  • Sicurezza del trasporto: il protocollo A2A richiede HTTPS per tutte le comunicazioni A2A negli ambienti di produzione e consiglia Transport Layer Security (TLS) versioni 1.2 o successive.
  • Autenticazione: il protocollo A2A delega l'autenticazione a meccanismi web standard come le intestazioni HTTP e a standard come OAuth2 e OpenID Connect. Ogni agente pubblicizza i requisiti di autenticazione nella propria scheda agente. Per saperne di più, consulta Autenticazione A2A.
  • Governance tra agenti: registra gli agenti A2A in Agent Registry e instrada le richieste tra agenti tramite Agent Gateway. Combinando Agent Gateway con Agent Identity, IAP e policy di accesso IAM, puoi verificare in modo crittografico l'identità dell'agente chiamante, applicare un'autorizzazione granulare tra agenti coordinatori e subagenti e ispezionare i payload tra agenti con Model Armor.

Considerazioni sulla sicurezza di Cloud Run

Per assicurarti che l'implementazione di Cloud Run soddisfi i tuoi requisiti di sicurezza, tieni presente i seguenti suggerimenti:

  • Sicurezza del traffico in entrata (per il servizio frontend): per controllare l'accesso all'applicazione, disattiva l'URL run.app predefinito del servizio Cloud Run di frontend e configura un bilanciatore del carico delle applicazioni esterno regionale. Oltre a bilanciare il carico del traffico in entrata verso l'applicazione, il bilanciatore del carico gestisce la gestione dei certificati SSL. Per una maggiore protezione, puoi utilizzare le policy di sicurezza di Google Cloud Armor per fornire il filtro delle richieste, la protezione DDoS e la limitazione di frequenza per il servizio.

  • Autenticazione utente:

    • Utenti all'interno della tua organizzazione: per autenticare l'accesso degli utenti interni al servizio Cloud Run frontend, utilizza IAP. Quando un utente tenta di accedere a una risorsa protetta da IAP, IAP esegue i controlli di autenticazione e autorizzazione.
    • Utenti esterni alla tua organizzazione: per autenticare l'accesso degli utenti esterni al servizio frontend, utilizza Identity Platform o Firebase Authentication. Per gestire l'accesso degli utenti esterni, configura l'applicazione in modo che gestisca un flusso di accesso ed effettui chiamate API autenticate al servizio Cloud Run.

    Per saperne di più, consulta Autenticazione degli utenti.

  • Sicurezza dell'agente e del server MCP: quando ospiti agenti o server MCP su Cloud Run, configura le funzionalità di Agent Platform per Cloud Run per assegnare un'identità agente gestita al servizio e utilizza IAP con Agent Gateway per autenticare e autorizzare le richieste in entrata di agenti e strumenti.

  • Sicurezza delle immagini container: per garantire che venga eseguito il deployment in Cloud Run solo delle immagini container autorizzate, puoi utilizzare Autorizzazione binaria. Per identificare e mitigare i rischi per la sicurezza nelle immagini container, utilizza Artifact Analysis per eseguire automaticamente le analisi delle vulnerabilità. Per maggiori informazioni, consulta Panoramica della scansione dei container.

  • Residenza dei dati: Cloud Run ti aiuta a soddisfare i requisiti di residenza dei dati. I servizi Cloud Run vengono eseguiti all'interno della regione selezionata.

Per ulteriori indicazioni sulla sicurezza dei container, consulta Suggerimenti generali per lo sviluppo di Cloud Run.

Considerazioni sulla sicurezza per tutti i prodotti Google Cloud nell'architettura

Per contribuire a garantire che la tua architettura soddisfi i requisiti di sicurezza, considera i seguenti suggerimenti generali:

  • Crittografia dei dati: per impostazione predefinita, Google Cloud cripta i dati at-rest utilizzando Google-owned and Google-managed encryption keys. Per proteggere i dati dei tuoi agenti utilizzando chiavi di crittografia che controlli, puoi utilizzare CMEK che crei e gestisci in Cloud KMS. Per informazioni sui servizi Google Cloud compatibili con Cloud KMS, consulta Servizi compatibili.
  • Mitiga il rischio di esfiltrazione di dati: per ridurre il rischio di esfiltrazione di dati, crea un perimetro di Controlli di servizio VPC intorno all'infrastruttura. I Controlli di servizio VPC supportano tutti i serviziGoogle Cloud utilizzati da questa architettura di riferimento.
  • Controllo dell'accesso: quando configuri le autorizzazioni per le risorse nella tua topologia, segui il principio del privilegio minimo.
  • Sicurezza dell'ambiente cloud: utilizza gli strumenti di Security Command Center per rilevare le vulnerabilità, identificare e mitigare le minacce, definire e implementare una security posture ed esportare i dati per ulteriori analisi.
  • Ottimizzazione post-deployment: dopo aver eseguito il deployment dell'applicazione inGoogle Cloud, ricevi consigli per ottimizzare ulteriormente la sicurezza utilizzando Active Assist. Esamina i consigli e applicali in base al tuo ambiente. Per saperne di più, consulta Trovare i suggerimenti in Active Assist.

Altri suggerimenti sulla sicurezza

Affidabilità

Questa sezione descrive le considerazioni e i suggerimenti di progettazione per creare e gestire un'infrastruttura affidabile per il tuo deployment in Google Cloud.

Componente Considerazioni e consigli sulla progettazione
Agente

Simula errori: prima di eseguire il deployment del sistema di AI agentica in produzione, convalidalo simulando un ambiente di produzione. Identifica e correggi i problemi e i comportamenti imprevisti.

Scala orizzontalmente: per garantire alta affidabilità e tolleranza di errore, esegui più istanze dell'applicazione dell'agente dietro un bilanciatore del carico. Questo approccio può anche contribuire a ridurre la latenza e i timeout distribuendo le richieste tra le istanze. Alcuni runtime degli agenti gestiscono automaticamente il bilanciamento del carico, ad esempio con la scalabilità automatica delle istanze nei servizi Cloud Run.

Ripristino dalle interruzioni: per garantire che l'agente possa gestire correttamente i riavvii e mantenere il contesto, disaccoppia lo stato dal runtime. Per implementare un'applicazione agente stateless di questo tipo, utilizza un datastore esterno come un database o una cache distribuita. Ad esempio, puoi utilizzare Memory Bank, Memorystore for Redis o un servizio di database come Cloud SQL.

Gestisci gli errori: per consentire la diagnosi e la risoluzione dei problemi, implementa i meccanismi di logging, gestione delle eccezioni e nuovi tentativi.

Agent Platform

Pianificazione della capacità: se il numero di richieste supera la capacità allocata, viene restituito il codice di errore 429. Per i workload business-critical che richiedono costantemente un throughput elevato, puoi prenotare il throughput utilizzando il throughput riservato.

Disponibilità degli endpoint del modello: se i dati possono essere condivisi tra più regioni o paesi, puoi utilizzare un endpoint globale per il modello.

Cloud Run

Robustezza alle interruzioni dell'infrastruttura: Cloud Run è un servizio regionale. Archivia i dati in modo sincrono in più zone all'interno di una regione e bilancia automaticamente il carico del traffico tra le zone. In caso di interruzione a livello di zona, Cloud Run continua a funzionare e i dati non vengono persi. Se si verifica un'interruzione della regione, il servizio smette di funzionare finché Google non risolve l'interruzione.

Scalabilità orizzontale: i servizi Cloud Run gestiscono la scalabilità automatica delle istanze per te. La scalabilità automatica contribuisce a garantire che le istanze possano gestire tutte le richieste in entrata, gli eventi e l'utilizzo della CPU necessari per garantire un'alta affidabilità.

Tutti i prodotti nell'architettura

Ottimizzazione post-deployment: dopo aver eseguito il deployment dell'applicazione in Google Cloud, ricevi consigli per ottimizzare ulteriormente la sicurezza utilizzando Active Assist. Esamina i consigli e applicali in base alle esigenze del tuo ambiente. Per maggiori informazioni, consulta Trovare i suggerimenti in Active Assist.

Per i principi e i suggerimenti di affidabilità specifici per i workload di AI e ML, consulta Prospettiva di AI e ML: affidabilità nel Well-Architected Framework.

Operazioni

Questa sezione descrive i fattori da considerare quando utilizzi questa architettura di riferimento per progettare una topologia Google Cloud che puoi gestire in modo efficiente.

Componente Considerazioni e consigli sulla progettazione
Agente

Debug e analisi: implementa il logging strutturato all'interno dell'applicazione agente. Il logging e il tracciamento ti consentono di acquisire informazioni chiave in un formato strutturato, ad esempio quali strumenti sono stati chiamati, gli input e gli output dell'agente e la latenza di ogni passaggio.

Agent Platform

Monitoraggio tramite log: per impostazione predefinita, i log dell'agente scritti nei flussi stdout e stderr vengono indirizzati a Cloud Logging. Per il logging avanzato, puoi integrare il logger Python con Logging. Se hai bisogno del controllo completo sul logging e sui log strutturati, utilizza il client Logging. Per saperne di più, consulta Accesso di un agente e Accesso in ADK.

Valutazione continua: esegui regolarmente una valutazione qualitativa dell'output degli agenti e della traiettoria o dei passaggi eseguiti dagli agenti per produrre l'output. Per implementare la valutazione degli agenti, puoi utilizzare il servizio di valutazione dell'AI generativa o i metodi di valutazione supportati da ADK.

Cloud Run

Integrità e prestazioni: monitora i tuoi servizi Cloud Run utilizzando Google Cloud Observability. Configura gli avvisi in Cloud Monitoring per ricevere una notifica di potenziali problemi, ad esempio un aumento dei tassi di errore, una latenza elevata o un utilizzo anomalo delle risorse.

Database

Integrità e prestazioni: monitora il database utilizzando Google Cloud Observability. Configura gli avvisi in Monitoring per ricevere notifiche di potenziali problemi, come un aumento dei tassi di errore, una latenza elevata o un utilizzo anomalo delle risorse.

MCP

Strumenti per database: per gestire in modo efficiente gli strumenti per database per i tuoi agenti AI e per garantire che gli agenti gestiscano in modo sicuro complessità come il pooling delle connessioni e l'autenticazione, utilizza MCP Toolbox for Databases. Fornisce una posizione centralizzata per archiviare e aggiornare gli strumenti del database. Puoi condividere gli strumenti tra gli agenti e aggiornarli senza doverli ridistribuire. La toolbox include un'ampia gamma di strumenti per i database Google Cloud come AlloyDB per PostgreSQL e per i database di terze parti come MongoDB.

Modelli di AI generativa: per consentire agli agenti AI di utilizzare i modelli di AI generativa di Google come Imagen e Veo, puoi utilizzare i server MCP per le Google Cloud API di media generativi.

Prodotti e strumenti di sicurezza Google: per consentire agli agenti AI di accedere a prodotti e strumenti di sicurezza Google come Google Security Operations, Google Threat Intelligence e Security Command Center, utilizza i server MCP per i prodotti di sicurezza Google.

Tutti i prodotti Google Cloud nell'architettura

Tracciamento: raccogli e analizza continuamente i dati di traccia utilizzando Trace. I dati di Trace ti consentono di identificare e diagnosticare rapidamente i problemi di latenza all'interno di Agentic Workflows complessi. Puoi eseguire un'analisi approfondita tramite le visualizzazioni nella pagina Esplora tracce della console Google Cloud . Per saperne di più, consulta Traccia un agente.

Per principi e consigli di eccellenza operativa specifici per i workload di AI e ML, consulta Prospettiva AI e ML: eccellenza operativa nel framework Well-Architected.

Ottimizzazione dei costi

Questa sezione fornisce indicazioni per ottimizzare i costi di configurazione e gestione di una topologia Google Cloud creata utilizzando questa architettura di riferimento.

Considerazioni sui costi di Agent Platform

Per assicurarti che le configurazioni e l'utilizzo di Agent Platform soddisfino i tuoi requisiti di costo, tieni presente i seguenti suggerimenti:

  • Analisi e gestione dei costi: per analizzare e gestire i costi della piattaforma Agent, ti consigliamo di creare metriche di riferimento per le query al secondo (QPS) e i token al secondo (TPS). Poi, monitora queste metriche dopo il deployment. La baseline aiuta anche con la pianificazione della capacità. Ad esempio, la base di riferimento ti aiuta a determinare quando potrebbe essere necessario il throughput riservato.
  • Selezione del modello: il modello che selezioni per la tua applicazione di AI influisce direttamente sia sui costi che sulle prestazioni. Per identificare il modello che offre un equilibrio ottimale tra prestazioni e costi per il tuo caso d'uso specifico, testa i modelli in modo iterativo. Ti consigliamo di iniziare con il modello più conveniente e passare gradualmente a opzioni più potenti.
  • Prompting conveniente: la lunghezza dei prompt (input) e delle risposte generate (output) influisce direttamente sulle prestazioni e sui costi. Scrivi prompt brevi, diretti e che forniscano un contesto sufficiente. Progetta i prompt in modo da ottenere risposte concise dal modello. Ad esempio, includi frasi come "riassumi in 2 frasi" o "elenca 3 punti chiave". Per saperne di più, consulta le best practice per la progettazione dei prompt.
  • Memorizzazione nella cache del contesto: per ridurre il costo delle richieste che contengono contenuti ripetuti con un numero elevato di token di input, utilizza la memorizzazione nella cache del contesto.
  • Richieste batch: se pertinente, prendi in considerazione le previsioni in batch. Le richieste batch comportano un costo inferiore rispetto alle richieste standard.

Considerazioni sui costi di Cloud Run

Per assicurarti che l'implementazione di Cloud Run soddisfi i tuoi requisiti di costo, tieni presente i seguenti suggerimenti:

Considerazioni sui costi per tutti i prodotti Google Cloud dell'architettura

Dopo aver eseguito il deployment dell'applicazione in Google Cloud, ricevi suggerimenti per ottimizzare ulteriormente i costi utilizzando Active Assist. Esamina i consigli e applicali in modo appropriato al tuo ambiente. Per saperne di più, consulta Trova i suggerimenti in Active Assist.

Per stimare il costo delle risorse Google Cloud , utilizza il Calcolatore prezziGoogle Cloud .

Per principi e consigli di ottimizzazione dei costi specifici per i workload AI e ML, consulta Prospettiva AI e ML: ottimizzazione dei costi nel framework Well-Architected.

Ottimizzazione delle prestazioni

Questa sezione descrive le considerazioni e i suggerimenti di progettazione per creare una topologia in Google Cloud che soddisfi i requisiti di prestazioni dei tuoi workload.

Considerazioni sulle prestazioni per gli agenti

Per assicurarti che le configurazioni degli agenti soddisfino i requisiti di rendimento, prendi in considerazione i seguenti suggerimenti:

  • Selezione del modello: quando selezioni i modelli per il tuo sistema di AI agentica, considera le funzionalità richieste per le attività che gli agenti devono svolgere.
  • Ottimizzazione dei prompt: per migliorare e ottimizzare rapidamente le prestazioni dei prompt su larga scala ed eliminare la necessità di riscrittura manuale, utilizza lo strumento di ottimizzazione dei prompt della piattaforma Agent. L'ottimizzatore ti aiuta ad adattare in modo efficiente i prompt tra diversi modelli.

Considerazioni sulle prestazioni di Agent Platform

Per assicurarti che le configurazioni e l'utilizzo della piattaforma dell'agente soddisfino i tuoi requisiti di prestazioni, tieni conto dei seguenti suggerimenti:

  • Selezione del modello: il modello che selezioni per la tua applicazione di AI influisce direttamente sia sui costi che sulle prestazioni. Per identificare il modello che offre un equilibrio ottimale tra prestazioni e costi per il tuo caso d'uso specifico, testa i modelli in modo iterativo. Ti consigliamo di iniziare con il modello più conveniente e di passare gradualmente a opzioni più potenti.
  • Prompt engineering: la lunghezza dei prompt (input) e delle risposte generate (output) influisce direttamente sulle prestazioni e sui costi. Scrivi prompt brevi, diretti e che forniscano un contesto sufficiente. Progetta i prompt in modo da ottenere risposte concise dal modello. Ad esempio, includi diciture come "riassumi in 2 frasi" o "elenca 3 punti chiave". Per saperne di più, consulta le best practice per la progettazione dei prompt.
  • Memorizzazione nella cache del contesto: per ridurre la latenza delle richieste che contengono contenuti ripetuti con un numero elevato di token di input, utilizza la memorizzazione nella cache del contesto.

Considerazioni sulle prestazioni di Cloud Run

A seconda dei requisiti di prestazioni, configura la memoria e la CPU da allocare al servizio Cloud Run. Per saperne di più, consulta Configura i limiti di memoria per i servizi e Configura i limiti della CPU per i servizi.

Per ulteriori indicazioni sull'ottimizzazione delle prestazioni, consulta Suggerimenti generali per lo sviluppo di Cloud Run.

Considerazioni sulle prestazioni per tutti i prodotti Google Cloud nell'architettura

Dopo aver eseguito il deployment dell'applicazione in Google Cloud, ricevi suggerimenti per ottimizzare ulteriormente le prestazioni utilizzando Active Assist. Esamina i consigli e applicali in base al tuo ambiente. Per saperne di più, consulta Trovare i suggerimenti in Active Assist.

Per principi e consigli di ottimizzazione delle prestazioni specifici per i workload AI e ML, consulta Prospettiva AI e ML: ottimizzazione delle prestazioni nel Well-Architected Framework.

Deployment

Il deployment automatico per questa architettura di riferimento non è disponibile. Utilizza i seguenti esempi di codice per creare un'architettura ad agente singolo:

Per esempi di codice per iniziare a utilizzare ADK insieme ai server MCP, consulta Strumenti MCP.

Per esempi di altri sistemi di AI ad agente singolo, puoi utilizzare i seguenti esempi di codice. Questi esempi di codice sono punti di partenza completamente funzionali per l'apprendimento e la sperimentazione. Per un funzionamento ottimale negli ambienti di produzione, devi personalizzare la codebase in base ai tuoi requisiti aziendali e tecnici specifici.

  • Shopping personalizzato: fornisci consigli personalizzati sui prodotti per un brand, un commerciante o un marketplace online specifico.
  • Gestione degli incidenti: convalida il token e l'identità dell'utente finale per ogni richiesta utilizzando la propagazione dinamica dell'identità.
  • Elaborazione degli ordini: elabora e archivia gli ordini e coordina la conferma via email con una revisione umana condizionale per le quantità di ordine specificate.
  • Data engineering: sviluppa pipeline Dataform, risolvi i problemi delle pipeline e gestisci il data engineering, dalle query SQL complesse alle trasformazioni e alle dipendenze dei dati.
  • Recupero della documentazione: utilizza la RAG per eseguire query sui documenti che carichi nel motore RAG su Gemini Enterprise Agent Platform e ottenere risposte con citazioni alla documentazione e al codice.

Passaggi successivi

Collaboratori