Analizzare le chiamate MCP utilizzando Trace

Cloud Trace raccoglie e visualizza dati, come chiamate di strumenti, invocazioni di metodi, prompt e risposte, per aiutarti a comprendere il comportamento delle tue applicazioni agentiche. Questo documento descrive come configurare un'applicazione agentica che chiama i server MCP di Google Cloud remoti per consentire a questi server di generare span che registrano lo stato delle chiamate.

Uno span registra una singola funzione o operazione che fa parte di un'operazione end-to-end più grande. Una traccia rappresenta una singola operazione end-to-end ed è composta da span. Pertanto, una traccia fornisce informazioni sulla sequenza di funzioni chiamate e sulla latenza complessiva, mentre uno span fornisce informazioni sullo stato e sulla latenza per una funzione specifica.

Informazioni sugli strumenti

Gli strumenti consentono a un agente di raccogliere informazioni al di fuori dei dati di addestramento, in genere interagendo con le API esterne. Con i server MCP di Google Cloud, le applicazioni agentiche possono chiamare strumenti che richiamano i metodi API Google Cloud . Ad esempio, l'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 link alla relativa documentazione di riferimento, consulta Prodotti supportati.

Come viene passato il contesto di traccia a un server MCP

Le pagine di riferimento MCP, come la documentazione di 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 elenca 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 interazioni. Client e server possono utilizzare questo campo per passare il contesto di 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 dal World Wide Web Consortium (W3C) traceparent header. Il valore include quanto segue:

  • Versione della specifica traceparent (00).
  • ID della traccia (TRACE_ID).
  • ID dello span chiamante (PARENT_SPAN_ID).
  • Specifica se lo span chiamante ha campionato la richiesta (SAMPLED_FLAG). Questo campo ha un valore di 01 quando viene campionato e 00 quando non viene campionato.

Il campo tracestate contiene informazioni di tracciamento specifiche del fornitore.

Limitazioni

  • Il contesto di traccia deve seguire lo standard W3C Trace Context, e il flag sampled deve essere impostato su 1.

  • I server MCP di Google Cloud remoti possono generare un singolo span per un'operazione tools/call, ma non generano span per altri tipi di operazioni o span secondari per l'operazione tools/call.

  • I server MCP di Google Cloud remoti generano uno span solo quando la richiesta viene autenticata, autorizzata e supera altri controlli interni.

Server MCP di Google e remoti che supportano il tracciamento Google Cloud

I seguenti prodotti contengono un'integrazione che consente al server MCP remoto di generare uno span di traccia per un'operazione tools/call:

Come configurare l'applicazione

Puoi utilizzare qualsiasi framework o SDK che passi il contesto di traccia utilizzando il _meta campo. Questi framework e SDK includono quelli che supportano le convenzioni semantiche OpenTelemetry per MCP.

Ad esempio, puoi utilizzare il framework Agent Development Kit (ADK). Per saperne di più, consulta Instrumentare le applicazioni ADK con OpenTelemetry.

Come visualizzare gli span

Per visualizzare i dati di traccia, utilizza Trace Explorer. Questa pagina consente di visualizzare informazioni aggregate sui dati di traccia ed esplorare singole tracce e span. Per saperne di più, consulta Trovare ed esplorare le tracce.

Per visualizzare gli span scritti dai server MCP, filtra i dati di traccia in base al nome dello span. Ad esempio, alcuni server MCP di Google Cloud remoti possono generare uno span di traccia quando ricevono un'operazione tools/call. Questi span hanno la seguente convenzione di denominazione:

tools/call NAME

Nell'espressione precedente, NAME si riferisce all'endpoint richiamato. Ad esempio, potrebbe essere qualcosa di simile a list_keys. Questa convenzione di denominazione è definita dalle convenzioni semantiche OpenTelemetry per MCP.

Per trovare questi span, utilizza la barra dei filtri e aggiungi un filtro di attributi per mcp.method.name. Imposta il valore del filtro su tools/call.

Esempi di strumentazione

Per consigli sulla strumentazione, consulta Scegliere un approccio di strumentazione.

Gli esempi di strumentazione che forniamo utilizzano OpenTelemetry: