Panoramica sull'osservabilità

L'osservabilità degli agenti in Gemini Enterprise Agent Platform offre una visibilità completa su prestazioni, comportamento e integrità degli agenti e dei server Model Context Protocol (MCP) di cui hai eseguito il deployment. Monitorando le metriche chiave, tracciando i percorsi di esecuzione e osservando il sistema multi-agente nel suo complesso, puoi diagnosticare i problemi, ottimizzare il consumo di risorse e migliorare l'affidabilità degli agenti.

Questo documento fornisce una panoramica degli strumenti di osservabilità disponibili all'interno di Gemini Enterprise Agent Platform, tra cui la topologia a livello di sistema, il monitoraggio dei singoli agenti e le metriche del server MCP.

Configurazione della telemetria

Per compilare queste dashboard, topologie e tracce di osservabilità, i tuoi agenti devono essere configurati per inviare i dati di telemetria nel formato OpenTelemetry ai sistemi di archiviazione in Google Cloud Observability.

Assicurati che gli ambienti degli agenti e dei server MCP siano configurati correttamente per emettere questi dati. I componenti Google Cloud integrati emettono automaticamente la telemetria nel formato OpenTelemetry. Ad esempio, Model Armor emette in modo nativo dati di telemetria standardizzati, consentendoti di esporre e monitorare senza problemi le intercettazioni delle policy in tempo reale direttamente all'interno dei dati di traccia, senza richiedere alcuna strumentazione personalizzata.

Per istruzioni e requisiti di configurazione della telemetria dell'agente, consulta le seguenti risorse:

Indicatori di osservabilità

Gemini Enterprise Agent Platform offre osservabilità tramite metriche, tracce e log.

Quando selezioni un agente specifico dal Registry, la scheda Osservabilità fornisce una suite di dashboard mirate per monitorarne l'integrità operativa, le prestazioni e l'utilizzo dell'infrastruttura. Utilizza la navigazione a sinistra nella scheda Osservabilità per passare da una visualizzazione all'altra:

  • Panoramica: monitora l'utilizzo generale nel periodo di tempo selezionato, tra cui le sessioni totali, i turni medi per sessione e le chiamate totali dell'agente. I grafici delle serie temporali mostrano l'utilizzo dei token (input rispetto a output), il volume complessivo del traffico dell'agente, i percentili di latenza (p50, p95, p99) e i tassi di errore.
  • Valutazione: mostra i monitoraggi online per la valutazione continua della qualità. Sono inclusi widget di serie temporali che monitorano la qualità media delle risposte, le metriche di sicurezza, i tassi di allucinazione e la qualità dell'utilizzo degli strumenti.
  • Modelli: suddivide il rendimento in base al foundation model sottostante. Puoi monitorare la latenza p95, il numero totale di chiamate, le percentuali di errore, gli errori di quota di frequenza e l'utilizzo dei token isolati per modelli specifici.
  • Strumenti: monitora gli strumenti e i servizi esterni collegati all'agente. Questa visualizzazione mostra in dettaglio la latenza p95, il numero di chiamate e i tassi di errore per strumento, nonché la frequenza delle interazioni in cui non è stato chiamato alcuno strumento.
  • Utilizzo: fornisce metriche a livello di infrastruttura per l'ambiente di runtime dell'agente, tra cui l'allocazione della CPU del container, l'allocazione della memoria del container e l'utilizzo dei token.
  • Log agentico: mostra un flusso filtrabile di log non elaborati dell'agente, tra cui gravità, timestamp e riepiloghi esecutivi per l'approfondimento della risoluzione dei problemi. Per saperne di più, consulta Visualizza i log dell'agente.

Oltre alle dashboard nella scheda Osservabilità, puoi utilizzare la scheda Tracce dell'agente per esaminare l'esecuzione passo passo di sessioni specifiche, inclusi i grafi diretti aciclici di intervalli e input/output. Per saperne di più, consulta Visualizza le tracce dell'agente. Puoi anche utilizzare la scheda Topologia per visualizzare le dipendenze in entrata e in uscita specifiche per quel singolo agente.

Per i server MCP, puoi monitorare il numero di richieste e la durata delle richieste p95 per monitorare l'utilizzo e la reattività.

Controllo delle azioni dell'agente

Per supportare i controlli di sicurezza e conformità aziendali, Gemini Enterprise Agent Platform utilizza il logging con doppia attribuzione per registrare l'attività degli agenti in Cloud Logging. Quando un agente esegue un'azione o chiama uno strumento per conto di una persona (autorità delegata dall'utente), i log di controllo e di esecuzione registrano sia l'identità dell'agente basata su SPIFFE (principal://... nei log di controllo o spiffe://... nei log di esecuzione) sia l'identità dell'utente umano che ha avviato l'azione. Quando un agente agisce autonomamente con la propria autorità, i log attribuiscono l'azione direttamente all'identità univoca dell'agente.

I revisori e gli amministratori della sicurezza possono isolare ed esaminare gli eventi avviati dall'agente in Cloud Logging filtrando in base al flag is_agentic=true nelle query di log. La combinazione di is_agentic=true con l'identità dell'agente o l'entità utente ti consente di tracciare i percorsi di esecuzione end-to-end e di verificare l'applicazione delle policy in tutte le interazioni degli agenti.

Arresto di emergenza e aspettative di propagazione delle policy

Quando si risponde a un incidente di sicurezza o a un comportamento anomalo dell'agente, Agent Platform fornisce due livelli complementari per interrompere l'attività dell'agente:

  • Terminazione immediata del runtime o reindirizzamento del traffico: l'eliminazione di un agente di cui è stato eseguito il deployment su Agent Runtime (runtimes.delete o reasoningEngines.delete) termina immediatamente le istanze del container, interrompe le sessioni attive e le chiamate di streaming e invalida definitivamente l'identità dell'agente SPIFFE al termine dell'operazione di eliminazione. In alternativa, puoi cambiare percorso del 100% del traffico root verso una revisione valida nota utilizzando trafficSplitManual o archiviare le revisioni preesistenti aggiornando spec.deployment_spec.agent_gateway_config.
  • Revoca dell'accesso basata su policy: l'aggiunta di una regola DENY alle Unified Access Policies (UAP) applicate da Agent Gateway (iamEnforcementMode: "ENFORCE") o l'applicazione di una policy di negazione o di una revoca dei ruoli di Identity and Access Management (IAM) blocca le chiamate API e degli strumenti in uscita, preservando al contempo il container di runtime per l'analisi forense. Tuttavia, gli aggiornamenti delle policy IAM e delle UAP sono coerenti: le modifiche dirette alle policy diventano effettive in genere entro 2 minuti, ma possono richiedere fino a 7 minuti o più per essere propagate a livello globale (vedi Propagazione delle modifiche di accesso) e gli aggiornamenti dell'appartenenza ai gruppi o di principalSet possono richiedere da diversi minuti a ore per la sincronizzazione. Gli aggiornamenti delle policy vengono valutati in base ai nuovi controlli di autorizzazione e non chiudono forzatamente le connessioni di streaming già stabilite, a meno che non vengano autorizzate di nuovo.

Per un kill switch immediato durante un incidente attivo, elimina il runtime dell'agente o cambia percorso del traffico della revisione, oltre ad applicare una regola di negazione della policy. Per istruzioni passo passo, consulta Arresto di emergenza e revoca dell'accesso.

Latenza dei risultati di telemetria e sicurezza

Diversi controlli di osservabilità e sicurezza operano su diverse pianificazioni di importazione e valutazione. Comprendere queste aspettative di latenza aiuta gli addetti alla risposta agli incidenti a distinguere tra l'applicazione in linea e il rilevamento asincrono delle minacce.

La tabella seguente riassume il modello di valutazione e la latenza prevista per ogni segnale di telemetria e indicatore sicuro in Agent Platform:

Segnale o controllo Modello di valutazione e importazione Latenza tipica
Cloud Audit Logs e log delle richieste di Agent Gateway (cloudaudit.googleapis.com/*, networkservices.googleapis.com/gateway_requests) Generati in modo sincrono quando vengono valutate le chiamate API e i controlli di autorizzazione del gateway, quindi importati in Logging. Quasi in tempo reale (in genere ricercabile in Esplora log entro pochi secondi). I filtri di aggiornamento dell'interfaccia a riga di comando (CLI) ristretti, come --freshness=6h, possono occasionalmente non rilevare le voci dell'indice indicizzate di recente; utilizza --freshness=1d per verificare gli eventi recenti.
Log di esecuzione di Agent Runtime (aiplatform.googleapis.com/reasoning_engine_stdout, reasoning_engine_stderr) In streaming asincrono dal container di runtime a Logging. In genere sono visibili entro pochi secondi dall'emissione.
Tracce distribuite in Cloud Trace Esportati in modo asincrono al completamento degli span OpenTelemetry, in base alle regole samplingRate e parentBasedSampling configurate. In genere, è possibile eseguire ricerche entro pochi secondi dal completamento dello span.
Metriche di Cloud Monitoring Campionati periodicamente da Agent Runtime, Agent Gateway e dalle pipeline di rilevamento di anomalie. Campionamento eseguito ogni 60-120 secondi, con un ritardo di visibilità fino a 180-420 secondi in Metrics Explorer e nelle dashboard.
Applicazione delle policy in linea (Agent Gateway, Identity-Aware Proxy, Model Armor) Valutati in modo sincrono sul percorso della richiesta in tempo reale prima del completamento di una chiamata allo strumento, di una richiesta MCP o di un prompt del modello. Intercettazione in linea in tempo reale (zero ritardi di post-elaborazione).
Rilevamento anomalie degli agenti e risultati di Security Command Center (Security Command Center) (AGENT_SESSION_ANOMALY) Valutato in modo asincrono fuori banda in una pipeline di rilevamento multilivello dopo l'importazione dei log e delle tracce della sessione, aggiungendo zero latenza alle risposte degli agenti in tempo reale. L'attivazione iniziale dell'ambito richiede circa 40 minuti. Le metriche delle anomalie vengono campionate ogni 120 secondi (con un ritardo di visibilità fino a 420 secondi) e viene applicata una latenza di sincronizzazione aggiuntiva prima che i risultati confermati vengano visualizzati in Security Command Center.

Conservazione con rilevamento delle manomissioni per gli audit log

Le voci di Cloud Audit Logs sono immutabili per progettazione: dopo che Logging scrive una voce di audit log, il payload e i metadati non possono essere modificati. Gli audit log Attività di amministrazione ed Eventi di sistema sono archiviati nel bucket di log _Required, che applica un periodo di conservazione fisso di 400 giorni e non può essere modificato o eliminato.

Per impostazione predefinita, gli audit log di controllo dell'accesso ai dati (cloudaudit.googleapis.com/data_access), i log delle policy negate (cloudaudit.googleapis.com/policy_denied), i log delle richieste di Agent Gateway (networkservices.googleapis.com/gateway_requests) e i log di esecuzione dell'agente con doppia attribuzione (is_agentic=true) vengono indirizzati al bucket di log _Default con un periodo di conservazione di 30 giorni.

Per applicare la conservazione WORM (Write Once, Read Many) con rilevamento delle manomissioni per le prove di conformità, indirizza i log di audit e del gateway dell'agente a un bucket Logging personalizzato, configura un periodo di conservazione personalizzato (da 1 a 3650 giorni) e blocca definitivamente il bucket. Il blocco di un bucket di Logging è un'azione irreversibile che impedisce a chiunque, inclusi i Project Owner e gli amministratori dell'organizzazione, di eliminare il bucket, eliminare le voci di log prima della scadenza del periodo di conservazione o ridurre il periodo di conservazione.

Per creare e bloccare un bucket di Logging personalizzato per gli audit log degli agenti utilizzando Google Cloud CLI, esegui questi comandi:

gcloud logging buckets create BUCKET_ID \
    --location=LOCATION \
    --retention-days=RETENTION_DAYS \
    --project=PROJECT_ID

gcloud logging buckets update BUCKET_ID \
    --location=LOCATION \
    --locked \
    --project=PROJECT_ID

Sostituisci quanto segue:

  • BUCKET_ID: un identificatore univoco per il bucket dei log di controllo (ad esempio agent-audit-worm-bucket).
  • LOCATION: la località del bucket (ad esempio global, us o eu).
  • RETENTION_DAYS: il numero di giorni per conservare le voci di log (tra 1 e 3650).
  • PROJECT_ID: l'ID progetto Google Cloud .

Per evitare che un bucket di log bloccato venga rimosso se il progetto principale viene eliminato, applica un blocco del progetto al progetto. In alternativa, puoi esportare gli audit log in un bucket Cloud Storage configurato con una policy di conservazione bloccata (Blocco bucket). Per saperne di più, consulta Configura e gestisci i bucket di log.

Esporta i log di controllo in un SIEM

Per centralizzare il monitoraggio della sicurezza, la correlazione e l'archiviazione della conformità a lungo termine, puoi esportare continuamente gli audit log degli agenti, le decisioni di autorizzazione di Agent Gateway e i log di esecuzione di is_agentic=true in Google Security Operations (Google SecOps) o in un sistema di security information and event management (SIEM) di terze parti.

Puoi configurare un sink di Logging a livello di progetto o un sink aggregato a livello di organizzazione o di cartella per instradare i log alle seguenti destinazioni:

  • Google Security Operations: importa gli audit log di Cloud, i log di Agent Gateway e i risultati di AGENT_SESSION_ANOMALY da Security Command Center in Google SecOps in modo nativo o tramite un feed Pub/Sub o Cloud Storage per analizzare le sessioni degli agenti insieme alla telemetria di sicurezza aziendale. Per istruzioni sulla configurazione, consulta Esporta i dati di Google Cloud in Google SecOps.
  • Pub/Sub (Pub/Sub): trasmetti in streaming gli audit log degli agenti in tempo reale a un argomento Pub/Sub per l'importazione da parte di piattaforme SIEM di terze parti (come Splunk, Datadog o QRadar) utilizzando una sottoscrizione Pub/Sub o un connettore Dataflow. Per maggiori dettagli, consulta Instrada i log a Pub/Sub.
  • BigQuery (BigQuery) o Observability Analytics: esporta i log in un set di dati BigQuery o collega un bucket di log abilitato per Observability Analytics a BigQuery per eseguire query di conformità SQL su identità degli agenti, deleghe degli utenti e negazioni delle policy del gateway.
  • Cloud Storage: esporta i file di log JSON in batch in un bucket Cloud Storage con il blocco dei bucket abilitato per l'archiviazione immutabile a lungo termine.

Per creare un sink di Logging che trasmetta in streaming gli audit log dell'agente e i log del gateway a un argomento Pub/Sub per l'importazione SIEM, completa i seguenti passaggi:

  1. Crea il sink di log con un filtro di inclusione che acquisisce Cloud Audit Logs, i log delle richieste di Agent Gateway, i log di Agent Runtime e le voci di doppia attribuzione (is_agentic=true):

    gcloud logging sinks create SINK_NAME \
    pubsub.googleapis.com/projects/DESTINATION_PROJECT_ID/topics/TOPIC_ID \
    --log-filter='logName:("cloudaudit.googleapis.com" OR "networkservices.googleapis.com%2Fgateway_requests" OR "aiplatform.googleapis.com%2Freasoning_engine") OR jsonPayload.is_agentic=true OR labels.is_agentic="true"' \
    --project=PROJECT_ID

    Sostituisci quanto segue:

    • SINK_NAME: un nome per il sink di log (ad esempio, agent-audit-siem-sink).
    • DESTINATION_PROJECT_ID: l'ID progetto che ospita l'argomento Pub/Sub di destinazione.
    • TOPIC_ID: l'ID dell'argomento Pub/Sub a cui si iscrive il SIEM.
    • PROJECT_ID: l'ID progetto da cui stai esportando i log. Per esportare i dati di un'intera organizzazione, sostituisci --project=PROJECT_ID con --organization=ORGANIZATION_ID --include-children.

  2. Recupera l'identità del account di servizio writer del sink e concedigli il ruolo Publisher Pub/Sub (roles/pubsub.publisher) nell'argomento di destinazione:

    WRITER_IDENTITY=$(gcloud logging sinks describe SINK_NAME \
    --project=PROJECT_ID \
    --format='value(writerIdentity)')

gcloud pubsub topics add-iam-policy-binding TOPIC_ID \
    --project=DESTINATION_PROJECT_ID \
    --member="${WRITER_IDENTITY}" \
    --role="roles/pubsub.publisher"

Convenzioni di AI generativa di OpenTelemetry

Le tracce degli agenti e i log di prompt e risposte si basano in gran parte sulle convenzioni semantiche di OpenTelemetry per i sistemi di AI generativa per standardizzare il modo in cui la telemetria dell'AI generativa viene acquisita, strutturata e segnalata.

Il rispetto di queste convenzioni è fondamentale per il tracciamento degli agenti perché stabilisce un formato universale e indipendente dal fornitore per descrivere workflow degli agenti complessi e in più passaggi, come le esecuzioni degli strumenti, i passaggi di recupero e il consumo di token. Questa standardizzazione contribuisce a un'interoperabilità perfetta tra diversi backend di osservabilità e strumenti di analisi, sia all'interno che all'esterno di Google Cloud.

Passaggi successivi