Définir des attributs et des événements sur des spans d’agent

Lorsque vous instrumentez un agent avec le SDK Weave, chaque objet span (Turn, LLM, Tool et SubAgent) expose des méthodes permettant d’ajouter des métadonnées personnalisées. Utilisez ces méthodes pour associer aux spans d’agent des informations contextuelles comme 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 Weave. Ces métadonnées existent sous deux formes :

Attributs : propriétés clé-valeur d’un span dans son ensemble. Utilisez set_attributes() (Python) ou setAttributes() (TypeScript) pour définir des attributs sur un seul span, ou définissez des attributs à l’échelle de la session qui s’appliquent à chaque span émis par une session.
Événements : marqueurs ponctuels survenant pendant la durée de vie d’un span, comme un prompt d’autorisation ou une transition du cycle de vie. Utilisez add_event() (Python) ou addEvent() (TypeScript).

Ces méthodes correspondent à l’API de span OpenTelemetry (OTel) : set_attributes correspond à Span.set_attributes d’OTel, et add_event à Span.add_event. Le SDK Weave émet des spans OTel et stocke tous les attributs afin qu’ils restent interrogeables dans Weave.

Définir des attributs sur un span

Utilisez set_attributes() (Python) ou setAttributes() (TypeScript) pour ajouter des attributs arbitraires à un span donné. Passez 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

import weave

weave.init("[TEAM-NAME]/[PROJECT-NAME]")

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

import * as weave from 'weave';

await weave.init('[TEAM-NAME]/[PROJECT-NAME]');

const session = weave.startSession({ agentName: 'my-agent' });
const turn = weave.startTurn({ agentName: 'my-agent' });

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

turn.end();
session.end();

Les mêmes méthodes sont disponibles sur chaque classe de span. Par exemple, vous pouvez étiqueter un appel d’outil individuel ou un appel LLM :

Python
TypeScript

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

const turn = weave.startTurn({ agentName: 'my-agent' });
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 sont des métadonnées personnalisées arbitraires, mais Weave réserve deux préfixes pour un traitement particulier. Les clés sous weave.* correspondent à des champs Weave intégrés, et les clés sous gen_ai.* correspondent aux champs de convention sémantique 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 utilisateur Agents and Traces. Pour les métadonnées arbitraires sur lesquelles vous souhaitez filtrer et regrouper, utilisez vos propres clés, comme user_id ou tenant, que Weave stocke comme attributs personnalisés filtrables.

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

Ajouter des attributs span par span convient bien aux métadonnées propres à un span, mais certaines métadonnées s’appliquent à l’ensemble d’une session. Pour appliquer les mêmes attributs à chaque span émis par une session, transmettez attributes lorsque vous démarrez la session. Cela permet de propager des métadonnées à l’échelle de la session, comme une identité d’intégration ou un environnement de déploiement.

Python
TypeScript

import weave

weave.init("[TEAM-NAME]/[PROJECT-NAME]")

session = weave.start_session(
    agent_name="my-agent",
    attributes={"weave.integration.name": "my-harness", "env": "production"},
)
# Chaque span de tour de conversation, LLM, outil et sous-agent de cette session porte ces attributs.

import * as weave from 'weave';

await weave.init('[TEAM-NAME]/[PROJECT-NAME]');

const session = weave.startSession({
  agentName: 'my-agent',
  attributes: { 'weave.integration.name': 'my-harness', env: 'production' },
});
// Chaque span de tour de conversation, LLM, outil et sous-agent de cette session porte ces attributs.

Comme pour les attributs par span, utilisez vos propres clés personnalisées pour les attributs de session. Définissez les champs de convention sémantique, comme le nom de l’agent, le nom de la session ou le modèle, via leurs paramètres typés (agent_name, session_name, model) plutôt que via attributes. Évitez les clés sous les préfixes réservés gen_ai.* et weave.*. Weave les extrait dans des champs typés lors de l’ingestion. Une valeur personnalisée sous une clé réservée n’est donc pas prise en charge.

Enregistrer des événements sur un span

Utilisez add_event() (Python) ou addEvent() (TypeScript) pour enregistrer un marqueur à un moment précis du cycle de vie d’un span. Contrairement à un attribut, qui décrit le span dans son ensemble, un événement capture quelque chose qui se produit à un instant donné pendant le span, comme un prompt d’autorisation, une étape de compactage du contexte ou une transition de cycle de vie telle que spawned, streaming ou finished. Chaque événement prend un nom et, de façon facultative, un dictionnaire ou un objet d’attributs.

Python
TypeScript

with weave.start_turn(user_message="Delete the temp files") as turn:
    # Enregistrer un marqueur lorsque l’agent demande une autorisation
    turn.add_event("weave.permission_request", {"tool": "shell", "command": "rm -rf ./tmp"})

    # ... l’agent continue ...

    turn.add_event("finished")

const turn = weave.startTurn({ agentName: 'my-agent' });

// Enregistrer un marqueur lorsque l’agent compacte son contexte
turn.addEvent('context_compacted', { removedMessages: 12 });

turn.end();

Dans l’interface utilisateur, les événements enregistrés peuvent être consultés en sélectionnant l’onglet Spans, puis en choisissant le span associé. Dans le panneau de détail du span, sélectionnez l’onglet de données Raw et développez le tableau events dans l’arborescence JSON, comme illustré dans l’image suivante.

L’onglet Spans avec un span sélectionné contenant des événements. Le panneau de détail à droite affiche l’onglet de données Raw avec le tableau events développé, qui liste les événements enregistrés sur le span.

Quand vous pouvez définir des attributs et des événements

Définissez les attributs et les événements tant que le span est en cours d’enregistrement, c’est-à-dire une fois le span démarré et avant qu’il ne se termine. En Python, cela se fait à l’intérieur du bloc with. En TypeScript, cela se fait après start*() et avant end(). Si vous appelez set_attributes(), add_event() ou leurs équivalents TypeScript sur un span qui n’a pas encore démarré ou qui est déjà terminé, l’appel est sans effet et consigne un avertissement indiquant comment corriger le problème. L’appel ne génère aucun avertissement uniquement lorsque OTel n’est pas installé ou que Weave est désactivé.

Pour joindre des attributs lors de la journalisation, en un seul lot, d’une activité d’agent déjà terminée plutôt que pendant l’exécution en temps réel, renseignez directement les champs déclarés de l’objet span et transmettez l’objet à log_turn ou log_session. Voir Journaliser l’activité d’agent par lots.

Afficher et filtrer les attributs dans l’interface utilisateur

L’ajout d’attributs n’est que la première étape. Leur intérêt réside dans leur utilisation pour analyser l’activité des agents. Après avoir attribué des attributs aux spans d’agent, vous pouvez filtrer et regrouper les conversations d’agent selon ces attributs dans l’onglet Agents de votre projet Weave. Pour en savoir plus, voir Afficher l’activité des agents.

​Définir des attributs sur un span

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

​Enregistrer des événements sur un span

​Quand vous pouvez définir des attributs et des événements

​Afficher et filtrer les attributs dans l’interface utilisateur

Définir des attributs sur un span

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

Enregistrer des événements sur un span

Quand vous pouvez définir des attributs et des événements

Afficher et filtrer les attributs dans l’interface utilisateur