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.

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 de los tipos de recursos de AgentCore tiempo de ejecución, memoria, puerta de enlace, herramientas integradas e identidad. Estos datos predeterminados están disponibles en Amazon CloudWatch. Para ver la gama completa de datos de observabilidad en la CloudWatch consola o para generar métricas de tiempo de ejecución personalizadas para los agentes, debes instrumentar tu código con el SDK AWS Distro for Open Telemetry (ADOT).

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

Consulte las siguientes secciones para obtener más información sobre la configuración de 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 rastreos generados por el AgentCore servicio, primero debes completar una configuración única para activar la búsqueda de CloudWatch transacciones de Amazon. Para ver los intervalos de recursos de memoria proporcionados por el servicio, también debe habilitar el rastreo al crear una memoria. Consulta Cómo habilitar la observabilidad para el 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 del 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 procedimientos siguientes para habilitar la búsqueda de transacciones.

Abarca el destino de los agentes alojados en Amazon Bedrock Runtime AgentCore

Con AgentCore Runtime, una funcionalidad de Amazon Bedrock AgentCore, puede configurar un agente para que entregue sus intervalos al mismo grupo de registros de Amazon que los registros del agente. CloudWatch Con esta configuración, los intervalos van a la secuencia de spans registros en /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name> lugar de al grupo de registros compartidoaws/spans. Puede agrupar los intervalos, los registros estructurados y la salida estándar en un grupo de registros por agente, asignar 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 admita el destino de intervalo unificado mantienen el grupo de aws/spans registros compartido como predeterminado.

Puede anular la configuración predeterminada para 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 intervalos que AgentCore ya se entregaron permanecen en su grupo de registro original.

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

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

Cuando utilizas marcos de agentes como Strands o CrewAI con bibliotecas de instrumentación de terceros compatibles, el propio marco 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 por ejemplo. LangChain opentelemetry-instrument-langchain También es posible enviar telemetría e intervalos a las convenciones semánticas de la IA generativa definiendo un rastreador personalizado. https://opentelemetry.io/docs/specs/semconv/gen-ai/ https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/ AgentCore admite el uso de las siguientes bibliotecas de instrumentación en el marco de su agente:

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

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

Agregue la observabilidad a su agente AgentCore

Habilitar la observabilidad para los agentes alojados fuera de AgentCore

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

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

En el caso de los agentes que se ejecutan fuera del AgentCore tiempo de ejecución, también debes crear un grupo de registros de agentes para incluirlo en las variables de entorno.

Configure las variables de AWS entorno y, a continuación, defina 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
AWS_GENAI_CONTENT_EXTRACTION_OPT_OUT=true # Keeps model payloads and tool request/response data on spans. Requires ADOT >=0.18.0.
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úyalas por el nombre de tu agente y <agent-id> por un identificador único para tu agente.

Compatibilidad con identificadores de sesión

Para propagar el identificador de sesión, debe invocarlo utilizando el identificador de sesión incluido en el equipaje del hotel:

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

Permitir la observabilidad del AgentCore tiempo de ejecución, la memoria, la puerta de enlace, las herramientas integradas y los recursos de identidad

Al crear un recurso AgentCore de tiempo de ejecución (agente), de forma predeterminada, AgentCore Runtime 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 tiene el formato/aws/vendedlogs/bedrock-agentcore/{resource-type}/APPLICATION_LOGS/{resource-id}, donde {resource-type} es memory ogateway.

Para los registros de memoria y puerta de enlace, también puede configurar los destinos de registro 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 Cargar, descargar y trabajar con objetos en Amazon S3 y Crear 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 integradas, el AgentCore servicio no proporciona registros de forma predeterminada, pero puedes generar tus propios registros a partir de tu código. Si proporcionas tus propias salidas de registro, debes configurar manualmente los destinos de los registros 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 memoria o puerta de enlace en la AgentCore consola, utilice los procedimientos siguientes.

Configure el seguimiento de la entrega para CloudWatch utilizar la consola

En esta sección se describe cómo habilitar el seguimiento y la entrega CloudWatch para rastrear el flujo de interacciones en la aplicación, lo que permite visualizar las solicitudes, identificar los cuellos de botella en el rendimiento, solucionar los errores y optimizar el rendimiento.

Configure CloudWatch los recursos mediante un AWS SDK

Para configurar una fuente de entrega para los registros y los 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)

Se ha mejorado la capacidad AgentCore de observación en 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 encabezado adicionales opcionales para los agentes alojados en tiempo de ejecución. AgentCore

Ejemplo de invocación de 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:

Se ha mejorado la observabilidad de las herramientas AgentCore integradas con encabezados personalizados

Puedes invocar tus 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 observación y rastreo:

Las siguientes API admiten encabezados personalizados:

Se ha mejorado AgentCore la capacidad de observación de la identidad con encabezados personalizados

Puede invocar sus recursos de identidad con encabezados HTTP adicionales para ofrecer opciones de observabilidad mejoradas. Puedes incluir los siguientes encabezados opcionales al integrar las siguientes API de identidad para mejorar las capacidades de observación 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 tiempo de AgentCore ejecución con otras plataformas de observabilidad para capturar y ver los resultados de la telemetría, defina la siguiente variable de entorno:

DISABLE_ADOT_OBSERVABILITY=true

Al configurar esta variable para desactivar las variables de entorno ADOT predeterminadas del AgentCore tiempo de ejecución, se garantiza que true no se haya establecido ninguna de las configuraciones ADOT predeterminadas.