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

# Envoyer des spans OpenTelemetry à Agent Lens

> Envoyez des données de trace OTLP depuis n’importe quel pipeline OpenTelemetry vers le point de terminaison Agent Lens. Aucune intégration du SDK n’est requise.

CoreWeave Agent Lens repose sur [OpenTelemetry (OTel)](https://opentelemetry.io/docs/concepts/) et fournit un point de terminaison OTLP dédié qui ingère les spans dans Agent Lens. Vous pouvez ainsi rediriger rapidement vers Agent Lens les spans de votre application instrumentée avec OTel : il suffit de remplacer la configuration actuelle du point de terminaison de votre exportateur OTel par celle d’Agent Lens. Il n’est pas nécessaire d’installer le SDK CoreWeave Forge pour cela.

Cette page explique comment vous authentifier auprès du point de terminaison et lui envoyer des spans.

<Note>
  Agent Lens s’exécute sur le même backend que Weights & Biases. C’est pourquoi certains noms de configuration conservent le préfixe `wandb` : la variable d’environnement `WANDB_API_KEY`, l’en-tête `wandb-api-key`, ainsi que les attributs de ressource `wandb.entity` et `wandb.project`. Utilisez ces noms tels quels.
</Note>

<h2 id="authentication">
  Authentification
</h2>

Vous pouvez envoyer des spans au point de terminaison suivant :

* **Chemin** : `/agents/otel/v1/traces`
* **Méthode** : `POST`
* **Content-Type** : `application/x-protobuf`
* **URL de base** : `https://trace.wandb.ai` pour le Cloud mutualisé.

Le point de terminaison accepte uniquement les charges utiles OTLP au format protobuf. Utilisez un exportateur HTTP protobuf tel que `opentelemetry-exporter-otlp-proto-http` (Python) ou `@opentelemetry/exporter-trace-otlp-proto` (TypeScript). Le point de terminaison accepte également les encodages de contenu `gzip` et `deflate`.

Pour vous authentifier auprès du point de terminaison, définissez votre [clé API](https://forge.coreweave.com/settings#apikeys) dans la configuration de votre `OTLPSpanExporter` à l’aide de l’une des valeurs suivantes :

* `wandb-api-key` : votre clé API Forge comme valeur.
* `Authorization` : authentification HTTP Basic avec `api` comme nom d’utilisateur et votre clé API Forge comme mot de passe. Cette méthode est utile lorsque votre exportateur ou votre collecteur ne prend en charge que les en-têtes d’autorisation standard.

<h2 id="project-routing">
  Acheminement vers un projet
</h2>

Agent Lens achemine les spans vers un projet à l’aide des attributs de ressource OTel ou d’un en-tête de requête :

* **Attributs de ressource** (recommandé) : dans la ressource de votre `TracerProvider`, définissez `wandb.entity` sur le nom de votre équipe ou de votre utilisateur Forge, et `wandb.project` sur le nom du projet.
* **En-tête `project_id`** : définissez la valeur sur `[YOUR-TEAM]/[YOUR-PROJECT]`.

Si les deux sont présents, les attributs de ressource sont prioritaires. Les spans reçus sans entity ni projet sont supprimés.

<h2 id="shape-spans-for-the-conversations-tab">
  Structurer les spans pour l’onglet Conversations
</h2>

Agent Lens accepte n’importe quel span OTel et en stocke tous les attributs, mais l’onglet Conversations n’affiche que les spans conformes aux [conventions sémantiques OTel GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/). Définissez `gen_ai.operation.name` sur chaque span pour indiquer à Agent Lens ce qu’il représente :

| `gen_ai.operation.name` | Représente | Affiché sous forme de |
| - | - | - |
| `invoke_agent` | Un échange complet entre l’utilisateur et l’agent. | Un tour de conversation. |
| `chat` | Un appel à l’API d’un modèle de langage. | Un appel LLM au sein d’un tour de conversation. |
| `execute_tool` | Une exécution d’outil. | Un appel d’outil. |

Deux autres attributs déterminent le regroupement :

* `gen_ai.conversation.id` : regroupe les tours de conversation au sein d’une conversation. Utilisez un identifiant stable pendant toute la durée de vie de la conversation.
* `gen_ai.agent.name` : regroupe les conversations sous un agent nommé dans l’onglet Conversations.

Les autres attributs des conventions sémantiques GenAI, comme `gen_ai.request.model`, `gen_ai.usage.input_tokens` et `gen_ai.usage.output_tokens`, sont facultatifs, mais enrichissent l’affichage avec le nom des modèles et le nombre de jetons. Pour en savoir plus sur le modèle de données d’agent auquel correspondent ces spans, voir [Tracer vos agents](/fr/products/agent-lens/tracing/instrument#the-agent-data-model).

<h2 id="configure-with-environment-variables-only">
  Configurer uniquement avec des variables d’environnement
</h2>

Si votre application ou votre collecteur lit les variables d’environnement standard de l’exportateur OTel, vous pouvez définir les variables suivantes pour acheminer les spans vers Agent Lens sans modifier votre code :

```bash lines theme={"system"}
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://trace.wandb.ai/agents/otel/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="wandb-api-key=$WANDB_API_KEY"
export OTEL_RESOURCE_ATTRIBUTES="wandb.entity=[YOUR-TEAM],wandb.project=[YOUR-PROJECT]"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
```

* `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` : le point de terminaison Agent Lens vers lequel votre exportateur envoie les spans.
* `OTEL_EXPORTER_OTLP_TRACES_HEADERS` : authentifie chaque requête avec votre clé API Forge, transmise dans l’en-tête `wandb-api-key`.
* `OTEL_RESOURCE_ATTRIBUTES` : envoie les spans vers votre projet. Définissez `wandb.entity` sur le nom de votre équipe Forge ou votre nom d’utilisateur Forge, et `wandb.project` sur le nom du projet.
* `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` : configure l’exportateur pour qu’il envoie du protobuf OTLP via HTTP. La valeur doit être `http/protobuf`, car le point de terminaison n’accepte que les charges utiles protobuf.

<h2 id="example-emit-agent-spans-without-the-agent-lens-sdk">
  Exemple : émettre des spans d’agent sans le SDK Agent Lens
</h2>

L’exemple suivant instrumente un tour de conversation minimal d’un agent à l’aide des seuls packages OTel. Il émet un span `invoke_agent` pour le tour de conversation, un span `chat` pour l’appel LLM et un span `execute_tool` pour un appel d’outil, puis les exporte vers le point de terminaison des agents d’Agent Lens.

Commencez par installer les dépendances requises :

<CodeGroup>
  ```bash Python theme={"system"}
  pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
  ```

  ```bash TypeScript theme={"system"}
  npm install @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base @opentelemetry/resources @opentelemetry/exporter-trace-otlp-proto
  ```
</CodeGroup>

Dans le code suivant, remplacez ensuite `YOUR-TEAM`, `YOUR-PROJECT` et `YOUR_API_KEY` par vos propres valeurs, puis exécutez-le :

<CodeGroup>
  ```python Python lines highlight="8,9,14" theme={"system"}
  import os
  from opentelemetry import trace
  from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
  from opentelemetry.sdk import trace as trace_sdk
  from opentelemetry.sdk.resources import Resource
  from opentelemetry.sdk.trace.export import BatchSpanProcessor

  ENTITY = "[YOUR-TEAM]"
  PROJECT = "[YOUR-PROJECT]"

  AGENTS_LENS_OTLP_ENDPOINT = "https://trace.wandb.ai/agents/otel/v1/traces"

  # Créez une clé API sur https://forge.coreweave.com/settings#apikeys
  WANDB_API_KEY = [YOUR-API-KEY]

  exporter = OTLPSpanExporter(
      endpoint=WEAVE_AGENTS_OTLP_ENDPOINT,
      headers={"wandb-api-key": WANDB_API_KEY},
  )

  tracer_provider = trace_sdk.TracerProvider(resource=Resource({
      "wandb.entity": ENTITY,
      "wandb.project": PROJECT,
  }))
  tracer_provider.add_span_processor(BatchSpanProcessor(exporter))
  trace.set_tracer_provider(tracer_provider)

  tracer = trace.get_tracer("my-agent")

  CONVERSATION_ID = "conversation-001"

  # Un tour de conversation : un utilisateur pose une question, l’agent appelle un outil, puis répond.
  with tracer.start_as_current_span("invoke_agent my-agent") as turn:
      turn.set_attribute("gen_ai.operation.name", "invoke_agent")
      turn.set_attribute("gen_ai.agent.name", "my-agent")
      turn.set_attribute("gen_ai.conversation.id", CONVERSATION_ID)

      with tracer.start_as_current_span("chat gpt-4o") as llm:
          llm.set_attribute("gen_ai.operation.name", "chat")
          llm.set_attribute("gen_ai.conversation.id", CONVERSATION_ID)
          llm.set_attribute("gen_ai.request.model", "gpt-4o")
          # Remplacez par un véritable appel LLM et enregistrez son utilisation des jetons.
          llm.set_attribute("gen_ai.usage.input_tokens", 100)
          llm.set_attribute("gen_ai.usage.output_tokens", 20)

          with tracer.start_as_current_span("execute_tool get_weather") as tool:
              tool.set_attribute("gen_ai.operation.name", "execute_tool")
              tool.set_attribute("gen_ai.conversation.id", CONVERSATION_ID)
              tool.set_attribute("gen_ai.tool.name", "get_weather")
              # Remplacez par une véritable exécution d’outil.

  tracer_provider.shutdown()  # Vide tous les spans en attente avant la fermeture.
  ```

  ```typescript TypeScript lines highlight="7,8,13" theme={"system"}
  import { trace } from "@opentelemetry/api";
  import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
  import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
  import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
  import { Resource } from "@opentelemetry/resources";

  const ENTITY = "[YOUR-TEAM]";
  const PROJECT = "[YOUR-PROJECT]";

  const WEAVE_AGENTS_OTLP_ENDPOINT = "https://trace.wandb.ai/agents/otel/v1/traces";

  // Créez une clé API sur https://forge.coreweave.com/settings#apikeys
  const WANDB_API_KEY = [YOUR-API-KEY]!;

  const exporter = new OTLPTraceExporter({
    url: WEAVE_AGENTS_OTLP_ENDPOINT,
    headers: { "wandb-api-key": WANDB_API_KEY },
  });

  const provider = new NodeTracerProvider({
    resource: new Resource({
      "wandb.entity": ENTITY,
      "wandb.project": PROJECT,
    }),
    spanProcessors: [new BatchSpanProcessor(exporter)],
  });

  provider.register();

  const tracer = trace.getTracer("my-agent");

  const CONVERSATION_ID = "conversation-001";

  // Un tour de conversation : un utilisateur pose une question, l’agent appelle un outil, puis répond.
  tracer.startActiveSpan("invoke_agent my-agent", (turn) => {
    turn.setAttribute("gen_ai.operation.name", "invoke_agent");
    turn.setAttribute("gen_ai.agent.name", "my-agent");
    turn.setAttribute("gen_ai.conversation.id", CONVERSATION_ID);

    tracer.startActiveSpan("chat gpt-4o", (llm) => {
      llm.setAttribute("gen_ai.operation.name", "chat");
      llm.setAttribute("gen_ai.conversation.id", CONVERSATION_ID);
      llm.setAttribute("gen_ai.request.model", "gpt-4o");
      // Remplacez par un véritable appel LLM et enregistrez son utilisation des jetons.
      llm.setAttribute("gen_ai.usage.input_tokens", 100);
      llm.setAttribute("gen_ai.usage.output_tokens", 20);

      tracer.startActiveSpan("execute_tool get_weather", (tool) => {
        tool.setAttribute("gen_ai.operation.name", "execute_tool");
        tool.setAttribute("gen_ai.conversation.id", CONVERSATION_ID);
        tool.setAttribute("gen_ai.tool.name", "get_weather");
        // Remplacez par une véritable exécution d’outil.
        tool.end();
      });

      llm.end();
    });

    turn.end();
  });

  await provider.shutdown(); // Vide tous les spans en attente avant la fermeture.
  ```
</CodeGroup>

Pour ajouter d’autres tours de conversation à la même conversation, émettez d’autres spans `invoke_agent` avec le même `gen_ai.conversation.id`. Chaque tour de conversation constitue le span racine de sa propre trace : les tours de conversation n’ont donc pas besoin de partager un span parent.

Une fois que votre application a exporté les spans, ouvrez la vue **Conversations** de votre projet Agent Lens.