> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Joignez des attributs personnalisés et enregistrez des événements sur les spans d’agent (Turn, LLM, Tool et SubAgent) pour filtrer et analyser l’activité des agents dans Weave.

export const AgentLensBanner = ({href}) => <Tip>
    <strong>This workflow is also available in CoreWeave Agent Lens.</strong> Agent Lens is the Forge experience built for tracing, monitoring, and analyzing AI agents, with automated insights into agent failures and user intents. It uses the same trace data as Weights & Biases Weave, so the traces you already send appear there with nothing to migrate.{' '}
    <a href={href || '/products/agent-lens'}>{href ? 'See how to do this in Agent Lens' : 'Learn about Agent Lens'}</a>.
  </Tip>;

<AgentLensBanner href="/fr/products/agent-lens/tracing/attributes-and-events" />

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)](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/) : `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.

<h2 id="set-attributes-on-a-span">
  Définir des attributs sur un span
</h2>

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.

<Tabs>
  <Tab title="Python">
    ```python lines theme={"system"}
    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"})
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript lines twoslash theme={"system"}
    // @noErrors
    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();
    ```
  </Tab>
</Tabs>

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 :

<Tabs>
  <Tab title="Python">
    ```python lines theme={"system"}
    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"})
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript lines twoslash theme={"system"}
    // @noErrors
    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();
    ```
  </Tab>
</Tabs>

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.

<h2 id="set-attributes-on-every-span-in-a-conversation">
  Définir des attributs sur chaque span d’une conversation
</h2>

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.

<Tabs>
  <Tab title="Python">
    ```python lines theme={"system"}
    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.
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript lines twoslash theme={"system"}
    // @noErrors
    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.
    ```
  </Tab>
</Tabs>

<Note>
  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.
</Note>

<h2 id="when-you-can-set-attributes">
  Quand définir des attributs
</h2>

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é.

<Tip>
  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](/fr/products/wandb/weave/guides/tracking/trace-agents-batch).
</Tip>

<h2 id="view-and-filter-attributes-in-the-ui">
  Afficher et filtrer les attributs dans l’interface utilisateur
</h2>

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](/fr/products/wandb/weave/guides/tracking/view-agent-activity).


## Related topics

- [Définir et journaliser des attributs](/fr/products/wandb/weave/guides/tools/attributes.md)