Définir des attributs et des événements sur les 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 de joindre des métadonnées personnalisées. Utilisez ces méthodes pour apposer sur les spans de l’agent des informations contextuelles, telles que des ID utilisateur, des tenants, des noms d’expériences ou des libellés d’environnement, puis filtrez et regroupez l’activité de l’agent selon ces métadonnées dans l’interface de Weights & Biases. Ces métadonnées se présentent sous deux formes :

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

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

Définir des attributs sur un span

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

Python
TypeScript

import weave

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

with weave.start_conversation(agent_name="my-agent"):
    with weave.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 * as weave from 'weave';

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

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

// 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 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 correspondent à des métadonnées personnalisées arbitraires, mais Weave réserve deux préfixes à une gestion particulière. Les clés commençant par weave.* correspondent aux champs Weave intégrés, et celles commençant par gen_ai.* correspondent 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 Agents et Traces. Pour les métadonnées arbitraires qui vous servent à filtrer et à regrouper, utilisez vos propres clés, comme user_id ou tenant, que Weave stocke sous forme d’attributs personnalisés filtrables.

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

Ajouter des 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, transmettez attributes au démarrage de la conversation. Cette approche permet de propager des métadonnées valables pour toute la conversation, comme l’identité d’une intégration ou un environnement de déploiement.

Python
TypeScript

import weave

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

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

import * as weave from 'weave';

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

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

Comme pour les attributs par span, utilisez vos propres clés personnalisées pour les attributs de conversation. Définissez les champs des conventions sémantiques, comme 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 via attributes. Évitez les clés relevant des préfixes réservés gen_ai.* et weave.* : Weave les extrait dans des champs typés lors de l’ingestion, si bien qu’une valeur personnalisée associée à une clé réservée n’est 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 se situe 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 (no-op) et journalise un avertissement indiquant la correction à apporter. L’appel reste silencieux (aucun avertissement) uniquement lorsque OTel n’est pas installé ou que Weave est désactivé.

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

Afficher et filtrer les attributs dans l’interface utilisateur

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

​Définir des attributs sur 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

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

Quand définir des attributs

Afficher et filtrer les attributs dans l’interface utilisateur