Envoyer des spans OpenTelemetry vers la vue Agents

L’observabilité des agents de W&B Weave repose sur OpenTelemetry (OTel) et fournit un point de terminaison OTLP dédié qui ingère les spans dans la vue Agents. Vous pouvez ainsi rediriger rapidement vers Weave 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 du point de terminaison de Weave. Il n’est pas nécessaire d’installer le SDK Weave pour cela. Cette page explique comment vous authentifier auprès du point de terminaison et lui envoyer des spans.

Authentification

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, indiquez votre clé API W&B dans la configuration de votre OTLPSpanExporter à l’aide de l’une des valeurs suivantes :

wandb-api-key : votre clé API W&B comme valeur.
Authorization : authentification HTTP Basic avec api comme nom d’utilisateur et votre clé API W&B 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.

Acheminement vers un projet

Weave 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é) : sur la ressource de votre TracerProvider, définissez wandb.entity sur le nom de votre équipe ou de votre utilisateur CoreWeave 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.

Structurer les spans pour la vue Agents

Weave accepte n’importe quel span OTel et en stocke tous les attributs, mais la vue Agents n’affiche que les spans conformes aux conventions sémantiques OTel GenAI. Définissez gen_ai.operation.name sur chaque span pour indiquer à Weave ce qu’il représente :

`gen_ai.operation.name`	Représente	Rendu sous forme de
`invoke_agent`	Un échange complet entre l’utilisateur et l’agent.	Un tour de conversation.
`chat`	Un appel à une API de 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 contrôlent le regroupement :

gen_ai.conversation.id : regroupe les tours de conversation en une conversation. Utilisez un ID 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 Agents.

Les autres attributs des conventions sémantiques GenAI, tels que gen_ai.request.model, gen_ai.usage.input_tokens et gen_ai.usage.output_tokens, sont facultatifs, mais enrichissent le rendu avec les noms de modèles et le nombre de jetons. Pour le modèle de données d’agent auquel ces spans correspondent, voir Tracer vos agents.

Configurer uniquement avec des variables d’environnement

Si votre application ou votre collecteur lit les variables d’environnement standard de l’exportateur OTel, vous pouvez définir les variables suivantes et acheminer les spans vers Weave sans modifier une seule ligne de code :

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]"

Exemple : émettre des spans d’agent sans le SDK Weave

L’exemple suivant instrumente un tour de conversation minimal d’un agent à l’aide des seuls paquets 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 Weave. Commencez par installer les dépendances requises :

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

npm install @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base @opentelemetry/resources @opentelemetry/exporter-trace-otlp-proto

Définissez ensuite les valeurs WANDB_API_KEY, ENTITY et PROJECT dans le code suivant, puis exécutez-le :

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]"

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

# Créez une clé API sur https://forge.coreweave.com/settings
WANDB_API_KEY = [YOUR-WANDB-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 de quitter.

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
const WANDB_API_KEY = [YOUR-WANDB-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 de l’outil.
      tool.end();
    });

    llm.end();
  });

  turn.end();
});

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

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 l’onglet Agents de votre projet Weave.

​Authentification

​Acheminement vers un projet

​Structurer les spans pour la vue Agents

​Configurer uniquement avec des variables d’environnement

​Exemple : émettre des spans d’agent sans le SDK Weave

Authentification

Acheminement vers un projet

Structurer les spans pour la vue Agents

Configurer uniquement avec des variables d’environnement

Exemple : émettre des spans d’agent sans le SDK Weave