Investiga las llamadas de MCP con Trace

Cloud Trace recopila y muestra datos, como llamadas a herramientas, invocaciones de métodos, instrucciones y respuestas, para ayudarte a comprender el comportamiento de tus aplicaciones basadas en agentes. En este documento, se describe cómo configurar una aplicación basada en agentes que llama a servidores de MCP remotos de Google Cloud para permitir que estos servidores generen intervalos que registren el estado de las llamadas.

Un intervalo registra una sola función u operación que forma parte de una operación integral más grande. Un seguimiento representa una sola operación de extremo a extremo y se compone de intervalos. Por lo tanto, un registro de seguimiento proporciona información sobre la secuencia de funciones llamadas y la latencia general, mientras que un intervalo proporciona información sobre el estado y la latencia de una función específica.

Acerca de las herramientas

Las herramientas permiten que un agente recopile información fuera de sus datos de entrenamiento, por lo general, interactuando con APIs externas. Con los servidores de MCP de Google Cloud, tus aplicaciones basadas en agentes pueden llamar a herramientas que invocan métodos de la Google Cloud API. Por ejemplo, tu aplicación puede llamar a la herramienta list_log_entries para recuperar datos de registro recientes.

El Protocolo de contexto del modelo (MCP) es una especificación que define una forma estandarizada para que los agentes de IA se comuniquen e interactúen con herramientas, fuentes de datos y recursos externos. Para obtener una lista completa de los productos que proporcionan un servidor de MCP y vínculos a su documentación de referencia, consulta Productos compatibles.

Cómo se pasa el contexto de seguimiento a un servidor de MCP

Las páginas de referencia de MCP, como la documentación de list_log_entries, proporcionan un ejemplo del comando curl que puedes usar para enviar solicitudes HTTP a la herramienta. La carga útil JSON que se envía en la solicitud es similar a la siguiente:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "NAME",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "id": 1
}

El valor del campo name enumera el nombre de la herramienta, como list_log_entries. El campo arguments contiene la información que requiere la operación para completar la solicitud.

El estándar de MCP define un campo _meta, que permite que los clientes y los servidores adjunten metadatos a sus interacciones. Los clientes y los servidores pueden usar este campo para pasar el contexto de seguimiento:

{
  "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
}

Los datos de _meta incluyen un campo traceparent. El formato del valor de este campo se define en el encabezado traceparent del World Wide Web Consortium (W3C). El valor incluye lo siguiente:

  • Versión de la especificación de traceparent (00).
  • ID del registro (TRACE_ID).
  • ID del intervalo de llamada (PARENT_SPAN_ID).
  • Especifica si el intervalo de llamada muestreó la solicitud (SAMPLED_FLAG). Este campo tiene el valor 01 cuando se muestrea y 00 cuando no se muestrea.

El campo tracestate contiene información de seguimiento específica del proveedor.

Limitaciones

  • El contexto de seguimiento debe seguir el estándar de contexto de seguimiento W3C, y la marca sampled debe establecerse en 1.

  • Los servidores MCP de Google Cloud remotos pueden generar un solo intervalo para una operación tools/call, pero no generan intervalos para otros tipos de operaciones ni intervalos secundarios para la operación tools/call.

  • Los servidores de MCP remotos de Google Cloud solo generan un intervalo cuando se autentica y autoriza la solicitud, y cuando esta pasa otras verificaciones internas.

Servidores de Google y Google Cloud MCP remotos que admiten el seguimiento

Los siguientes productos contienen una integración que permite que su servidor de MCP remoto genere un intervalo de seguimiento para una operación de tools/call:

Cómo configurar tu aplicación

Puedes usar cualquier framework o SDK que pase el contexto de seguimiento con el campo _meta. Estos frameworks y SDKs incluyen aquellos que admiten las Convenciones semánticas de OpenTelemetry para MCP.

Por ejemplo, puedes usar el framework del Kit de desarrollo de agentes (ADK). Para obtener más información, consulta Instrumenta aplicaciones del ADK con OpenTelemetry.

Cómo ver los intervalos

Para ver tus datos de seguimiento, usa el Explorador de seguimiento. En esta página, puedes ver información agregada sobre tus datos de seguimiento y explorar seguimientos y períodos individuales. Para obtener más información, consulta Busca y explora seguimientos.

Para ver los tramos escritos por los servidores de MCP, filtra tus datos de seguimiento por el nombre del tramo. Por ejemplo, algunos servidores de MCP remotos de Google Cloud pueden generar un intervalo de seguimiento cuando reciben una operación tools/call. Estos intervalos tienen la siguiente convención de nomenclatura:

tools/call NAME

En la expresión anterior, NAME hace referencia al extremo invocado. Por ejemplo, podría ser algo similar a list_keys. Esta convención de nombres se define en las Convenciones semánticas de OpenTelemetry para MCP.

Para encontrar estos intervalos, usa la barra de filtros y agrega un filtro de atributo para mcp.method.name. Establece el valor del filtro en tools/call.

Ejemplos de instrumentación

Para obtener recomendaciones de instrumentación, consulta Elige un enfoque de instrumentación.

Las muestras de instrumentación que proporcionamos usan OpenTelemetry:

  • Para ver ejemplos que usan una exportación basada en un recopilador, consulta lo siguiente:

    Estos ejemplos envían datos de seguimiento a la API de Telemetry.

  • Si deseas obtener información para usar una exportación directa de datos de seguimiento y enviar esos datos a la API de Telemetry, consulta Migra del exportador de Trace al extremo de OTLP.

  • Para ver ejemplos que te muestran cómo configurar una aplicación basada en agentes para recopilar instrucciones y respuestas, consulta Cómo instrumentar tus aplicaciones de IA generativa.

  • Para saber qué servidores de MCP remotos de Google Cloud admiten la generación de registros y cómo configurar tu aplicación para indicarle a estos servidores que creen intervalos, consulta Investiga las llamadas de MCP con Trace.