View a markdown version of this page

Configuración y entrega de telemetría - Base amazónica AgentCore
Configure la observabilidadModos de entrega de telemetríaQué lee el servicio de un intervaloReferenciasEjemplos de agentes

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Configuración y entrega de telemetría

Su agente emite intervalos que Amazon Bedrock AgentCore Evaluations utiliza para reconstruir cada sesión. Para saber cómo se AgentCore representan las sesiones, los seguimientos y los intervalos, consulte Comprender la observabilidad de los recursos de las agencias en. AgentCore

Para puntuar una sesión, el servicio necesita el contenido de la conversación: las solicitudes del modelo, las terminaciones del modelo y las entradas y salidas de la herramienta. La ubicación de ese contenido depende de la forma en que su agente entregue la telemetría, y eso es lo que se explica en esta página.

Temas

Configure la observabilidad

Instrumentar a su agente es una parte de la producción de telemetría que el servicio de evaluación pueda leer. Tu agente también debe tener habilitada la observabilidad para poder exportar su telemetría a Amazon. CloudWatch Realice los siguientes pasos:

  1. Activa la búsqueda de transacciones de Amazon CloudWatch . La evaluación lo requiere en ambos modos de entrega. Consulte Habilitar la AgentCore observabilidad.

  2. Habilite la observabilidad para su agente, según el lugar donde lo aloje:

  3. Compruebe el modo de entrega que utiliza su agente para saber dónde llega la telemetría. Los agentes que creaste el 20 de julio de 2026 o después utilizan la telemetría unificada de forma predeterminada, y los agentes que creaste antes de esa fecha utilizan la telemetría dividida. La telemetría unificada necesita la versión 0.18.0 o posterior de ADOT (). aws-opentelemetry-distro>=0.18.0 Las versiones anteriores enviaban intervalos al grupo de registros compartido. aws/spans

    En el caso de un agente en AgentCore Runtime, se cambia de modo con la variable de UNIFIED_TRACES_DESTINATION_ENABLED entorno: se establece true para telemetría unificada o false para telemetría dividida. Para ver las variables de entorno, los permisos de IAM y el procedimiento completo para cada opción de alojamiento, consulte Span el destino para los agentes alojados en Amazon Bedrock Runtime. AgentCore

Si se cambia el modo de entrega, no se mueve la telemetría que ya se ha entregado. AgentCore Los intervalos más antiguos permanecen en el grupo de registros en el que se escribieron, por lo que el servicio sigue evaluando una sesión que haya grabado antes del cambio.

Modos de entrega de telemetría

AgentCore entrega la telemetría de su agente en uno de estos dos modos:

  • La telemetría unificada (recomendada) mantiene todo en orden. Los atributos que contienen las cargas útiles del modelo y las solicitudes y respuestas de la herramienta permanecen en el mismo intervalo, y toda la telemetría del agente se destina a un grupo de registros.

  • La telemetría dividida separa los dos. La AWS distribución para OpenTelemetry (ADOT) mueve esos atributos del intervalo a registros separados, que van a un grupo de registros diferente al de los intervalos.

AgentCore Las evaluaciones leen ambos modos. En el servicio de evaluación no puedes elegir entre ellos y, de cualquier manera, los mismos evaluadores te dan los mismos resultados. Recomendamos la telemetría unificada, que está disponible en todas las regiones AWS comerciales en las que AgentCore Runtime está disponible.

Telemetría unificada (recomendada)

Con la telemetría unificada, toda la telemetría de su agente va a un grupo de registros. Los intervalos van a la secuencia de spans registros de ese grupo de registros, junto a los registros del propio agente y a la salida de la consola. El intervalo conserva los atributos que contienen las cargas útiles del modelo y las solicitudes y respuestas de la herramienta, de modo que el servicio lee todo lo que necesita del propio intervalo.

Telemetría unificada: ADOT envía cada intervalo con su contenido a un grupo de registros

El grupo de registro que contiene los intervalos depende de dónde aloje el agente:

  • En Amazon Bedrock AgentCore Runtime: el grupo de registros del agente,. /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name> AgentCore configura esto para usted.

  • Alojado fuera AgentCore de Runtime: el grupo de registros al que nombras en la variable de OTEL_EXPORTER_OTLP_TRACES_HEADERS entorno.

Mantener los intervalos y los registros en un solo lugar ayuda más allá de la evaluación. Puede analizar las trazas y los registros a la vez, elaborar políticas de administración de AWS identidades y accesos (IAM) y configurar el cifrado de claves gestionado por el cliente para un único agente, y puede exportar todo lo que produce un agente suscribiéndose a un grupo de registros.

Telemetría dividida

Con la telemetría dividida, ADOT elimina las grandes cargas útiles del espacio. A medida que exporta cada intervalo, extrae los atributos que contienen las cargas útiles del modelo y las solicitudes y respuestas de la herramienta, y los envía como registros de eventos independientes, dejando el intervalo con sus metadatos y sus atributos más pequeños. Los registros de eventos solo existen en este modo y siguen la convención de OpenTelemetry eventos.

Cada registro de eventos enlaza con su extensión a través de un enlace compartido traceId y spanId el contenido se encuentra en el registrobody, por ejemplo, en body.input.messages ybody.output.messages.

Telemetría dividida: ADOT envía los intervalos aws/spans y el contenido de las conversaciones al grupo de registro de agentes en forma de registros de eventos

Luego, los dos tipos de registro van a lugares diferentes:

  • Los intervalos van al grupo de aws/spans registros compartido. CloudWatch crea este grupo de registros al activar la búsqueda de transacciones.

  • Los registros de eventos van a un grupo de registros independiente. En AgentCore Runtime, ese es el grupo de registros del agente, en el flujo de otel-rt-logs registros, que se AgentCore configura automáticamente. Fuera AgentCore de Runtime, es el grupo de registros al que se nombra en la variable de OTEL_EXPORTER_OTLP_LOGS_HEADERS entorno.

Para evaluar una sesión, el servicio lee los intervalos aws/spans y los compara con sus registros de eventos.

Qué lee el servicio de un intervalo

Para cada intervalo de una sesión, el servicio hace lo siguiente:

  1. Determina qué tipo de intervalo es, en función de los atributos establecidos por el marco. Un intervalo puede ser un intervalo de agentes de invocación (la ejecución del agente de nivel superior), un intervalo de herramientas de ejecución (una única llamada a una herramienta) o un intervalo de inferencia (una única llamada de modelo).

  2. Lee los valores que necesita, como la solicitud del usuario, la respuesta del agente y las entradas y salidas de la herramienta. Por ejemplo, la solicitud de usuario proviene del mensaje sobre el rol del usuario que aparece en la entrada del agente y la respuesta del agente proviene del mensaje sobre el rol de asistente que aparece en la salida del agente.

Los atributos que identifican un intervalo siempre permanecen en el intervalo, en ambos modos de entrega. Solo se mueve el contenido de la conversación. La ubicación de ese contenido dentro del intervalo también depende de la biblioteca de instrumentación: la mayoría de las bibliotecas lo registran como atributos de grupo y algunas lo adjuntan al conjunto como eventos. Para cada biblioteca, las páginas por marco enumeran los atributos identificativos, indican dónde se encuentra el contenido y muestran ejemplos de los intervalos para ambos modos.

Referencias

AgentCore Las evaluaciones se basan en las siguientes especificaciones: OpenTelemetry

Ejemplos de agentes

Los siguientes ejemplos muestran cómo instrumentar un agente de Strands alojado fuera de Amazon Bedrock AgentCore Runtime. Cada ejemplo exporta la telemetría a Amazon CloudWatch mediante ADOT. Se centran en la configuración de la observabilidad más que en la API de evaluación. Los ejemplos utilizan Strands, pero el mismo patrón de alojamiento y exportación por telemetría se aplica a otros marcos compatibles, como. LangGraph