View a markdown version of this page

Configuration et livraison de la télémétrie - Base rocheuse de l'Amazonie AgentCore
Configurer l'observabilitéModes de diffusion de télémétrieCe que le service lit sur une pageRéférencesAgents d'échantillonnage

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Configuration et livraison de la télémétrie

Votre agent émet des intervalles qu'Amazon Bedrock AgentCore Evaluations utilise pour reconstruire chaque session. Pour savoir comment AgentCore représente les sessions, les traces et les étendues, voir Comprendre l'observabilité des ressources agentiques dans. AgentCore

Pour attribuer un score à une session, le service a besoin du contenu de la conversation : les instructions du modèle, les versions complètes du modèle et les entrées et sorties de l'outil. L'emplacement de ce contenu dépend de la manière dont votre agent fournit la télémétrie, et c'est ce que cette page explique.

Rubriques

Configurer l'observabilité

L'instrumentation de votre agent fait partie de la production de données télémétriques lisibles par le service d'évaluation. L'observabilité de votre agent doit également être activée pour qu'il exporte sa télémétrie vers Amazon. CloudWatch Procédez comme suit :

  1. Activez Amazon CloudWatch Transaction Search. L'évaluation l'exige dans les deux modes de prestation. Consultez la section Activation de AgentCore l'observabilité.

  2. Activez l'observabilité pour votre agent, en fonction de l'endroit où vous l'hébergez :

  3. Vérifiez le mode de livraison utilisé par votre agent afin de savoir où atterrit votre télémétrie. Les agents que vous avez créés le 20 juillet 2026 ou après cette date utilisent la télémétrie unifiée par défaut, et les agents que vous avez créés avant cette date utilisent la télémétrie fractionnée. La télémétrie unifiée nécessite la version 0.18.0 ou ultérieure d'ADOT (). aws-opentelemetry-distro>=0.18.0 Les versions précédentes envoyaient des spans au groupe de aws/spans journaux partagé.

    Pour un agent sur AgentCore Runtime, vous changez de mode à l'aide de la variable d'UNIFIED_TRACES_DESTINATION_ENABLEDenvironnement : définissez-la sur true pour la télémétrie unifiée ou false pour la télémétrie fractionnée. Pour les variables d'environnement, les autorisations IAM et la procédure complète pour chaque option d'hébergement, consultez Span destination pour les agents hébergés dans l'environnement d'exécution Amazon Bedrock AgentCore .

La modification du mode de diffusion ne déplace pas la télémétrie AgentCore déjà fournie. Les anciennes spans restent dans le groupe de journaux dans lequel elles ont été écrites, de sorte que le service évalue toujours une session que vous avez enregistrée avant la modification.

Modes de diffusion de télémétrie

AgentCore fournit la télémétrie de votre agent selon l'un des deux modes suivants :

  • La télémétrie unifiée (recommandée) permet de tout garder en place. Les attributs contenant les charges utiles du modèle ainsi que les demandes et réponses des outils restent inchangés, et toutes les données télémétriques de votre agent sont transmises à un seul groupe de journaux.

  • La télémétrie fractionnée sépare les deux. La AWS distribution pour OpenTelemetry (ADOT) déplace ces attributs hors de la plage vers des enregistrements distincts, qui sont placés dans un groupe de journaux différent de celui des plages.

AgentCore Les évaluations lisent les deux modes. Vous n'avez pas à choisir entre les deux dans le service d'évaluation, et les mêmes évaluateurs vous donnent les mêmes résultats dans les deux cas. Nous recommandons la télémétrie unifiée, qui est disponible dans toutes les régions AWS commerciales où AgentCore Runtime est disponible.

Télémétrie unifiée (recommandée)

Grâce à la télémétrie unifiée, toutes les données télémétriques de votre agent sont transmises à un seul groupe de journaux. Les spans sont redirigées vers le flux de spans journaux de ce groupe de journaux, à côté des journaux de l'agent et de la sortie de console. Le span conserve les attributs qui transportent les charges utiles du modèle ainsi que les demandes et réponses des outils, de sorte que le service lit tout ce dont il a besoin dans le span lui-même.

Télémétrie unifiée : ADOT envoie chaque span avec son contenu à un groupe de journaux

Le groupe de journaux contenant les spans dépend de l'endroit où vous hébergez l'agent :

  • Sur Amazon Bedrock AgentCore Runtime  : le groupe de journaux de l'agent,/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>. AgentCore configure cela pour vous.

  • Hébergé en dehors de AgentCore Runtime  : le groupe de journaux que vous nommez dans la variable d'OTEL_EXPORTER_OTLP_TRACES_HEADERSenvironnement.

Le fait de conserver les intervalles et les journaux au même endroit va au-delà de l'évaluation. Vous pouvez examiner les traces et les journaux ensemble, rédiger des politiques de gestion des AWS identités et des accès (IAM) et configurer le chiffrement des clés géré par le client pour un seul agent, et vous pouvez exporter tout ce qu'un agent produit en vous abonnant à un groupe de journaux.

Télémétrie fractionnée

Grâce à la télémétrie fractionnée, ADOT permet de réduire les charges utiles importantes. Au fur et à mesure qu'il exporte chaque span, il extrait les attributs contenant les charges utiles du modèle ainsi que les demandes et réponses des outils, et les envoie sous forme d'enregistrements d'événements distincts, laissant le span avec ses métadonnées et ses attributs plus petits. Les enregistrements d'événements existent uniquement dans ce mode et suivent la convention OpenTelemetry des événements.

Chaque enregistrement d'événement renvoie à sa période via un « traceId et » partagéspanId, et le contenu se trouve dans l'enregistrementbody, par exemple dans body.input.messages etbody.output.messages.

Télémétrie fractionnée : ADOT envoie des spans aws/spans et le contenu des conversations au groupe de journaux des agents sous forme d'enregistrements d'événements

Les deux types de disques sont ensuite transférés à des endroits différents :

  • Les spans vont au groupe de aws/spans journaux partagés. CloudWatch crée ce groupe de journaux lorsque vous activez la recherche de transactions.

  • Les enregistrements d'événements sont placés dans un groupe de journaux distinct. Sur AgentCore Runtime, il s'agit du groupe de journaux de l'agent, dans le flux de otel-rt-logs journaux, AgentCore qui est configuré pour vous. En dehors de AgentCore Runtime, il s'agit du groupe de journaux que vous nommez dans la variable d'OTEL_EXPORTER_OTLP_LOGS_HEADERSenvironnement.

Pour évaluer une session, le service lit les intervalles aws/spans et les associe à ses enregistrements d'événements.

Ce que le service lit sur une page

Pour chaque période d'une session, le service effectue les opérations suivantes :

  1. Détermine de quel type de span il s'agit, en fonction des attributs définis par le framework. Une étendue peut être une étendue d'agent d'invocation (l'agent de niveau supérieur exécuté), une étendue d'outil d'exécution (un seul appel d'outil) ou une étendue d'inférence (un appel de modèle unique).

  2. Lit les valeurs dont il a besoin, telles que l'invite de l'utilisateur, la réponse de l'agent et les entrées et sorties de l'outil. Par exemple, l'invite utilisateur provient du message de rôle utilisateur dans l'entrée de l'agent, et la réponse de l'agent provient du message de rôle d'assistant dans la sortie de l'agent.

Les attributs qui identifient une plage restent toujours sur la plage, dans les deux modes de livraison. Seul le contenu de la conversation est déplacé. L'emplacement de ce contenu dans la plage dépend également de votre bibliothèque d'instruments : la plupart des bibliothèques l'enregistrent sous forme d'attributs de plage, et certaines l'associent à la plage en tant qu'événements. Pour chaque bibliothèque, les pages par framework répertorient les attributs d'identification, indiquent où se trouve le contenu et montrent des exemples de périodes pour les deux modes.

Références

AgentCore Les évaluations s'appuient sur les OpenTelemetry spécifications suivantes :

Agents d'échantillonnage

Les exemples suivants montrent comment instrumenter un agent Strands hébergé en dehors d'Amazon Bedrock AgentCore Runtime. Chaque exemple exporte la télémétrie vers Amazon à l' CloudWatch aide d'ADOT. Ils se concentrent sur la configuration de l'observabilité plutôt que sur l'API d'évaluation. Les exemples utilisent Strands, mais le même modèle d'hébergement et d'exportation de télémétrie s'applique aux autres frameworks pris en charge, tels que. LangGraph