View a markdown version of this page

Support du framework générique - Amazon Bedrock AgentCore
Conventions prises en chargeComment les travées sont identifiéesComment sont extraits les champs d'évaluationExigences de configuration

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.

Support du framework générique

Amazon Bedrock AgentCore Evaluations lit la télémétrie selon deux normes ouvertes : les conventions sémantiques OpenTelemetry génératives de l'IA et les conventions sémantiques. OpenInference Outre les frameworks qui ont leur propre page dans cette section, le service prend en charge tout agent qui émet de la télémétrie selon l'une de ces deux conventions. Il s'agit d'un support de framework générique.

Utilisez la prise en charge générique du framework lorsque vous créez avec un framework qui ne comporte aucune page dans cette section, ou lorsque vous écrivez votre propre instrumentation pour un agent personnalisé. Configurez votre instrumentation pour émettre le nom de l'étendue, les attributs de l'étendue et les attributs d'identification décrits sur cette page, et le service identifie vos étendues et extrait les valeurs dont les évaluateurs ont besoin, en utilisant la même classification des étendues et la même extraction de champs que les frameworks nommés.

Comme les structures de données propres à votre framework ne sont pas connues à l'avance, le service extrait chaque valeur sous forme de chaîne plutôt que de l'analyser dans une structure spécifique au framework. Conservez les invites, les réponses et les arguments de l'outil dans les attributs répertoriés dans la section Comment les champs d'évaluation sont extraits, plutôt que de les encapsuler dans votre propre structure, telle qu'un objet de demande imbriqué ou une enveloppe de message personnalisée, afin que les évaluateurs reçoivent des valeurs claires.

Rubriques

Conventions prises en charge

Le service sélectionne la manière de lire chaque plage à partir de celle de la plagescope.name. Définissez le nom du scope de votre instrumentation sur l'un des préfixes suivants, et le service lit l'intervalle avec la convention correspondante :

Convention Préfixe du nom de la portée

OpenTelemetry

opentelemetry.instrumentation.*

OpenInference

openinference.instrumentation.*

Si une étendue possède sa propre page dans cette section, le service utilise à la place le traitement décrit sur cette page. La prise en charge du framework générique s'applique à toutes les autres étendues correspondant à l'un de ces préfixes.

Certains scopes correspondent aux OpenTelemetry préfixes mais ne sont pas des frameworks d'agents GenAI. Il s'agit d'instruments de transport et d'infrastructure, tels que les clients HTTP (httpxurllib3,urllib,aiohttp_client), les frameworks Web (starlette,fastapi), l'instrumentation MCP (Model Context Protocol) et l'instrumentation AWS SDK (botocore), y compris ses interfaces bedrock-agentcore et bedrock-runtime ses scopes. Le service exclut ces étendues de la prise en charge du framework générique afin que leurs étendues ne produisent pas de fausses étendues d'agents, d'outils ou d'inférence.

Comment les travées sont identifiées

Le service classe chaque étendue dans l'un des trois types en utilisant l'attribut d'identification standard pour sa convention. Définissez cet attribut sur chaque plage que vous souhaitez évaluer. Sa valeur indique au service ce que représente l'intervalle, et le service le lit à partir de l'intervalle lui-même, quel que soit l'endroit où le contenu de la conversation est stocké.

Exemple
OpenTelemetry

Le service classe les spans en utilisant gen_ai.operation.name le nom de l'opération et revient au traceloop.span.kind moment où le nom de l'opération est absent.

Type d'envergure Attribut d'identification

Invoquer un agent

gen_ai.operation.name= invoke_agent (ou traceloop.span.kind =workflow)

Outil d'exécution

gen_ai.operation.name= execute_tool (ou traceloop.span.kind =tool)

Inférence

gen_ai.operation.name= chat (ou llm.request.type =chat)
OpenInference

Le service classe les spans en utilisant. openinference.span.kind

Type d'envergure Attribut d'identification

Invoquer un agent

openinference.span.kind= AGENT ou CHAIN

Outil d'exécution

openinference.span.kind = TOOL

Inférence

openinference.span.kind = LLM

Comment sont extraits les champs d'évaluation

Pour chaque plage classée, le service 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. Comme pour les frameworks nommés, l'emplacement du contenu de la conversation dépend du mode de diffusion de la télémétrie. Avec la télémétrie fractionnée, le contenu réside dans l'enregistrement d'événements corrélé. Grâce à la télémétrie unifiée, il reste sur la plage en tant qu'attributs. Pour plus d'informations, consultez la section Configuration et diffusion de la télémétrie.

Le service essaie plusieurs emplacements pour chaque champ et utilise le premier contenant une valeur, afin que vous puissiez émettre l'attribut déjà défini par votre instrumentation. Chaque valeur extraite est stringifiée plutôt que analysée dans une structure spécifique au framework.

OpenTelemetry convention

Pour les frameworks utilisant la OpenTelemetry convention, le service lit chaque champ à partir des emplacements suivants, dans l'ordre :

  • Invite utilisateur (invoquez l'extension de l'agent) : depuis l'enregistrement de l'événementbody.input, puis depuis l'attribut gen_ai.task.input span.

  • Réponse de l'agent (invoquez l'extension de l'agent) : depuis l'enregistrement de l'événementbody.output, puis depuis l'attribut gen_ai.task.output span. Si aucun des deux n'est présent, le service revient au premier message utilisateur et au dernier message d'assistant qu'il a collectés à partir des intervalles d'inférence de la trace.

  • Messages d'inférence (étendue d'inférence) : depuis l'enregistrement de l'événementbody.output.messages, body.input.messages puis depuis les attributs gen_ai.input.messages and gen_ai.output.messages span.

  • Nom de l'outil (execute tool span) : depuis l'attribut gen_ai.tool.name span ; puis depuis l'attribut traceloop.entity.name span.

  • Arguments de l'outil (execute tool span) : depuis l'attribut gen_ai.tool.call.arguments span ; puis depuis l'enregistrement de l'événement body.input ; puis depuis l'attribut traceloop.entity.input span.

  • Résultat de l'outil (execute tool span) : depuis l'attribut gen_ai.tool.call.result span ; puis depuis l'enregistrement de l'événement body.output ; puis depuis l'attribut traceloop.entity.output span.

  • Invite système (étendue d'inférence) : depuis l'attribut gen_ai.system_instructions span.

OpenInference convention

Pour les frameworks utilisant la OpenInference convention, le service lit chaque champ à partir des emplacements suivants, dans l'ordre :

  • Invite utilisateur (invoquez l'extension de l'agent) : depuis l'attribut input.value span ; puis depuis la saisie du corps de l'enregistrement de l'événement.

  • Réponse de l'agent (invoquez agent span) : à partir de l'attribut output.value span ; puis à partir de la sortie du corps de l'enregistrement d'événements.

  • Messages d'inférence (étendue d'inférence) : à partir des attributs de OpenInference message de la plage (par exemple, llm.input_messages.* etllm.output_messages.*) ; puis à partir du input.value output.value corps de l'enregistrement d'événements.

  • Arguments de l'outil (execute tool span) : depuis l'attribut input.value span ; puis depuis l'entrée du corps de l'enregistrement d'événement.

  • Résultat de l'outil (execute tool span) : depuis l'attribut output.value span ; puis depuis la sortie du corps de l'enregistrement d'événements.

  • Invite système (étendue d'inférence) : à partir des attributs de la plage d'inférence ; puis à partir du corps de l'enregistrement d'événements.

  • Outils disponibles  : à partir des attributs de définition d'outil de la plage d'inférence (llm.tools.*) ; puis analysés à partir de la demande sérialisée dans le corps de l'enregistrement d'événement ou. input.value

Exigences de configuration

Pour être évalué avec la prise en charge d'un framework générique, configurez votre instrumentation comme suit :

  • Utilisez un nom d'étendue reconnu. Émettez des étendues sous un nom de portée commençant par opentelemetry.instrumentation.* ouopeninference.instrumentation.*. Le service lit uniquement ces préfixes avec un support de framework générique.

  • Définissez un attribut d'identification pour chaque travée. Définissez gen_ai.operation.name ou traceloop.span.kind pour la OpenTelemetry convention, ou openinference.span.kind pour la OpenInference convention. Le service ignore une plage qui ne comporte aucun attribut d'identification reconnu.

  • Insérez le contenu dans les attributs documentés. Définissez les attributs d'invite, de réponse et d'outil répertoriés dans Comment les champs d'évaluation sont extraits. Si vous intégrez ces valeurs dans votre propre structure, la valeur extraite inclut la structure environnante, car le service stringifie le contenu au lieu d'analyser le modèle de données de votre framework.

Si vous ne pouvez pas définir d'attributs conventionnels, vous pouvez toujours évaluer le tour de l'agent de haut niveau. Définissez les attributs agentcore.invocation.user_prompt et agentcore.invocation.agent_response span, que le AgentCore SDK émet également. Le service lit ces attributs depuis n'importe quelle étendue, et ils ne concernent que l'invite et la réponse de l'agent, et non l'inférence ou les étendues d'outils.