Définir des attributs sur les spans d’agent

Lorsque vous instrumentez un agent avec le SDK CoreWeave Forge, chaque objet span (Turn, LLM, Tool et SubAgent) vous permet de joindre des métadonnées personnalisées sous forme d’attributs. Les attributs sont des propriétés clé-valeur d’un span. Utilisez-les pour associer aux spans d’agent des informations contextuelles telles que des ID d’utilisateur, des locataires, des noms d’expérience ou des libellés d’environnement, puis filtrez et regroupez l’activité des agents selon ces métadonnées dans l’interface de CoreWeave Agent Lens. Vous pouvez définir des attributs sur un seul span avec set_attributes() (Python) ou setAttributes() (TypeScript), ou bien définir des attributs au niveau d’une conversation, qui s’appliquent à chaque span émis par celle-ci. set_attributes reprend la méthode Span.set_attributes de l’API de span OpenTelemetry (OTel). Le SDK Agent Lens émet des spans OTel et stocke tous les attributs, qui peuvent ainsi être interrogés dans Agent Lens. Les exemples de cette page supposent que vous avez installé et initialisé le SDK comme décrit dans Tracer vos agents.

Définir des attributs sur un span

Utilisez set_attributes() (Python) ou setAttributes() (TypeScript) pour associer des attributs arbitraires à un span donné. Transmettez un dictionnaire ou un objet, que vous ayez une seule clé ou plusieurs. La méthode renvoie le span, ce qui vous permet de chaîner les appels.

Python
TypeScript

from coreweave.forge.agentlens import tracing

tracing.init("[YOUR-TEAM]/[YOUR-PROJECT]")

with tracing.start_conversation(agent_name="my-agent"):
    with tracing.start_turn(user_message="What is the weather in Tokyo?") as turn:
        # Associer des attributs à ce span de tour de conversation
        turn.set_attributes({"user_id": "12345", "tenant": "acme", "env": "production"})

import { tracing } from '@coreweave/forge-sdk/agentlens';

await tracing.init('[YOUR-TEAM]/[YOUR-PROJECT]');

await tracing.runIsolated(async () => {
  const conversation = tracing.startConversation({ agentName: 'my-agent' });
  const turn = tracing.startTurn({ userMessage: 'What is the weather in Tokyo?' });

  // Associer des attributs à ce span de tour de conversation
  turn.setAttributes({ user_id: '12345', tenant: 'acme', env: 'production' });

  turn.end();
  conversation.end();
});

Les mêmes méthodes sont disponibles sur toutes les classes de span. Vous pouvez par exemple étiqueter un appel d’outil ou un appel LLM précis :

Python
TypeScript

with tracing.start_turn(user_message="What is the weather in Tokyo?") as turn:
    with turn.start_tool(name="get_weather") as tool:
        tool.set_attributes({"weave.display_name": "Weather lookup"})

const turn = tracing.startTurn({ userMessage: 'What is the weather in Tokyo?' });
const tool = turn.startTool({ name: 'get_weather' });

tool.setAttributes({ 'weave.display_name': 'Weather lookup' });

tool.end();
turn.end();

La plupart des clés d’attribut correspondent à des métadonnées personnalisées arbitraires, mais Agent Lens réserve deux préfixes à un traitement particulier. Les clés weave.* correspondent aux champs intégrés d’Agent Lens, et les clés gen_ai.* aux champs des conventions sémantiques GenAI d’OpenTelemetry. Dans l’exemple précédent, weave.display_name est une clé réservée qui définit le nom d’affichage du span dans l’interface d’Agent Lens. Pour les métadonnées arbitraires qui vous serviront à filtrer et à regrouper, utilisez vos propres clés, comme user_id ou tenant, qu’Agent Lens stocke sous forme d’attributs personnalisés filtrables.

Enregistrer ce qui se passe pendant un span

Les attributs permettent également d’enregistrer ce qui se produit pendant l’exécution d’un span, comme une demande d’autorisation ou son issue. Définissez les attributs au moment où cela se produit, tant que le span est encore en cours d’enregistrement :

Python
TypeScript

with tracing.start_turn(user_message="Delete the old backups.") as turn:
    turn.set_attributes({"permission.scope": "filesystem.delete"})
    # ... demander à l'utilisateur et attendre sa réponse ...
    turn.set_attributes({"permission.granted": True})

const turn = tracing.startTurn({ userMessage: 'Delete the old backups.' });
turn.setAttributes({ 'permission.scope': 'filesystem.delete' });
// ... demander à l'utilisateur et attendre sa réponse ...
turn.setAttributes({ 'permission.granted': true });
turn.end();

Un attribut enregistre une valeur, et non le moment où elle a été définie. Si vous avez besoin de savoir quand quelque chose s’est produit au sein d’un span, enregistrez l’heure dans un attribut dédié, par exemple permission.granted_at.

Les méthodes add_event() (Python) et addEvent() (TypeScript) du SDK sont obsolètes, car OpenTelemetry abandonne progressivement l’API Span Event. Enregistrez plutôt ces données à l’aide d’attributs.

Définir des attributs sur chaque span d’une conversation

Définir les attributs span par span convient bien aux métadonnées propres à un span, mais certaines métadonnées concernent une conversation entière. Pour appliquer les mêmes attributs à tous les spans émis par une conversation, passez attributes au démarrage de la conversation. Vous pouvez ainsi propager des métadonnées valables pour toute la conversation, comme un nom de déploiement ou un environnement.

Python
TypeScript

from coreweave.forge.agentlens import tracing

tracing.init("[YOUR-TEAM]/[YOUR-PROJECT]")

conversation = tracing.start_conversation(
    agent_name="my-agent",
    attributes={"deployment": "canary", "env": "production"},
)
# Tous les spans de tour de conversation, de LLM, d’outil et de sous-agent de cette conversation portent ces attributs.

import { tracing } from '@coreweave/forge-sdk/agentlens';

await tracing.init('[YOUR-TEAM]/[YOUR-PROJECT]');

await tracing.runIsolated(async () => {
  const conversation = tracing.startConversation({
    agentName: 'my-agent',
    attributes: { deployment: 'canary', env: 'production' },
  });
  // Tous les spans de tour de conversation, de LLM, d’outil et de sous-agent de cette conversation portent ces attributs.
});

Comme pour les attributs par span, utilisez vos propres clés personnalisées pour les attributs de conversation. Définissez les champs relevant des conventions sémantiques, tels que le nom de l’agent, le nom de la conversation ou le modèle, au moyen de leurs paramètres typés (agent_name, conversation_name, model) plutôt que de attributes. Évitez les clés relevant des préfixes réservés gen_ai.* et weave.*. Agent Lens les extrait dans des champs typés lors de l’ingestion ; une valeur personnalisée associée à une clé réservée n’est donc pas prise en charge.

Quand définir des attributs

Définissez les attributs pendant l’enregistrement du span, c’est-à-dire après son démarrage et avant sa fin. En Python, cela correspond à l’intérieur du bloc with. En TypeScript, cela correspond à l’intervalle entre start*() et end(). Si vous appelez set_attributes(), ou son équivalent TypeScript, sur un span qui n’a pas encore démarré ou qui est déjà terminé, l’appel n’a aucun effet et journalise un avertissement qui indique comment corriger le problème. L’appel est silencieux (aucun avertissement) uniquement lorsque le traçage n’a pas été initialisé.

Pour joindre des attributs lorsque vous journalisez en un seul lot une activité d’agent terminée, plutôt que pendant l’exécution, renseignez directement les champs déclarés de l’objet span et transmettez celui-ci à log_turn ou à log_conversation. Voir Journaliser l’activité des agents par lots.

Afficher et filtrer les attributs dans l’interface utilisateur

Ajouter des attributs n’est que la première étape : tout leur intérêt réside dans leur exploitation pour analyser l’activité des agents. Une fois les attributs ajoutés aux spans d’agent, vous pouvez filtrer et regrouper les conversations des agents selon ces attributs dans l’onglet Conversations de votre projet Agent Lens. Pour plus de détails, voir Afficher l’activité des agents.

​Définir des attributs sur un span

​Enregistrer ce qui se passe pendant un span

​Définir des attributs sur chaque span d’une conversation

​Quand définir des attributs

​Afficher et filtrer les attributs dans l’interface utilisateur

Définir des attributs sur un span

Enregistrer ce qui se passe pendant un span

Définir des attributs sur chaque span d’une conversation

Quand définir des attributs

Afficher et filtrer les attributs dans l’interface utilisateur