View a markdown version of this page

Configuração e entrega de telemetria - Base da Amazônia AgentCore
Configurar a observabilidadeModos de entrega de telemetriaO que o serviço lê em um intervaloReferênciasAgentes de amostra

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

Configuração e entrega de telemetria

Seu agente emite períodos que a Amazon Bedrock AgentCore Evaluations usa para reconstruir cada sessão. Para saber como AgentCore representa sessões, rastreamentos e extensões, consulte Compreender a observabilidade de recursos agentes em. AgentCore

Para pontuar uma sessão, o serviço precisa do conteúdo da conversa: as solicitações do modelo, as conclusões do modelo e as entradas e saídas da ferramenta. A localização desse conteúdo depende de como seu agente fornece telemetria, e é isso que esta página explica.

Tópicos

Configurar a observabilidade

Instrumentar seu agente é uma parte da produção de telemetria que o serviço de avaliação possa ler. Seu agente também deve ter a observabilidade ativada para exportar sua telemetria para a Amazon. CloudWatch Execute as etapas a seguir:

  1. Ative a pesquisa CloudWatch de transações da Amazon. A avaliação exige isso em ambos os modos de entrega. Consulte Habilitando a AgentCore observabilidade.

  2. Permita a observabilidade do seu agente, com base em onde você o hospeda:

  3. Verifique qual modo de entrega seu agente usa, para que você saiba onde sua telemetria chega. Os agentes que você criou em ou após 20 de julho de 2026 usam telemetria unificada por padrão, e os agentes que você criou antes dessa data usam telemetria dividida. A telemetria unificada precisa da versão 0.18.0 ou posterior do ADOT (). aws-opentelemetry-distro>=0.18.0 As versões anteriores enviam extensões para o grupo de aws/spans registros compartilhados.

    Para um agente no AgentCore Runtime, você alterna os modos com a variável de UNIFIED_TRACES_DESTINATION_ENABLED ambiente: defina-a como true para telemetria unificada ou false para telemetria dividida. Para as variáveis de ambiente, as permissões do IAM e o procedimento completo para cada opção de hospedagem, consulte Destino de Span para agentes hospedados no tempo de AgentCore execução do Amazon Bedrock.

Alterar o modo de entrega não move a telemetria que AgentCore já foi entregue. Os períodos mais antigos permanecem no grupo de registros em que foram gravados, portanto, o serviço ainda avalia uma sessão que você gravou antes da alteração.

Modos de entrega de telemetria

AgentCore fornece a telemetria do seu agente em um dos dois modos:

  • A telemetria unificada (recomendada) mantém tudo sob controle. Os atributos que transportam as cargas do modelo e as solicitações e respostas da ferramenta permanecem inalterados, e toda a telemetria do seu agente vai para um grupo de registros.

  • A telemetria dividida separa os dois. O AWS Distro for OpenTelemetry (ADOT) move esses atributos do intervalo para registros separados, que vão para um grupo de registros diferente dos intervalos.

AgentCore As avaliações leem os dois modos. Você não escolhe entre eles no serviço de avaliação, e os mesmos avaliadores fornecem os mesmos resultados de qualquer maneira. Recomendamos a telemetria unificada, que está disponível em todas as regiões AWS comerciais em que o AgentCore Runtime está disponível.

Telemetria unificada (recomendada)

Com a telemetria unificada, toda a telemetria do seu agente vai para um grupo de registros. Os spans vão para o fluxo de spans log nesse grupo de logs, ao lado dos próprios registros do agente e da saída do console. O span mantém os atributos que transportam as cargas do modelo e as solicitações e respostas da ferramenta, para que o serviço leia tudo o que precisa do próprio span.

Telemetria unificada: o ADOT envia cada intervalo com seu conteúdo para um grupo de registros

O grupo de registros que contém os períodos depende de onde você hospeda o agente:

  • No Amazon Bedrock AgentCore Runtime: o grupo de logs do agente,/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>. AgentCore configura isso para você.

  • Hospedado fora do AgentCore Runtime: o grupo de registros que você nomeia na variável de OTEL_EXPORTER_OTLP_TRACES_HEADERS ambiente.

Manter extensões e registros em um só lugar ajuda além da avaliação. Você pode analisar rastreamentos e registros juntos, escrever políticas de gerenciamento de AWS identidade e acesso (IAM) e configurar a criptografia de chaves gerenciada pelo cliente para um único agente e exportar tudo o que um agente produz ao se inscrever em um grupo de registros.

Telemetria dividida

Com a telemetria dividida, o ADOT elimina as grandes cargas úteis. Ao exportar cada intervalo, ele extrai os atributos que transportam as cargas úteis do modelo e as solicitações e respostas da ferramenta e os envia como registros de eventos separados, deixando o intervalo com seus metadados e seus atributos menores. Os registros de eventos existem somente nesse modo e seguem a convenção de OpenTelemetry eventos.

Cada registro de evento é vinculado à sua extensão por meio de um traceId e compartilhadospanId, e o conteúdo fica no registrobody, por exemplo, em body.input.messages body.output.messages e.

Telemetria dividida: o ADOT envia períodos aws/spans e conteúdo da conversa para o grupo de log do agente como registros de eventos

Os dois tipos de registro então vão para lugares diferentes:

  • As extensões vão para o grupo de aws/spans registros compartilhados. CloudWatch cria esse grupo de registros quando você ativa a Pesquisa de transações.

  • Os registros de eventos vão para um grupo de registros separado. Em AgentCore Runtime, esse é o grupo de registros do agente, no fluxo de otel-rt-logs registros, que é AgentCore configurado para você. Fora do AgentCore Runtime, é o grupo de log que você nomeia na variável de OTEL_EXPORTER_OTLP_LOGS_HEADERS ambiente.

Para avaliar uma sessão, o serviço lê os períodos aws/spans e os associa aos registros do evento.

O que o serviço lê em um intervalo

Para cada período em uma sessão, o serviço faz o seguinte:

  1. Determina o tipo de extensão, com base nos atributos definidos pela estrutura. Um intervalo pode ser um intervalo de invocação do agente (a execução do agente de nível superior), um intervalo da ferramenta de execução (uma única chamada de ferramenta) ou um intervalo de inferência (uma única chamada de modelo).

  2. Lê os valores necessários, como a solicitação do usuário, a resposta do agente e as entradas e saídas da ferramenta. Por exemplo, a solicitação do usuário vem da mensagem da função do usuário na entrada do agente e a resposta do agente vem da mensagem da função de assistente na saída do agente.

Os atributos que identificam um intervalo sempre permanecem nele, em ambos os modos de entrega. Somente o conteúdo da conversa é movido. A localização desse conteúdo no intervalo também depende da sua biblioteca de instrumentação: a maioria das bibliotecas o registra como atributos do intervalo e algumas o anexam ao intervalo como eventos. Para cada biblioteca, as páginas por estrutura listam os atributos de identificação, dizem onde está o conteúdo e mostram exemplos de extensões para os dois modos.

Referências

AgentCore As avaliações se baseiam nas seguintes especificações: OpenTelemetry

Agentes de amostra

Os exemplos a seguir mostram como instrumentar um agente Strands hospedado fora do Amazon Bedrock AgentCore Runtime. Cada exemplo exporta telemetria para a Amazon CloudWatch usando ADOT. Eles se concentram na configuração de observabilidade em vez da API de avaliação. Os exemplos usam Strands, mas o mesmo padrão de hospedagem e exportação de telemetria se aplica a outras estruturas compatíveis, como. LangGraph