Skip to main content
Ce document complète les conventions sémantiques OpenTelemetry GenAI officielles par des règles et des recommandations propres à Agent Lens. Là où la spécification en amont indique MAY ou SHOULD, ce profil impose généralement MUST (conformément à la RFC 2119). Sauf mention contraire dans ce document, les conventions sémantiques officielles s’appliquent.

API

Envoyez des données OTLP au format protobuf à POST /agents/otel/v1/traces. Pour l’authentification et l’acheminement par projet, consultez Envoyer des spans OpenTelemetry à Agent Lens.

Liste de contrôle

Pour qu’Agent Lens ingère correctement vos spans OTel, assurez-vous qu’ils respectent les règles suivantes :

Mappage du modèle de données d’Agent Lens

Les attributs suivants sont stockés et exposés par Agent Lens. Cette liste n’est pas exhaustive, et la logique de repli réelle peut être plus complexe que ce qui est décrit ici. La prise en charge des attributs hérités et obsolètes (y compris OpenInference) est assurée au mieux.

Noms d’opération GenAI spéciaux

Chaque span DOIT définir gen_ai.operation.name. Sa valeur DEVRAIT être un nom standard défini dans les conventions sémantiques officielles d’OTel. Les noms d’opération suivants ont un rôle particulier dans Agent Lens. Ils constituent l’ensemble minimal d’opérations nécessaires pour décrire la plupart des flux de travail agentiques.

Attributs personnalisés

Agent Lens accepte les noms d’attributs propres à un fournisseur ou définis par l’utilisateur, et les rend disponibles sous forme d’attributs personnalisés. Par exemple : my_company.user.is_admin=true, my_company.user.sentiment="positive" et my_company.eval.score=0.5.
  • Les valeurs des attributs personnalisés DOIVENT être des entiers, des nombres à virgule flottante, des chaînes de caractères ou des valeurs booléennes.
  • Les noms des attributs personnalisés DOIVENT présenter une faible cardinalité et NE DOIVENT PAS être générés dynamiquement.
  • Les noms des attributs personnalisés DEVRAIENT utiliser un namespace cohérent, par exemple my_company.*.

Spans et attributs OTel

Cette section reprend la structure des spans d’agent et des spans d’inférence de la convention sémantique officielle d’OTel, mais ne mentionne que les points sur lesquels ce profil s’en écarte. Pour tout le reste, y compris les noms de spans, les types de spans et les spans qui ne figurent pas ici, les recommandations officielles s’appliquent.

Span d’appel de flux de travail (Invoke workflow)

Dans Agent Lens, un span racine DOIT être soit invoke_workflow, soit invoke_agent. Utilisez invoke_workflow pour gérer les cas complexes dans lesquels un utilisateur peut appeler plusieurs agents à la fois. Sinon, privilégiez invoke_agent.

Span d’appel d’agent

Dans Agent Lens, un span racine DOIT être soit invoke_workflow, soit invoke_agent. Utilisez invoke_workflow pour gérer les cas complexes dans lesquels un utilisateur peut appeler plusieurs agents à la fois. Sinon, privilégiez invoke_agent.

Span d’inférence

Agent Lens utilise les spans d’inférence pour reconstituer l’historique des messages d’une conversation et estimer les coûts. Les spans d’inférence contiennent également les requêtes et les réponses des appels d’outil. Si un modèle envoie sa réponse finale au moyen d’un appel d’outil, cet outil DOIT porter l’un des noms suivants : final_answer, final_result, set_model_response ou send_message.

Utilisation des jetons et coût

Agent Lens estime le coût de chaque span d’inférence à partir de son utilisation des jetons et de gen_ai.response.model :
  • gen_ai.usage.input_tokens DOIT correspondre au total des entrées, jetons mis en cache compris. Les lectures et écritures en cache DEVRAIENT également être indiquées dans gen_ai.usage.cache_read.input_tokens et gen_ai.usage.cache_write.input_tokens. Agent Lens les soustrait du total et les facture à leur tarif propre. Si gen_ai.usage.input_tokens ne comptabilise que les jetons non mis en cache, les entrées sont sous-évaluées et le coût peut apparaître comme négatif.
  • gen_ai.usage.output_tokens DOIT correspondre au total des sorties, jetons de raisonnement compris.
  • Certains fournisseurs indiquent ces nombres séparément : vous devez donc les réintégrer dans les totaux. Anthropic comptabilise les jetons mis en cache à part des jetons d’entrée, et Gemini comptabilise les jetons de réflexion à part des jetons de sortie. OpenAI inclut déjà les jetons mis en cache dans son nombre de jetons d’entrée, et les jetons de raisonnement dans son nombre de jetons de sortie.
  • gen_ai.response.model DOIT correspondre exactement à l’ID du modèle renvoyé par le fournisseur. Un alias tel que opus ou sonnet n’a pas de tarif associé, et l’appel affiche Cost -.
  • Les attributs d’utilisation DEVRAIENT être définis uniquement sur les spans d’inférence. Ne recopiez pas les totaux d’un tour de conversation dans son span invoke_agent.

Span d’exécution d’outil

Un appel d’outil a lieu lorsqu’un modèle demande à votre application d’exécuter une fonction. Un même appel d’outil apparaît dans trois spans, et votre instrumentation doit enregistrer le même gen_ai.tool.call.id dans chacun d’eux pour qu’Agent Lens puisse les relier :
  1. Le span d’inférence dans lequel le modèle demande l’appel, sous forme de partie tool_call dans gen_ai.output.messages.
  2. Le span execute_tool correspondant à l’exécution de la fonction.
  3. Le span d’inférence suivant, qui renvoie le résultat au modèle sous forme de partie tool_call_response dans gen_ai.input.messages.
Les parties de requête, d’exécution et de réponse DOIVENT toutes être reliées par le même gen_ai.tool.call.id, et cet ID DOIT être unique au sein d’une trace.

Exemples

Un agent utilise un outil pour répondre à une question

L’agent appelle un sous-agent en tant qu’outil

Un flux de travail exécute deux agents en parallèle

Un agent génère une image

Un appel d’outil qui échoue

Dernière modification le 18 novembre 2026