> ## 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 sur les spans d’agent

> Joignez des attributs personnalisés aux spans d’agent pour filtrer et analyser l’activité dans Agent Lens.

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)](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/). 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](/fr/products/agent-lens/tracing/instrument#before-you-begin).

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

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

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

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

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.

<h2 id="record-what-happens-during-a-span">
  Enregistrer ce qui se passe pendant un span
</h2>

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 :

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

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

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

<Note>
  Les méthodes `add_event()` (Python) et `addEvent()` (TypeScript) du SDK sont obsolètes, car OpenTelemetry [abandonne progressivement l’API Span Event](https://opentelemetry.io/blog/2026/deprecating-span-events/). Enregistrez plutôt ces données à l’aide d’attributs.
</Note>

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

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.

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

  <Tab title="TypeScript">
    ```typescript lines theme={"system"}
    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.
    });
    ```
  </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 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.
</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 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é.

<Tip>
  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](/fr/products/agent-lens/tracing/batch-logging).
</Tip>

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

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](/fr/products/agent-lens/conversations/view-activity).