Añada observabilidad a sus recursos de Amazon Bedrock AgentCore

Amazon Bedrock AgentCore proporciona una serie de métricas integradas para supervisar el rendimiento de los recursos para el tiempo de AgentCore ejecución, la memoria, la puerta de enlace, las herramientas integradas y los tipos de recursos de identidad. Estos datos predeterminados están disponibles en Amazon CloudWatch. Para ver toda la gama de datos de observabilidad en la CloudWatch consola o generar métricas de tiempo de ejecución personalizadas para los agentes, debe instrumentar el código con el SDK AWS Distro for Open Telemetry (ADOT).

Para ver el panel de observabilidad en CloudWatch, abre la página de Amazon CloudWatch GenAi Observability.

Consulte las siguientes secciones para obtener más información sobre cómo configurar sus recursos para ver las métricas de observabilidad en la página de observabilidad de la IA generativa de la CloudWatch consola y en los registros. CloudWatch

Habilitar la observabilidad AgentCore

Para ver las métricas, los intervalos y los seguimientos generados por el AgentCore servicio, primero debes completar una configuración única para activar Amazon CloudWatch Transaction Search. Para ver los intervalos de recursos de memoria proporcionados por el servicio, también debes habilitar el rastreo al crear una memoria. Consulte Habilitar la observabilidad del AgentCore tiempo de ejecución, la memoria, la puerta de enlace, las herramientas integradas y los recursos de identidad para obtener más información.

En las siguientes secciones se describe cómo realizar estas acciones de configuración y cómo habilitar la observabilidad en el código de su agente.

Habilitar la búsqueda CloudWatch de transacciones

Puede habilitar la búsqueda de CloudWatch transacciones mediante la CloudWatch consola o mediante una API a través de la interfaz de línea de AWS comandos (AWS CLI) o uno de los AWS SDK.

Utilice uno de los siguientes procedimientos para activar la búsqueda de transacciones.

Destino de Span para los agentes alojados en Amazon Bedrock Runtime AgentCore

Con AgentCore Runtime, una capacidad de Amazon Bedrock AgentCore, puede configurar un agente para que entregue sus intervalos al mismo grupo de CloudWatch registros de Amazon que los registros del agente. Con esta configuración, los intervalos van al flujo de spans registros/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>, en lugar de al grupo de registros compartidoaws/spans. Puede mantener los intervalos, los registros estructurados y los resultados estándar juntos en un grupo de registros por agente, limitar el control de acceso y el cifrado a un agente individual y exportar la telemetría desde una única ubicación.

En AWS las regiones compatibles, los agentes recién creados utilizan el grupo de registros del agente como destino del intervalo predeterminado. Los agentes creados antes de que una región sea compatible con el destino del tramo unificado mantienen el grupo de aws/spans registros compartido como predeterminado.

Puede anular el valor predeterminado de un agente individual con la variable de UNIFIED_TRACES_DESTINATION_ENABLED entorno en el tiempo de ejecución de su agente:

AgentCore Para entregar los intervalos al grupo de registros del agente, debe cumplirse lo siguiente:

Al cambiar el destino del intervalo no se mueven los datos del intervalo existentes. Los tramos que AgentCore ya se entregaron permanecen en su grupo de registros original.

Habilitar la observabilidad en el código del agente para los agentes AgentCore-hosted

Además de las métricas generadas por el servicio, también AgentCore puedes recopilar datos de alcance y rastreo, así como métricas personalizadas emitidas por el código de tu agente.

Cuando utiliza marcos de agentes como Strands o CrewAI con bibliotecas de instrumentación de terceros compatibles, el marco en sí viene con soporte integrado para las convenciones semánticas de OTEL y GenAI, y también se puede instrumentar con un paquete de autoinstrumentación, como. LangChainopentelemetry-instrument-langchain También es posible enviar telemetría y extensiones a las convenciones semánticas de la IA generativa mediante la definición de un rastreador personalizado. AgentCore admite el uso de las siguientes bibliotecas de instrumentación en el marco de sus agentes:

Para ver estos datos en la página de observabilidad de la IA generativa de la CloudWatch consola y en Amazon CloudWatch, debe añadir el SDK AWS Distro for Open Telemetry (ADOT) a su código de agente.

Para añadir la compatibilidad con ADOT y habilitar AgentCore la observabilidad, siga los pasos del siguiente procedimiento.

Añada observabilidad a su agente AgentCore

Habilitar la observabilidad para los agentes alojados fuera de AgentCore

Para habilitar la observabilidad de los agentes alojados fuera del AgentCore entorno de ejecución, primero siga los pasos de las secciones anteriores para activar la búsqueda de CloudWatch transacciones y añadir el SDK de ADOT a su código.

Si aloja su agente en AWS Lambda, utilice la capa AWS Lambda para OpenTelemetry en el AWS sitio web Distro for. OpenTelemetry Añada la capa a su función y, a continuación, defina la variable de AWS_LAMBDA_EXEC_WRAPPER entorno en. /opt/otel-instrument Luego, la capa instrumenta automáticamente tu función. Con este enfoque, no es necesario añadir el aws-opentelemetry-distro paquete ni ejecutar el opentelemetry-instrument comando descrito anteriormente.

Para los agentes que se ejecutan fuera del AgentCore entorno de ejecución, también es necesario crear un grupo de registro de agentes que se incluya en las variables de entorno.

Configure las variables de AWS entorno y, a continuación, configure las variables de entorno de Open Telemetry como se muestra a continuación.

AWS variables de entorno

AWS_ACCOUNT_ID=<account id>
AWS_DEFAULT_REGION=<default region>
AWS_REGION=<region>
AWS_ACCESS_KEY_ID=<access key id>
AWS_SECRET_ACCESS_KEY=<secret key>

variables de entorno OTEL

AGENT_OBSERVABILITY_ENABLED=true
OTEL_PYTHON_DISTRO=aws_distro
OTEL_PYTHON_CONFIGURATOR=aws_configurator # required for ADOT Python only
OTEL_RESOURCE_ATTRIBUTES=service.name=<agent-name>,aws.log.group.names=/aws/bedrock-agentcore/runtimes/<agent-id>,cloud.resource_id=<AgentEndpointArn:AgentEndpointName> # endpoint is optional
OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=/aws/bedrock-agentcore/runtimes/<agent-id>,x-aws-log-stream=runtime-logs,x-aws-metric-namespace=bedrock-agentcore
OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-aws-log-group=/aws/bedrock-agentcore/runtimes/<agent-id>,x-aws-log-stream=spans # (Optional) Directs spans to your log group instead of the aws/spans log group. Requires ADOT version 0.18.0 or later.
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_TRACES_EXPORTER=otlp
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false # AWS Lambda Layer for OpenTelemetry only: disables Application Signals
OTEL_LOGS_EXPORTER=otlp # AWS Lambda Layer for OpenTelemetry only: exports logs over OTLP
OTEL_METRICS_EXPORTER=awsemf # AWS Lambda Layer for OpenTelemetry only: exports metrics as CloudWatch EMF

<agent-name>Sustitúyalo por el nombre de su agente y <agent-id> por un identificador único para su agente.

Compatibilidad con ID de sesión

Para propagar el identificador de sesión, debe invocarlo utilizando el identificador de sesión que se encuentra en el equipaje del OTEL:

from opentelemetry import baggage

ctx = baggage.set_baggage("session.id", session_id) # Set the session.id in baggage
attach(ctx) # Attach the context to make it active token

Permite observar el tiempo de AgentCore ejecución, la memoria, la puerta de enlace, las herramientas integradas y los recursos de identidad

Al crear un recurso en AgentCore tiempo de ejecución (agente), de forma predeterminada, en tiempo de AgentCore ejecución se crea un grupo de CloudWatch registros para los registros proporcionados por el servicio. Sin embargo, en el caso de los recursos de memoria, puerta de enlace y herramientas integradas, AgentCore no configura automáticamente los destinos de los registros.

En el caso de los recursos de memoria y puerta de enlace, puede configurar los destinos de registro en la consola o mediante un AWS SDK. Si usa la consola para configurar un destino de CloudWatch registros, el nombre del grupo de registros predeterminado para los recursos de memoria y puerta de enlace /aws/vendedlogs/bedrock-agentcore/{resource-type}/APPLICATION_LOGS/{resource-id} tendrá el siguiente {resource-type} formato: memory ogateway.

Para los registros de memoria y puerta de enlace, también puede configurar los destinos de los registros en los registros de Amazon S3 o en los registros de transmisión de Firehose mediante la AgentCore consola. Para obtener más información sobre el almacenamiento de registros en Amazon S3 o Firehose, consulte Carga, descarga y trabajo con objetos en Amazon S3 y Creación de una transmisión de entrega de Amazon Data Firehose.

Para obtener más información sobre la salida de datos de registro AgentCore para los recursos de memoria y puerta de enlace, consulte Datos de registro proporcionados (memoria) o Datos de registro proporcionados (puerta de enlace).

En el caso de los recursos de herramientas integrados, el AgentCore servicio no proporciona registros de forma predeterminada, pero puedes generar tus propios registros a partir del código. Si proporciona sus propios resultados de registro, tendrá que configurar manualmente los destinos de registro para almacenar estos datos.

Para ver qué datos de observabilidad AgentCore proporcionan de forma predeterminada para cada tipo de recurso, consulte los datos de observabilidad AgentCore generados por Amazon Bedrock.

Configure los destinos de los registros mediante la consola

Para configurar los destinos de los registros de la memoria o de la puerta de enlace en la AgentCore consola, utilice los siguientes procedimientos.

Configure el seguimiento de la entrega para CloudWatch usar la consola

En esta sección, se describe cómo habilitar la entrega de trazas CloudWatch para realizar un seguimiento del flujo de interacciones a través de la aplicación, lo que permite visualizar las solicitudes, identificar los obstáculos en el rendimiento, solucionar errores y optimizar el rendimiento.

Configure los CloudWatch recursos mediante un AWS SDK

Para configurar una fuente de entrega de registros y seguimientos (SDK)

import boto3

def enable_observability_for_resource(resource_arn, resource_id, account_id, region='us-east-1'):
    """
    Enable observability for a Bedrock AgentCore resource (e.g., Memory Store)
    """
    logs_client = boto3.client('logs', region_name=region)

    # Step 0: Create new log group for vended log delivery
    log_group_name = f'/aws/vendedlogs/bedrock-agentcore/{resource_id}'
    logs_client.create_log_group(logGroupName=log_group_name)
    log_group_arn = f'arn:aws:logs:{region}:{account_id}:log-group:{log_group_name}'

    # Step 1: Create delivery source for logs
    logs_source_response = logs_client.put_delivery_source(
        name=f"{resource_id}-logs-source",
        logType="APPLICATION_LOGS",
        resourceArn=resource_arn
    )

    # Step 2: Create delivery source for traces
    traces_source_response = logs_client.put_delivery_source(
        name=f"{resource_id}-traces-source",
        logType="TRACES",
        resourceArn=resource_arn
    )

    # Step 3: Create delivery destinations
    logs_destination_response = logs_client.put_delivery_destination(
        name=f"{resource_id}-logs-destination",
        deliveryDestinationType='CWL',
        deliveryDestinationConfiguration={
            'destinationResourceArn': log_group_arn,
        }
    )

    # Traces required
    traces_destination_response = logs_client.put_delivery_destination(
        name=f"{resource_id}-traces-destination",
        deliveryDestinationType='XRAY'
    )

    # Step 4: Create deliveries (connect sources to destinations)
    logs_delivery = logs_client.create_delivery(
        deliverySourceName=logs_source_response['deliverySource']['name'],
        deliveryDestinationArn=logs_destination_response['deliveryDestination']['arn']
    )

    # Traces required
    traces_delivery = logs_client.create_delivery(
        deliverySourceName=traces_source_response['deliverySource']['name'],
        deliveryDestinationArn=traces_destination_response['deliveryDestination']['arn']
    )

    print(f"Observability enabled for {resource_id}")
    return {
        'logs_delivery_id': logs_delivery['id'],
        'traces_delivery_id': traces_delivery['id']
    }

# Usage example
resource_arn = "arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/my-memory-id"
resource_id = "my-memory-id"
account_id = "123456789012"

delivery_ids = enable_observability_for_resource(resource_arn, resource_id, account_id)

Observabilidad mejorada en AgentCore tiempo de ejecución con encabezados personalizados

Puede invocar a su agente con encabezados HTTP adicionales para ofrecer opciones de observabilidad mejoradas. En el siguiente ejemplo, se muestran las invocaciones, incluidas las solicitudes de encabezados adicionales opcionales para los agentes alojados en el entorno de ejecución. AgentCore

Ejemplo de invocación a Boto3

def invoke_agent(agent_id, payload, session_id=None):
    client = boto3.client("bedrock-agentcore", region="us-west-2")
    response = client.invoke_agent_runtime(
        agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/test_agent_boto2-nIg2xk3VSR",
        runtimeSessionId="12345678-1234-5678-9abc-123456789012",
        payload='{"query": "Plan a weekend in Seattle"}',
    )

Puede incluir los siguientes encabezados opcionales al invocar a su agente para mejorar las capacidades de observación y rastreo:

Observabilidad mejorada AgentCore de las herramientas integradas con encabezados personalizados

Puede invocar sus Built-in herramientas con encabezados HTTP adicionales para ofrecer opciones de observabilidad mejoradas. Puedes incluir los siguientes encabezados opcionales al integrar las siguientes API de Build-in herramientas para mejorar las capacidades de observabilidad y rastreo:

Las siguientes API admiten encabezados personalizados:

Observabilidad de AgentCore identidad mejorada con encabezados personalizados

Puede invocar sus recursos de identidad con encabezados HTTP adicionales para ofrecer opciones de observabilidad mejoradas. Puede incluir los siguientes encabezados opcionales al integrar las siguientes API de identidad para mejorar las capacidades de observabilidad y rastreo:

Las siguientes API admiten encabezados personalizados:

Mejores prácticas de observabilidad

Tenga en cuenta las siguientes prácticas recomendadas al implementar la observabilidad para los agentes en: AgentCore

Uso de otras plataformas de observabilidad

Para integrar los agentes alojados en el AgentCore entorno de ejecución con otras plataformas de observabilidad para capturar y ver los resultados de telemetría, defina la siguiente variable de entorno:

DISABLE_ADOT_OBSERVABILITY=true

Si se true establece esta variable para que se anulen las variables de entorno ADOT predeterminadas del AgentCore tiempo de ejecución, se garantiza que no se establezca ninguna de las configuraciones de ADOT predeterminadas.