Cuando implementa agentes de IA creados con marcos como Strands Agents, LangGraph y CrewAI, necesita observabilidad de su desempeño. Esto es válido ya sea que se ejecuten en Amazon Elastic Kubernetes Service (Amazon EKS), Amazon Elastic Container Service (Amazon ECS), AWS Lambda, localmente u otro proveedor de nube como Google Cloud Platform (GCP) o Microsoft Azure.
Amazon Bedrock AgentCore es una plataforma para crear, conectar y optimizar agentes a escala, con cualquier marco o modelo. Aunque Amazon Bedrock AgentCore Observability, una capacidad de Amazon Bedrock AgentCore, proporciona seguimiento, monitoreo y análisis nativos que las herramientas de monitoreo de la nube local no ofrecen de forma inmediata, solo admite de forma nativa agentes implementados en el tiempo de ejecución de AgentCore en la nube de AWS. Si sus agentes se ejecutan en otro lugar, necesita una configuración adicional para enviar telemetría al panel.
En esta publicación, le mostramos cómo configurar la observabilidad para agentes que se ejecutan fuera de AWS. Aprenderá a configurar la instrumentación automática de AWS Distro for OpenTelemetry (ADOT) en entornos que no son de AWS, enrutar la telemetría al panel de Observabilidad de AgentCore y validar la configuración de principio a fin.
El siguiente diagrama muestra el proceso de observabilidad de un extremo a otro y cómo la telemetría fluye desde los agentes al panel de observabilidad de AgentCore.
Figura 1: Canal de observabilidad de un extremo a otro desde los agentes hasta el panel de observabilidad de AgentCore
Descripción general de la solución
La solución utiliza AWS Distro for OpenTelemetry (ADOT) que se ejecuta en proceso con la aplicación del agente. ADOT instrumenta automáticamente el marco del agente y captura los intervalos de convenciones semánticas de IA generativa, luego exporta la telemetría directamente al punto final del Protocolo OpenTelemetry (OTLP) de Amazon CloudWatch mediante la autenticación SigV4 con credenciales de AWS Identity and Access Management (IAM).
El envío de telemetría desde su agente de IA a Amazon Bedrock AgentCore Observability requiere tres componentes principales:
Instrumentación automática de ADOT: AWS Distro for OpenTelemetry maneja las complejidades de exportar telemetría desde entornos que no son de AWS. Credenciales de IAM: ADOT utiliza estas claves de acceso para autenticarse con CloudWatch y reenviar la telemetría de su agente (seguimientos, métricas y registros) al panel de Observabilidad de AgentCore. Variables de entorno: contienen configuraciones específicas de OpenTelemetry relacionadas con el enrutamiento y la autenticación.
Como se ve en el siguiente diagrama, esta solución de observabilidad multiplataforma integra varios servicios de AWS. Amazon CloudWatch sirve como base y maneja la ingesta y el almacenamiento de telemetría. Amazon Bedrock AgentCore Observability agrega paneles de monitoreo especializados para agentes de IA. AWS Distro for OpenTelemetry (ADOT) proporciona capacidades de instrumentación multiplataforma. IAM protege la autenticación entre sus entornos externos y AWS.
Figura 2: Arquitectura de observabilidad multiplataforma y servicios de AWS involucrados
La observabilidad es un pilar fundamental de la IA responsable. Al enrutar la telemetría a AgentCore Observability, obtiene visibilidad de las cadenas de razonamiento de los agentes, las invocaciones de herramientas y los resultados del modelo. Esto le permite detectar alucinaciones, monitorear respuestas dañinas o fuera de tema, rastrear el uso de tokens para controlar los costos y auditar el comportamiento de los agentes en todos los entornos. Esto es especialmente crítico para los agentes que se ejecutan fuera de AWS, donde los resultados problemáticos pueden pasar desapercibidos sin una observabilidad centralizada.
Requisitos previos
Antes de comenzar, verifique que tenga:
Una cuenta de AWS: con el acceso al modelo de Amazon Bedrock configurado (este tutorial utiliza Claude Haiku). Para conocer la disponibilidad de modelos por región de AWS, consulte los modelos admitidos por región de AWS en Amazon Bedrock. para la observabilidad de AgentCore designada y los grupos de registro designados. CloudWatch Transaction Search activado en su cuenta (configuración única) Python 3.10 o posterior instalado en su entorno que no es de AWS. Credenciales de usuario de IAM (ID de clave de acceso y clave de acceso secreta) con permisos para: bedrock:InvokeModel. registros:CreateLogGroup, registros:CreateLogStream, registros:PutLogEvents. rayos x:PutTraceSegments, rayos x:PutTelemetryRecords, rayos x:GetSamplingRules y rayos x:GetSamplingTargets. reloj en la nube:PutMetricData. Acceso HTTPS saliente a puntos finales de AWS desde su entorno.
Activar la búsqueda de transacciones de CloudWatch
Si no ha activado la Búsqueda de transacciones, ejecute lo siguiente (una vez por cuenta):
Verifica que esté activo:
como funciona
La instrumentación automática de ADOT (aws-opentelemetry-distro) maneja la complejidad de exportar telemetría desde entornos que no son de AWS a CloudWatch:
Instrumentación automática: el comando opentelemetry-instrument inyecta ADOT en el tiempo de ejecución de Python. Parcha automáticamente boto3 (para llamadas de Amazon Bedrock) y el marco Strands (para períodos de razonamiento de agentes) para emitir seguimientos de OpenTelemetry. Autenticación SigV4: aws_configurator utiliza la cadena de credenciales boto3 para firmar solicitudes de exportación OTLP con SigV4. Desde entornos que no son de AWS, esto utiliza las variables de entorno AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY. Punto final de OTLP de CloudWatch: ADOT exporta seguimientos y registros al punto final de ingesta OTLP nativo de CloudWatch. El encabezado OTEL_EXPORTER_OTLP_LOGS_HEADERS dirige los registros al grupo de registros específico de AgentCore, que es cómo CloudWatch indexa los datos en el panel de observabilidad de IA generativa. Para obtener detalles sobre cómo se determina y configura la URL del punto final de CloudWatch OTLP, consulte Punto final de CloudWatch OTLP. Convenciones semánticas de IA generativa: el paquete Strands [otel] emite intervalos siguiendo las convenciones semánticas de IA generativa de OpenTelemetry, incluidos pasos de razonamiento de agentes, invocaciones de herramientas y llamadas de modelos con uso de tokens.
El siguiente diagrama muestra cómo funciona la exportación de telemetría a través de la instrumentación automática de ADOT desde entornos que no son de AWS a CloudWatch.
Figura 3: Exportación de telemetría a través de la instrumentación automática ADOT desde entornos que no son de AWS a CloudWatch
Tutorial
Siga estos pasos para configurar y ejecutar un agente de Strands en un entorno que no sea de AWS, con la telemetría enrutada a AgentCore Observability.
Paso 1: instalar dependencias
En su entorno que no es de AWS (servidor local, máquina virtual de GCP, máquina virtual de Azure o una computadora con acceso a Internet):
El paquete aws-opentelemetry-distro incluye la instrumentación automática ADOT con exportadores OTLP específicos de AWS y aws_configurator que maneja la autenticación SigV4. El paquete strands-agents[otel] proporciona emisión de trazas OpenTelemetry desde el marco Strands.
Paso 2: configurar las credenciales de AWS
Configure sus credenciales de usuario de IAM como variables de entorno.
Nota de seguridad: para implementaciones de producción, considere usar IAM Roles Anywhere en lugar de claves de acceso de larga duración. Con IAM Roles Anywhere, las cargas de trabajo locales pueden obtener credenciales temporales mediante certificados X.509.
Paso 3: configurar las variables de entorno de OpenTelemetry
Estas variables de entorno configuran ADOT para enrutar la telemetría al panel de Observabilidad de AgentCore:
Detalles de configuración clave:
AGENT_OBSERVABILITY_ENABLED=true activa el procesamiento de telemetría generativo específico de IA en ADOT. OTEL_PYTHON_DISTRO=aws_distro y OTEL_PYTHON_CONFIGURATOR=aws_configurator activan la configuración de OpenTelemetry específica de AWS, incluida la firma SigV4 para el punto final OTLP de CloudWatch. OTEL_RESOURCE_ATTRIBUTES con aws.log.group.names le indica a CloudWatch que indexe la telemetría en el panel de Observabilidad de AgentCore. Sin esto, los seguimientos van a Amazon CloudWatch Logs genéricos. OTEL_EXPORTER_OTLP_LOGS_HEADERS con x-aws-metric-namespace=bedrock-agentcore enruta las métricas en formato de métrica incrustado al espacio de nombres correcto de CloudWatch.
Paso 4: crear la aplicación del agente
Cree un archivo llamado agent_test.py con un agente de Strands:
Paso 5: Ejecute con la instrumentación automática ADOT
El comando opentelemetry-instrument envuelve su proceso de Python con ADOT, instrumentando automáticamente las llamadas de Amazon Bedrock y las operaciones del marco de Strands:
La respuesta del agente aparece en la terminal. Detrás de escena, ADOT captura seguimientos, intervalos y registros, y los exporta a CloudWatch.
Paso 6: Verificar en la observabilidad de AgentCore
Verá datos de telemetría dentro de dos o tres minutos de la ejecución. Abra la consola de Amazon CloudWatch:
Elija GenAI Observability y luego Bedrock AgentCore. En la pestaña Agentes, busque mi-agente-externo. Elija el agente para ver sesiones, seguimientos y métricas de intervalo.
La siguiente captura de pantalla muestra la telemetría del agente de Strands (mi-agente-externo) que se ejecuta en un entorno que no es de AWS, como se ve en el panel de Observabilidad de AgentCore en CloudWatch.
Figura 4: La telemetría de mi agente externo en el panel de Observabilidad de AgentCore
La consola muestra:
Nombre del agente: mi-agente-externo. Sesiones: al menos una sesión. Seguimientos: tramos de seguimiento que muestran el razonamiento del agente y las invocaciones del modelo de Amazon Bedrock. Detalles de la extensión: invoke_agent, chat, ejecutar_event_loop_cycle y chat.us.anthropic.claude-haiku abarcan con latencia y métricas de token.
La siguiente captura de pantalla muestra un seguimiento exitoso del agente de Strands (mi-agente-externo) con cuatro tramos, información del modelo y detalles de latencia y token en el panel de Observabilidad de AgentCore.
Figura 5: Detalle de seguimiento de mi agente externo con métricas de intervalo, latencia y token
Validación desde Google Cloud Platform
Para confirmar que la solución funciona desde un proveedor de nube externo, probamos la misma configuración desde Google Cloud Shell, un terminal basado en navegador que se ejecuta en la infraestructura de GCP.
Configure el entorno en Google Cloud Shell:
Ejecute el agente desde GCP:
La siguiente captura de pantalla muestra el agente de Strands (gcp-hosted-agent) ejecutándose en Google Cloud Shell (GCP) y devolviendo una respuesta exitosa.
Figura 6: El agente alojado en gcp ejecutándose en Google Cloud Shell
Verificar la telemetría entre nubes
A los dos o tres minutos de la ejecución, el agente alojado en gcp aparece en el panel de observabilidad de AgentCore junto con los agentes que se ejecutan en el tiempo de ejecución de AgentCore u otros entornos.
La siguiente captura de pantalla muestra un seguimiento exitoso del agente de Strands (gcp-hosted-agent) que se ejecuta en GCP con cuatro tramos, información del modelo y detalles de latencia y token en el panel de Observabilidad de AgentCore.
Figura 7: Detalle de seguimiento del agente alojado en gcp que se ejecuta en GCP
La telemetría es idéntica a la que produce un agente alojado en tiempo de ejecución de AgentCore. Las sesiones, los seguimientos, las métricas de duración, el uso de tokens y la latencia son visibles en el mismo panel, independientemente de dónde se ejecute el agente.
Aunque este tutorial utiliza Strands Agents, el mismo patrón basado en ADOT se aplica a otros marcos de agentes compatibles con OpenTelemetry.
Al elegir cómo implementar sus agentes de IA, comprender las compensaciones de observabilidad entre diferentes entornos de ejecución le ayudará a tomar la decisión arquitectónica correcta. Los agentes implementados directamente en el tiempo de ejecución de Amazon Bedrock AgentCore se benefician de la configuración de observabilidad automática. Los agentes que se ejecutan en entornos que no son de AWS requieren una configuración manual adicional, pero ofrecen una mayor flexibilidad de implementación. La siguiente comparación resalta las diferencias clave en la recopilación de telemetría, la administración de credenciales y los casos de uso para ayudarlo a determinar el mejor enfoque para sus requisitos.
Aspecto Tiempo de ejecución que no es de AWS Tiempo de ejecución de AgentCore Telemetría compatible ADOT: se requieren variables OTEL manuales ADOT: variables OTEL automáticas integradas Administración de credenciales Clave/secreto de acceso de IAM o roles de IAM en cualquier lugar Automático (rol de IAM) Ideal para agentes locales, GCP, Azure o un entorno que no sea de AWS Agentes implementados en AWS con AgentCore
Entornos validados
Probamos el enfoque de instrumentación automática de ADOT en dos entornos que no son de AWS:
Entorno Plataforma Resultado Local (simulado) Servidor independiente que se ejecuta en un entorno que no es AWS El agente de Strands informa telemetría (sesiones, seguimientos, intervalos) en Observabilidad de AgentCore Google Cloud Shell (GCP) Terminal basado en navegador que se ejecuta en Google Cloud Platform Telemetría de informes del agente de Strands (sesiones, seguimientos, intervalos) en Observabilidad de AgentCore
Mejores prácticas
Según nuestras pruebas, recomendamos lo siguiente al configurar AgentCore Observability multiplataforma:
Utilice nombres coherentes: el nombre.servicio en OTEL_RESOURCE_ATTRIBUTES se convierte en el nombre del agente en el panel. Utilice nombres descriptivos que identifiquen el entorno (por ejemplo, prod-onprem-support-agent y staging-gcp-research-agent). Verifique primero con get-caller-identity: antes de ejecutar el agente, confirme que sus credenciales funcionan ejecutando python -c "import boto3; print(boto3.client('sts').get_caller_identity())". Si esto falla, el ADOT también falla silenciosamente. Utilice Python 3.10 o posterior: ADOT requiere Python 3.10 o posterior. Recomendamos Python 3.12 para obtener la mejor compatibilidad con todas las dependencias. Establezca ID de sesión para conversaciones de varios turnos: utilice la API de equipaje de OpenTelemetry para propagar los ID de sesión:
Rote las credenciales con regularidad: para implementaciones de producción, evite las claves de acceso de larga duración. Considere IAM Roles Anywhere para cargas de trabajo locales o utilice la federación de identidades de su proveedor de nube para asumir roles de AWS IAM.
Limpiar
Para eliminar los recursos creados durante este tutorial:
Este tutorial utiliza Amazon Bedrock, Amazon CloudWatch y AWS X-Ray, que generan costos. Consulte las páginas de precios respectivas para obtener más detalles.
Conclusión
La observabilidad de Amazon Bedrock AgentCore no se limita a los agentes que se ejecutan en el tiempo de ejecución de AgentCore o dentro de AWS. Al utilizar la instrumentación automática de ADOT con credenciales de IAM y las variables de entorno OpenTelemetry correctas, puede enviar telemetría desde el entorno que elija con acceso a Internet. Sus agentes pueden ejecutarse en las instalaciones, en GCP, en Azure o en cualquier otro lugar y seguir informando al mismo panel de Observabilidad de AgentCore.
La configuración requiere una instalación de pip y un conjunto de variables de entorno. La telemetría resultante es idéntica a la que producen los agentes alojados en tiempo de ejecución de AgentCore: sesiones, seguimientos, métricas de intervalo y uso de tokens, todo en una vista unificada.
Para comenzar, clone el código de muestra de GitHub y siga las instrucciones en el archivo README para configurar y ejecutar el agente en su entorno.
Para los agentes que ya se ejecutan en AWS pero fuera del tiempo de ejecución de AgentCore (EKS, ECS, Lambda), consulte el tutorial de Observabilidad de AgentCore para agentes alojados en EKS. Para los agentes en el tiempo de ejecución de AgentCore, la observabilidad se configura automáticamente. Consulte Agregar observabilidad a sus recursos de AgentCore.
Sobre los autores
vipul gargav
Vipul es gerente técnico de cuentas en AWS Enterprise Support, donde brinda soporte a clientes emergentes en una variedad de cargas de trabajo con especialización en monitoreo y observabilidad. Ayuda a los clientes a diseñar y optimizar sus soluciones en la nube para lograr confiabilidad y rendimiento. Fuera del trabajo, a Vipul le gusta trabajar la madera y pasar tiempo al aire libre, andar en bicicleta y acampar.
Rajesh Kumar Ravi
Rajesh es especialista mundial y arquitecto senior de soluciones en Amazon Web Services y se especializa en Amazon Bedrock AgentCore y Amazon Quick. Es un líder tecnológico consumado con años de experiencia en liderazgo multifuncional, plataformas escalables y desarrollo de productos de inteligencia artificial empresarial, con un enfoque actual en sistemas multiagente, RAG y SaaS nativo de la nube. Fuera del trabajo, le gusta caminar y hacer excursiones cortas.