As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

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 quanto ao tempo de AgentCore 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 nos registros. CloudWatch

Permitindo 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.

Habilitando 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 AWS SDKs.

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

Destino do Span para agentes hospedados no ambiente 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 fluxo de spans log em /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name> vez do grupo de aws/spans log compartilhado. Você pode manter extensões, registros estruturados e saída padrão juntos em um grupo de registros por agente, definir o escopo do controle de acesso e da 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 de extensão padrão. Os agentes criados antes de uma região oferecer suporte ao destino unificado do span 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 períodos ao grupo de registros do agente, o seguinte deve ser verdadeiro:

Alterar o destino da extensão não move os dados de extensão existentes. Os períodos 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 abrangência 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 embutido para as convenções semânticas OTEL e GenAI e também pode ser instrumentada com um pacote de instrumentação automática, como. LangChain opentelemetry-instrument-langchain Também é possível enviar convenções semânticas generativas de IA, telemetria e extensões definindo um rastreador personalizado. AgentCore suporta o uso das seguintes bibliotecas de instrumentação em sua estrutura de agentes:

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 código do seu agente.

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

Adicione observabilidade ao seu agente AgentCore

Permitindo 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 ADOT SDK ao seu código.

Se você hospedar seu agente no AWS Lambda, use o AWS Lambda Layer for OpenTelemetry no site AWS Distro for. OpenTelemetry Adicione a camada à sua função e 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 Open Telemetry 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 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>Substitua pelo nome do seu agente e <agent-id> por um identificador exclusivo para o 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

Permitindo 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 os destinos de registro para você.

Para recursos de memória e gateway, você pode configurar destinos de registro no console ou usando um AWS SDK. Se você usar o console para configurar um destino de CloudWatch registros, o nome do grupo de registros padrão 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 registro nos registros do Amazon S3 ou nos registros de stream do Firehose usando o AgentCore console. Para saber mais sobre como armazenar logs no Amazon S3 ou 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 registro fornecidos (memória) ou Dados de registro fornecidos (gateway).

Para recursos de ferramentas incorporados, 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 registro, precisará configurar manualmente os destinos de registro 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 registro usando o console

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

Configurar 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 observabilidade e rastreamento:

Observabilidade aprimorada das 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 práticas recomendadas 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 como true desativa as variáveis de ambiente ADOT padrão do AgentCore tempo de execução, garantindo que nenhuma das configurações padrão do ADOT seja definida.