Adicione observabilidade aos seus recursos do Amazon Bedrock AgentCore

O Amazon Bedrock AgentCore fornece várias métricas integradas para monitorar o desempenho dos recursos para o AgentCore tempo de execução, memória, gateway, ferramentas integradas e tipos de recursos de identidade. Esses dados padrão estão disponíveis na Amazon CloudWatch. Para visualizar toda a gama de dados de observabilidade no CloudWatch console ou gerar métricas de tempo de execução personalizadas para agentes, você precisa instrumentar seu código usando o SDK do AWS Distro for Open Telemetry (ADOT).

Para visualizar o painel de observabilidade em CloudWatch, abra a página Amazon CloudWatch GenAi Observability.

Consulte as seções a seguir para saber mais sobre como configurar seus recursos para visualizar métricas de observabilidade na página de observabilidade de IA generativa do CloudWatch console e em Logs. CloudWatch

Habilitando a AgentCore observabilidade

Para visualizar métricas, extensões e rastreamentos gerados pelo AgentCore serviço, primeiro você precisa concluir uma configuração única para ativar a Pesquisa de CloudWatch transações da Amazon. Para visualizar os períodos de recursos de memória fornecidos pelo serviço, você também precisa ativar o rastreamento ao criar uma memória. Consulte Habilitando a observabilidade para AgentCore tempo de execução, memória, gateway, ferramentas integradas e recursos de identidade para saber mais.

As seções a seguir descrevem como realizar essas ações de configuração e ativar a observabilidade no código do seu agente.

Ativando CloudWatch a pesquisa de transações

Você pode ativar a Pesquisa de CloudWatch Transações usando o CloudWatch console ou usando uma API por meio da Interface de Linha de AWS Comando (AWS CLI) ou de um dos SDKs. AWS

Use um dos procedimentos a seguir para ativar a Pesquisa de Transações.

Destino de extensão para agentes hospedados no tempo de execução do Amazon Bedrock AgentCore

Com o AgentCore runtime, um recurso do Amazon Bedrock AgentCore, você pode configurar um agente para entregar suas extensões ao mesmo grupo de CloudWatch registros da Amazon que os registros do agente. Com essa configuração, os spans vão para o stream de spans log in/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>, em vez do grupo de aws/spans log compartilhado. Você pode manter os intervalos, os registros estruturados e a saída padrão juntos em um grupo de registros por agente, definir o controle de acesso e a criptografia para um agente individual e exportar a telemetria de um único local.

AWS Nas regiões suportadas, os agentes recém-criados usam o grupo de registros do agente como o destino padrão do intervalo. Agentes criados antes que uma região ofereça suporte ao destino de extensão unificado mantêm o grupo de aws/spans registros compartilhados como padrão.

Você pode substituir o padrão de um agente individual pela variável de UNIFIED_TRACES_DESTINATION_ENABLED ambiente no tempo de execução do seu agente:

AgentCore Para entregar extensões ao grupo de registros do agente, o seguinte deve ser verdadeiro:

Alterar o destino do intervalo não move os dados do período existente. Os trechos que AgentCore já foram entregues permanecem em seu grupo de registros original.

Habilitando a observabilidade no código do agente para AgentCore-hosted agentes

Além das métricas geradas pelo serviço, AgentCore você também pode coletar dados de amplitude e rastreamento, bem como métricas personalizadas emitidas pelo código do seu agente.

Quando você usa estruturas de agentes como Strands ou CrewAI com bibliotecas de instrumentação de terceiros suportadas, a estrutura em si vem com suporte integrado às convenções semânticas OTEL e GenAI, e também pode ser instrumentada com um pacote de instrumentação automática, como. LangChainopentelemetry-instrument-langchain Também é possível enviar telemetria e extensões de convenções semânticas de IA generativa definindo um rastreador personalizado. AgentCore suporta o uso das seguintes bibliotecas de instrumentação em sua estrutura de agente:

Para visualizar esses dados na página de observabilidade de IA generativa do CloudWatch console e na Amazon CloudWatch, você precisa adicionar o SDK do AWS Distro for Open Telemetry (ADOT) ao seu código de agente.

Para adicionar suporte ao ADOT e ativar AgentCore a observabilidade, siga as etapas no procedimento a seguir.

Adicione observabilidade ao seu agente AgentCore

Possibilitando a observabilidade para agentes hospedados fora do AgentCore

Para permitir a observabilidade de agentes hospedados fora do AgentCore tempo de execução, primeiro siga as etapas nas seções anteriores para ativar a Pesquisa de CloudWatch transações e adicionar o SDK ADOT ao seu código.

Se você hospedar seu agente no AWS Lambda, use a camada AWS Lambda OpenTelemetry no site Distro for. AWS OpenTelemetry Adicione a camada à sua função e, em seguida, defina a variável de AWS_LAMBDA_EXEC_WRAPPER ambiente como/opt/otel-instrument. A camada então instrumenta automaticamente sua função. Com essa abordagem, você não precisa adicionar o aws-opentelemetry-distro pacote ou executar o opentelemetry-instrument comando descrito anteriormente.

Para agentes executados fora do AgentCore tempo de execução, você também precisa criar um grupo de registros de agentes que você inclua nas variáveis de ambiente.

Configure suas variáveis de AWS ambiente e, em seguida, defina suas variáveis de ambiente de Telemetria Aberta conforme mostrado a seguir.

AWS variáveis de ambiente

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>

Variáveis de ambiente do 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>Substitua pelo nome do seu agente e <agent-id> por um identificador exclusivo para seu agente.

Suporte para ID de sessão

Para propagar o ID da sessão, você precisa invocar usando o identificador de sessão na bagagem do 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

Possibilitando a observabilidade de AgentCore tempo de execução, memória, gateway, ferramentas integradas e recursos de identidade

Quando você cria um recurso AgentCore de tempo de execução (agente), por padrão, o AgentCore tempo de execução cria um grupo de CloudWatch registros para os registros fornecidos pelo serviço. No entanto, para recursos de memória, gateway e ferramentas integradas, AgentCore não configura automaticamente destinos de log para você.

Para recursos de memória e gateway, você pode configurar destinos de log no console ou usando um AWS SDK. Se você usar o console para configurar um destino de CloudWatch registros, o nome padrão do grupo de registros para recursos de memória e gateway terá o formato/aws/vendedlogs/bedrock-agentcore/{resource-type}/APPLICATION_LOGS/{resource-id}, onde {resource-type} é memory ougateway.

Para registros de memória e gateway, você também pode configurar destinos de log nos logs do Amazon S3 ou nos logs de stream do Firehose usando o console. AgentCore Para saber mais sobre como armazenar registros no Amazon S3 ou no Firehose, consulte Carregar, baixar e trabalhar com objetos no Amazon S3 e Criar um stream de entrega do Amazon Data Firehose.

Para saber mais sobre a saída de dados de log AgentCore por recursos de memória e gateway, consulte Dados de log fornecidos (memória) ou Dados de log fornecidos (gateway).

Para recursos de ferramentas integrados, o AgentCore serviço não fornece registros por padrão, mas você pode gerar seus próprios registros a partir do seu código. Se você fornecer suas próprias saídas de log, precisará configurar manualmente os destinos do log para armazenar esses dados.

Para ver quais dados de observabilidade AgentCore fornecem por padrão para cada tipo de recurso, consulte Dados de observabilidade AgentCore gerados pelo Amazon Bedrock.

Configurar destinos de log usando o console

Para configurar destinos de log para registros de memória ou gateway no AgentCore console, use os procedimentos a seguir.

Configure a entrega de rastreamento para CloudWatch usar o console

Esta seção descreve como habilitar a entrega de rastreamento CloudWatch para rastrear o fluxo de interações em seu aplicativo, permitindo que você visualize solicitações, identifique gargalos de desempenho, solucione erros e otimize o desempenho.

Configurar CloudWatch recursos usando um AWS SDK

Para configurar uma fonte de entrega para registros e rastreamentos (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)

Observabilidade aprimorada AgentCore do tempo de execução com cabeçalhos personalizados

Você pode invocar seu agente com cabeçalhos HTTP adicionais para fornecer opções aprimoradas de observabilidade. O exemplo a seguir mostra invocações, incluindo solicitações de cabeçalho adicionais opcionais para agentes hospedados no AgentCore tempo de execução.

Exemplo de invocação do 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"}',
    )

Você pode incluir os seguintes cabeçalhos opcionais ao invocar seu agente para aprimorar os recursos de observação e rastreamento:

Observabilidade aprimorada de ferramentas AgentCore integradas com cabeçalhos personalizados

Você pode invocar suas Built-in ferramentas com cabeçalhos HTTP adicionais para fornecer opções aprimoradas de observabilidade. Você pode incluir os seguintes cabeçalhos opcionais ao integrar as seguintes APIs de Build-in ferramentas para aprimorar os recursos de observabilidade e rastreamento:

As seguintes APIs oferecem suporte a cabeçalhos personalizados:

Observabilidade de AgentCore identidade aprimorada com cabeçalhos personalizados

Você pode invocar seus recursos de identidade com cabeçalhos HTTP adicionais para fornecer opções aprimoradas de observabilidade. Você pode incluir os seguintes cabeçalhos opcionais ao integrar as seguintes APIs de identidade para aprimorar os recursos de observabilidade e rastreamento:

As seguintes APIs oferecem suporte a cabeçalhos personalizados:

Melhores práticas de observabilidade

Considere as seguintes melhores práticas ao implementar a observabilidade para agentes em: AgentCore

Usando outras plataformas de observabilidade

Para integrar agentes hospedados no AgentCore tempo de execução com outras plataformas de observabilidade para capturar e visualizar saídas de telemetria, defina a seguinte variável de ambiente:

DISABLE_ADOT_OBSERVABILITY=true

Definir essa variável para true anular as variáveis de ambiente ADOT padrão do AgentCore tempo de execução, garantindo que nenhuma das configurações ADOT padrão seja definida.