Cloud Trace ti consente di analizzare il comportamento e le prestazioni delle applicazioni basate su agenti che chiamano server MCP Google Cloud remoti. Puoi instrumentare la tua applicazione per registrare prompt, risposte e chiamate ai metodi, mentre i server MCP remoti generano intervalli per le chiamate agli strumenti. Una traccia acquisisce l'operazione end-to-end per mostrare le sequenze di chiamate e la latenza complessiva, mentre i singoli intervalli forniscono dettagli sullo stato e sulla tempistica per funzioni specifiche.
Informazioni sugli strumenti
Gli strumenti consentono a un agente di raccogliere informazioni al di fuori dei dati di addestramento, in genere interagendo con API esterne. Con i server MCP di Google Cloud, le tue applicazioni basate su agenti possono chiamare strumenti che richiamano i metodi dell'API Google Cloud . Ad esempio, la tua applicazione può chiamare lo strumento list_log_entries per recuperare i dati di log recenti.
Il Model Context Protocol (MCP) è una specifica che definisce un modo standardizzato per gli agenti AI di comunicare e interagire con strumenti, origini dati e risorse esterni. Per un elenco completo dei prodotti che forniscono un server MCP e i link alla relativa documentazione di riferimento, consulta Prodotti supportati.
Come viene passato il contesto della traccia a un server MCP
Le pagine di riferimento di MCP, come la documentazione per list_log_entries, forniscono un comando curl di esempio che puoi utilizzare per inviare richieste HTTP allo strumento. Il payload JSON inviato nella richiesta è simile al seguente:
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "NAME",
"arguments": {
// provide these details according to the tool's MCP specification
}
},
"id": 1
}
Il valore del campo name indica il nome dello strumento, ad esempio list_log_entries.
Il campo arguments contiene le informazioni richieste dall'operazione per completare la richiesta.
Lo standard MCP definisce un campo _meta, che consente a client e server di allegare metadati alle loro interazioni. I client e i server possono utilizzare questo campo per passare il contesto della traccia:
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "NAME",
"arguments": {
// provide these details according to the tool's MCP specification
},
"_meta": {
"traceparent": "00-TRACE_ID-PARENT_SPAN_ID-SAMPLED_FLAG",
"tracestate": "Vendor specific information."
},
},
"id": 1
}
I dati _meta includono un campo traceparent. Il formato del valore di questo campo è definito dall'intestazione traceparent del World Wide Web Consortium (W3C). Il valore include:
- Versione della specifica
traceparent(00). - ID della traccia (TRACE_ID).
- ID dell'intervallo di chiamata (PARENT_SPAN_ID).
- Indica se lo span di chiamata ha campionato la richiesta (SAMPLED_FLAG). Questo campo ha il valore
01se campionato e00se non campionato.
Il campo tracestate contiene informazioni di tracciamento specifiche del fornitore.
Limitazioni
Il contesto della traccia deve seguire lo standard W3C Trace Context e il flag
sampleddeve essere impostato su 1.I server MCP Google Cloud remoti possono generare un singolo intervallo per un'operazione
tools/call, ma non generano intervalli per altri tipi di operazioni o intervalli secondari per l'operazionetools/call.I server MCP Google Cloud remoti generano uno span solo quando la richiesta viene autenticata, autorizzata e supera altri controlli interni.
Server MCP che supportano il tracciamento
Questa sezione elenca i server Google e Google Cloud server MCP remoti che supportano il tracciamento. Descrive inoltre come i server MCP in hosting autonomo possono generare intervalli di traccia.
Server self-hosted
Ti consigliamo di instrumentare i tuoi server MCP in hosting autonomo per inviare dati di telemetria al tuo progetto Google Cloud .
Se utilizzi Python, la strumentazione può generare intervalli per le operazioni tools/call. Per saperne di più, consulta Strumenta un server MCP in hosting autonomo con OpenTelemetry.
Server Google e Google Cloud MCP remoti che supportano il tracciamento
I seguenti prodotti contengono un'integrazione che consente al loro server MCP remoto di generare un intervallo di traccia per un'operazione tools/call:
Configura la tua applicazione
Puoi utilizzare qualsiasi framework o SDK che trasmetta il contesto della traccia utilizzando il campo _meta. Questi framework e SDK includono quelli che supportano le convenzioni semantiche di OpenTelemetry per MCP.
Ad esempio, puoi utilizzare il framework Agent Development Kit (ADK). Per saperne di più, consulta Strumenta le applicazioni ADK con OpenTelemetry.
Visualizza gli intervalli
Per visualizzare i dati di traccia, utilizza Esplora tracce. Questa pagina ti consente di visualizzare dati aggregati sui dati di traccia ed esplorare singole tracce e span. Per saperne di più, consulta Trova ed esplora le tracce.
Per visualizzare gli intervalli scritti dai server MCP, filtra i dati di traccia in base al nome dell'intervallo. Ad esempio, alcuni server MCP Google Cloud remoti possono generare un intervallo di traccia quando ricevono un'operazione tools/call. Questi intervalli hanno la seguente convenzione di denominazione:
tools/call NAME
Nell'espressione precedente, NAME si riferisce allo strumento richiamato, ad esempio list_keys. Questa convenzione di denominazione è definita dalle convenzioni semantiche di OpenTelemetry per MCP.
Per trovare questi intervalli, utilizza la barra dei filtri e aggiungi un filtro degli attributi per mcp.method.name. Imposta il valore del filtro su tools/call. Per informazioni dettagliate su questi passaggi, consulta Visualizza le chiamate ai server MCP remoti.
Campioni di strumentazione
Per i suggerimenti sull'instrumentazione, consulta Scegli un approccio di instrumentazione.
Gli esempi di strumentazione che forniamo utilizzano OpenTelemetry:
Per gli esempi che utilizzano un'esportazione basata su un raccoglitore, consulta quanto segue:
Questi esempi inviano al tuo progetto dati di log, metriche e tracce che seguono il formato OpenTelemetry Protocol (OTLP) utilizzando l'API Telemetry.
Per informazioni su come utilizzare un'esportazione diretta dei dati di traccia e inviarli all'API Telemetry, consulta Esegui la migrazione dall'esportatore di Trace all'endpoint OTLP.
Per esempi che mostrano come configurare un'applicazione agentica per raccogliere prompt e risposte, consulta Osservabilità per gli sviluppatori di agenti AI.