Tracer vos agents - CoreWeave Docs

Découvrez comment instrumenter une application agentique sur plusieurs tours de conversation avec le SDK W&B Weave afin de visualiser, déboguer et évaluer le comportement de votre agent. Ce guide s’adresse aux développeurs qui créent ou intègrent des agents et souhaitent bénéficier d’une visibilité structurée sur les conversations, les tours de conversation, les appels LLM et les exécutions d’outils. Le SDK Weave pour les agents modélise le cycle de vie complet d’une conversation d’agent sur plusieurs tours de conversation : l’agent, qui possède de nombreuses conversations ; la conversation, qui regroupe les tours de conversation ; chaque échange entre l’utilisateur et l’agent (tour de conversation) ; les appels LLM au sein d’un tour de conversation ; et les exécutions d’outils déclenchées par un LLM. Les traces apparaissent dans l’onglet Agents de votre projet Weave. Chaque conversation affiche une chronologie sur plusieurs tours de conversation, avec les appels d’outils imbriqués, l’utilisation des jetons et le feedback. Weave repose sur OpenTelemetry (OTel), la norme ouverte de traçage distribué. Chaque tour de conversation, appel LLM et appel d’outil émet un span OTel (un enregistrement structuré d’une opération). Chaque span est tagué avec des attributs issus des conventions sémantiques GenAI, tels que gen_ai.agent.name et gen_ai.conversation.id. Si vous tracez des fonctions individuelles en tant qu’ops avec le décorateur @weave.op, consultez plutôt Tracer des applications LLM.

Avant de commencer

Pour commencer, installez le package weave et initialisez votre projet. Cette étape enregistre votre équipe et votre projet auprès de Weave afin que le SDK achemine les spans vers le bon emplacement dans l’interface utilisateur.

Python
TypeScript

pip install weave

Remplacez [YOUR-TEAM] par le nom de votre équipe CoreWeave Forge et [YOUR-PROJECT] par le nom de votre projet Weights & Biases.

import weave

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

Appelez weave.init() avant tout appel à start_conversation(), start_turn(), start_llm(), start_tool() ou start_subagent(). Lorsque le traçage est désactivé ou que l’appel d’initialisation est absent, toutes les fonctions de traçage d’agent se comportent silencieusement comme des no-ops. Vous pouvez donc conserver l’instrumentation dans votre code de production et la piloter via la configuration.

npm install weave

Remplacez [YOUR-TEAM] par le nom de votre équipe CoreWeave Forge et [YOUR-PROJECT] par le nom de votre projet Weights & Biases.

import * as weave from 'weave';

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

Appelez weave.init() avant tout appel à startConversation(), startTurn(), startLLM(), startTool() ou startSubagent(). Lorsque le traçage est désactivé ou que l’appel d’initialisation est absent, toutes les fonctions de traçage d’agent se comportent silencieusement comme des no-ops. Vous pouvez donc conserver l’instrumentation dans votre code de production et la piloter via la configuration.

Le modèle de données des agents

Weave modélise le comportement des agents sous la forme d’une hiérarchie de relations un-à-plusieurs. Chaque agent peut avoir plusieurs conversations, chaque conversation peut comporter plusieurs tours de conversation, chaque tour de conversation peut contenir plusieurs appels LLM, et chaque appel LLM peut déclencher plusieurs appels d’outil.

Concept	Classe du SDK Weave	Type de span OTel	Description	Page de référence
Agent	(aucune classe)	(aucun span, regroupement par l’attribut `agent_name`)	Application agentique de l’onglet Agents qui contient une ou plusieurs conversations.
Conversation	`Conversation`	(aucun span, les tours de conversation sont regroupés par l’attribut `conversation_id`)	Conversation ou run qui contient un ou plusieurs tours de conversation.	Python TypeScript
Tour de conversation	`Turn`	`invoke_agent`	Un message de l’utilisateur et la réponse complète de l’agent.	Python TypeScript
Appel LLM	`LLM`	`chat`	Un appel à l’API d’un modèle de langage.	Python TypeScript
Appel d’outil	`Tool`	`execute_tool`	Un appel d’outil déclenché par une réponse du LLM.	Python TypeScript
Appel de sous-agent	`SubAgent`	`invoke_agent`	Appel d’agent imbriqué, généralement lorsqu’un agent délègue une tâche à un autre.	Python TypeScript

Le diagramme suivant montre comment un agent englobe plusieurs conversations, une conversation plusieurs tours de conversation, et ainsi de suite. Une conversation regroupe les tours de conversation au moyen d’un attribut conversation_id commun plutôt que d’un span parent ; chaque tour de conversation démarre donc sa propre trace OTel. Cette conception prend en charge le traçage distribué et l’exécution parallèle. Le client envoie les spans directement au collecteur OTel, sans aucune agrégation côté serveur.

Pour intégrer Weave à des SDK ou à des harness tels que le Claude Agent SDK ou Codex, consultez Choisir une intégration d’agent. Weave patche automatiquement plusieurs SDK de création d’agents et harness d’agents, ce qui permet une intégration rapide.

API de traçage d’agents

Les sections suivantes décrivent chaque fonction de traçage de premier niveau ainsi que les arguments qu’elle accepte. Utilisez ces fonctions pour instrumenter les couches conversation, tour de conversation, appel LLM et appel d’outil du modèle de données présenté dans la section précédente. Weave expose les fonctions de premier niveau suivantes. Chaque fonction renvoie un objet qui peut servir de gestionnaire de contexte (avec with en Python ou try/finally en TypeScript), ou que vous pouvez fermer manuellement en appelant .end().

Démarrer une conversation

start_conversation() (Python) ou startConversation() (TypeScript) appose un attribut conversation_id sur chaque span enfant afin que les tours de conversation soient regroupés dans l’onglet Agents. Si vous transmettez un conversation_id / conversationId, celui-ci doit rester stable pendant toute la durée de vie de la conversation. Réutilisez le même ID pour ajouter de nouveaux tours de conversation à une conversation existante. Si vous ne le transmettez pas, le SDK génère automatiquement un UUID. La conversation active est stockée dans le contexte (une ContextVar Python ou un AsyncLocalStorage Node.js). Ainsi, tout code s’exécutant dans le même contexte asynchrone peut la récupérer avec weave.get_current_conversation() / weave.getCurrentConversation() sans avoir à transmettre explicitement l’objet conversation.

Python
TypeScript

conversation = weave.start_conversation(
    agent_name="my-agent",    # Facultatif : identifie l’agent dans l’interface utilisateur. Si vous l’omettez, la conversation n’est pas regroupée sous un agent nommé.
    conversation_id="",       # Facultatif : ID stable pour regrouper les tours de conversation ; généré automatiquement s’il est vide.
    model="",                 # Facultatif : modèle par défaut pour les tours de cette conversation.
    conversation_name="",     # Facultatif : libellé lisible affiché dans l’interface utilisateur.
    include_content=True,     # Facultatif : définissez False pour omettre le corps des messages dans les spans.
    continue_parent_trace=False,  # Facultatif : se rattacher à une trace OTel existante au lieu d’en démarrer une nouvelle.
)

const conversation = weave.startConversation({
  agentName: 'my-agent',  // Facultatif : identifie l’agent dans l’interface utilisateur. Si vous l’omettez, la conversation n’est pas regroupée sous un agent nommé.
  conversationId: '',     // Facultatif : ID stable pour regrouper les tours de conversation, généré automatiquement s’il est vide.
  model: '',              // Facultatif : modèle par défaut pour les tours de cette conversation.
});

Démarrer un tour de conversation

start_turn() (Python) et startTurn() (TypeScript) créent un nouveau span invoke_agent qui devient la racine d’une nouvelle trace OTel. Weave utilise ce span pour représenter un échange complet entre l’utilisateur et l’agent dans la vue chronologique. Vous pouvez l’appeler de deux façons :

En tant que fonction de premier niveau (weave.start_turn(...) / weave.startTurn(...)), comme dans les exemples ci-dessous. Elle résout la conversation active à partir du contexte et hérite de son ID de conversation. Si aucune conversation n’est active, le tour de conversation est créé sans conversation_id et n’est pas regroupé avec les autres tours de conversation.
En tant que méthode d’instance sur une conversation dont vous détenez une référence (conversation.start_turn(...) / conversation.startTurn(...)). Cette forme est utile lorsqu’un objet conversation explicite est disponible dans la portée, par exemple à l’intérieur d’un bloc de gestionnaire de contexte. L’exemple « Gestionnaire de contexte ou schéma try-finally » ci-dessous utilise cette forme. Consultez le tableau du modèle de données ci-dessus pour accéder directement aux pages de référence Conversation, Turn, LLM, Tool et SubAgent des deux SDK.

Python
TypeScript

turn = weave.start_turn(
    user_message="What is the weather in Tokyo?",  # Texte saisi par l’utilisateur.
    agent_name="my-agent",   # Facultatif : redéfinit le nom d’agent défini au niveau de la conversation.
    model="gpt-4o",          # Facultatif : modèle utilisé pour ce tour de conversation.
)

const turn = weave.startTurn({
  agentName: 'my-agent',  // Facultatif : redéfinit le nom d’agent défini au niveau de la conversation.
  model: 'gpt-4o',        // Facultatif : modèle utilisé pour ce tour de conversation.
});

Démarrer un appel LLM

start_llm() / startLLM() crée un span chat imbriqué dans le tour de conversation en cours. Weave utilise ce span pour afficher l’utilisation des jetons, le nom du modèle, les messages d’entrée et de sortie ainsi que le raisonnement dans la vue Agents.

Python
TypeScript

llm = weave.start_llm(
    model="gpt-4o",             # L’identifiant du modèle.
    provider_name="openai",     # Facultatif : nom du fournisseur, par exemple "openai", "anthropic". Voir la remarque ci-dessous.
    system_instructions=["Be concise."],  # Facultatif : chaînes du prompt système.
)

const llm = weave.startLLM({
  model: 'gpt-4o',          // L’identifiant du modèle.
  providerName: 'openai',   // Facultatif : nom du fournisseur, par exemple "openai", "anthropic". Voir la remarque ci-dessous.
});

Une fois l’appel LLM terminé, attribuez les données de réponse à l’objet llm avant sa fermeture :

Python
TypeScript

with weave.start_llm(model="gpt-4o", provider_name="openai") as llm:
    response = openai_client.chat.completions.create(...)
    llm.input_messages = [Message(role="user", content="...")]
    llm.output_messages = [Message(role="assistant", content=response.choices[0].message.content)]
    llm.usage = Usage(
        input_tokens=response.usage.prompt_tokens,
        output_tokens=response.usage.completion_tokens,
    )

const llm = weave.startLLM({ model: 'gpt-4o', providerName: 'openai' });
try {
  const response = await openaiClient.chat.completions.create({ ... });
  llm.record({
    inputMessages: [{ role: 'user', content: '...' }],
    outputMessages: [{ role: 'assistant', content: response.choices[0].message.content ?? '' }],
    usage: {
      inputTokens: response.usage?.prompt_tokens,
      outputTokens: response.usage?.completion_tokens,
    },
  });
} finally {
  llm.end();
}

llm.record() est un raccourci qui permet d’attribuer inputMessages, outputMessages, usage et reasoning en un seul appel. Vous pouvez néanmoins définir chaque propriété séparément si vous le souhaitez. Le SDK Python expose la même méthode sous la forme llm.record(...), avec des arguments nommés en snake_case.

Transmettez explicitement provider_name / providerName. Weave ne le déduit pas de la chaîne du modèle.

Démarrer un appel d’outil

start_tool() / startTool() crée un span execute_tool. Ce span devient l’enfant du span OTel actif dans le contexte (généralement le span chat de l’appel LLM à l’origine de l’appel d’outil).

Python
TypeScript

tool = weave.start_tool(
    name="get_weather",                  # Nom de l’outil tel que déclaré au LLM.
    arguments='{"city": "Tokyo"}',       # Chaîne JSON des arguments de l’outil.
    tool_call_id="call_abc123",          # Facultatif : ID de l’appel d’outil issu de la réponse du LLM.
)

const tool = weave.startTool({
  name: 'get_weather',            // Nom de l’outil tel que déclaré au LLM.
  args: '{"city": "Tokyo"}',      // Facultatif : chaîne JSON des arguments de l’outil.
  toolCallId: 'call_abc123',      // Facultatif : ID de l’appel d’outil issu de la réponse du LLM.
});

Attribuez le résultat de l’outil avant de fermer le span :

Python
TypeScript

with weave.start_tool(name="get_weather", arguments='{"city": "Tokyo"}') as tool:
    result = get_weather_api("Tokyo")
    tool.result = result  # Accepte un dict, une liste ou une chaîne. Encodé automatiquement en JSON.

const tool = weave.startTool({ name: 'get_weather', args: '{"city": "Tokyo"}' });
try {
  tool.result = await getWeatherApi('Tokyo');
} finally {
  tool.end();
}

Modèles d’utilisation pour le traçage d’agents

Les sections suivantes décrivent comment combiner ces fonctions selon la structure de votre code d’agent. Les exemples suivants utilisent deux types du SDK Weave :

Message (Python · TypeScript) représente une entrée unique d’une conversation : une saisie de l’utilisateur, une réponse de l’assistant, un prompt système ou le résultat d’un outil. Attribuez une liste de messages à llm.input_messages / llm.inputMessages pour enregistrer ce que le modèle a reçu, et à llm.output_messages / llm.outputMessages pour enregistrer ce qu’il a produit.
Usage (Python · TypeScript) capture le nombre de jetons indiqué dans la réponse du LLM et est attribué à llm.usage.

Weave s’appuie sur ces deux types pour alimenter la vue Agents avec l’entrée, la sortie et l’utilisation des jetons de chaque appel LLM.

Gestionnaire de contexte ou schéma try-finally

Pour la plupart des agents, utilisez un gestionnaire de contexte en Python ou un schéma try-finally en TypeScript. Le span est fermé puis envoyé à la fin du bloc, même en cas d’exception. Weave conserve dans le contexte la conversation, le tour de conversation et l’appel LLM actifs. Ainsi, toute fonction appelée dans un bloc peut appeler start_llm() / startLLM() ou start_tool() / startTool() sans avoir à conserver de référence explicite au parent. Ce mécanisme fonctionne d’un module à l’autre, tant que le code s’exécute dans le même contexte asynchrone. Pour récupérer les objets actifs depuis n’importe quel niveau de la pile d’appels, utilisez weave.get_current_conversation() / weave.getCurrentConversation(), weave.get_current_turn() / weave.getCurrentTurn() et weave.get_current_llm() / weave.getCurrentLLM().

Python
TypeScript

import weave
from weave.conversation import Message, Usage

# Fonctions fictives : remplacez-les par vos propres implémentations.
def call_openai(*args, **kwargs):
    pass  # Remplacez par l’appel à votre client LLM.

def get_weather_api(city: str) -> str:
    return "24°C, sunny"  # Remplacez par l’appel à votre API météo.

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

with weave.start_conversation(agent_name="weather-bot") as conversation:
    with conversation.start_turn(user_message="What is the weather in Tokyo?") as turn:

        # Premier appel LLM : renvoie un appel d’outil.
        with weave.start_llm(model="gpt-4o", provider_name="openai") as llm:
            response = call_openai(...)
            llm.input_messages = [Message(role="user", content="What is the weather?")]
            llm.think("User wants weather data, I should call get_weather.")
            llm.output("Let me check the weather for you.")
            llm.usage = Usage(input_tokens=100, output_tokens=20)

            # Appel d’outil : enfant de l’appel LLM qui l’a demandé.
            with weave.start_tool(name="get_weather", arguments='{"city":"Tokyo"}') as tool:
                tool.result = get_weather_api("Tokyo")  # Renvoie "24°C, sunny".

        # Deuxième appel LLM : synthétise la réponse finale.
        with weave.start_llm(model="gpt-4o", provider_name="openai") as llm:
            llm.input_messages = [Message(role="user", content="What is the weather?")]
            llm.output("It is 24°C and sunny in Tokyo today.")
            llm.usage = Usage(input_tokens=150, output_tokens=30)

import * as weave from 'weave';
import type { Message, Usage } from 'weave';

// Fonction fictive : remplacez-la par votre propre implémentation.
async function getWeatherApi(city: string): Promise<string> {
  return '24°C, sunny';  // Remplacez par l’appel à votre API météo.
}

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

const conversation = weave.startConversation({ agentName: 'weather-bot' });
try {
  const turn = conversation.startTurn({ agentName: 'weather-bot' });
  try {
    // Premier appel LLM : renvoie un appel d’outil.
    const llm = weave.startLLM({ model: 'gpt-4o', providerName: 'openai' });
    try {
      llm.inputMessages = [{ role: 'user', content: 'What is the weather?' }];
      llm.think('User wants weather data, I should call get_weather.');
      llm.output('Let me check the weather for you.');
      llm.usage = { inputTokens: 100, outputTokens: 20 };

      // Appel d’outil : enfant de l’appel LLM qui l’a demandé.
      const tool = weave.startTool({ name: 'get_weather', args: '{"city":"Tokyo"}' });
      try {
        tool.result = await getWeatherApi('Tokyo');  // Renvoie "24°C, sunny".
      } finally {
        tool.end();
      }
    } finally {
      llm.end();
    }

    // Deuxième appel LLM : synthétise la réponse finale.
    const llm2 = weave.startLLM({ model: 'gpt-4o', providerName: 'openai' });
    try {
      llm2.inputMessages = [{ role: 'user', content: 'What is the weather?' }];
      llm2.output('It is 24°C and sunny in Tokyo today.');
      llm2.usage = { inputTokens: 150, outputTokens: 30 };
    } finally {
      llm2.end();
    }
  } finally {
    turn.end();
  }
} finally {
  conversation.end();
}

Modèle de démarrage et de fin manuels

Appelez .end() explicitement lorsque vous ne pouvez pas utiliser de blocs with ni try/finally, par exemple lorsque vous ouvrez et fermez des spans dans des appels de fonction distincts, ou lorsque vous gérez le cycle de vie asynchrone en dehors d’une coroutine. Il vous appartient d’appeler .end() sur chaque objet que vous créez, afin que les spans soient fermés et transmis au collecteur.

Python
TypeScript

conversation = weave.start_conversation(agent_name="weather-bot")
turn = conversation.start_turn(user_message="What is the weather?")

llm = weave.start_llm(model="gpt-4o", provider_name="openai")
llm.input_messages = [Message(role="user", content="What is the weather?")]
llm.output("Let me check.")
llm.usage = Usage(input_tokens=100, output_tokens=20)

tool = weave.start_tool(name="get_weather", arguments='{"city": "Tokyo"}')
tool.result = "24°C, sunny"
tool.end()   # end() est idempotent — peut être appelé plusieurs fois sans risque.

llm.end()

llm2 = weave.start_llm(model="gpt-4o", provider_name="openai")
llm2.output("It is 24°C and sunny in Tokyo.")
llm2.usage = Usage(input_tokens=150, output_tokens=30)
llm2.end()

turn.end()
conversation.end()

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

const llm = weave.startLLM({ model: 'gpt-4o', providerName: 'openai' });
llm.inputMessages = [{ role: 'user', content: 'What is the weather?' }];
llm.output('Let me check.');
llm.usage = { inputTokens: 100, outputTokens: 20 };

const tool = weave.startTool({ name: 'get_weather', args: '{"city": "Tokyo"}' });
tool.result = '24°C, sunny';
tool.end();  // end() est idempotent : peut être appelé plusieurs fois sans risque.

llm.end();

const llm2 = weave.startLLM({ model: 'gpt-4o', providerName: 'openai' });
llm2.output('It is 24°C and sunny in Tokyo.');
llm2.usage = { inputTokens: 150, outputTokens: 30 };
llm2.end();

turn.end();
conversation.end();

Conventions sémantiques

Le SDK Weave émet des spans OTel conformes aux conventions sémantiques GenAI et aux conventions de spans d’agent GenAI. Weave accepte n’importe quel span OTel, en stocke tous les attributs et permet de les interroger par requête. Vous pouvez ajouter des attributs personnalisés aux spans à l’aide de l’API de span OTel standard, en complément des objets de traçage de Weave.

Affichage des données dans l’interface Weights & Biases

Une fois votre agent instrumenté à l’aide des modèles précédents puis exécuté, vos traces apparaissent dans l’onglet Agents de votre projet Weave, à l’adresse https://forge.coreweave.com/wandb/[YOUR-TEAM]/[YOUR-PROJECT]/weave/agents.

L’onglet Conversations affiche toutes les conversations, accompagnées d’une mini-carte de l’activité des tours de conversation.
La vue détaillée d’une conversation s’ouvre lorsque vous cliquez sur une conversation. Elle affiche tous ses tours de conversation, ses appels LLM, ses exécutions d’outils, le nombre de jetons ainsi que tout feedback joint.

Pour en savoir plus sur l’affichage des données Agents dans Weave, consultez Afficher l’activité des agents.

​Avant de commencer

​Le modèle de données des agents

​API de traçage d’agents

​Démarrer une conversation

​Démarrer un tour de conversation

​Démarrer un appel LLM

​Démarrer un appel d’outil

​Modèles d’utilisation pour le traçage d’agents

​Gestionnaire de contexte ou schéma try-finally

​Modèle de démarrage et de fin manuels

​Conventions sémantiques

​Affichage des données dans l’interface Weights & Biases

Avant de commencer

Le modèle de données des agents

API de traçage d’agents

Démarrer une conversation

Démarrer un tour de conversation

Démarrer un appel LLM

Démarrer un appel d’outil

Modèles d’utilisation pour le traçage d’agents

Gestionnaire de contexte ou schéma try-finally

Modèle de démarrage et de fin manuels

Conventions sémantiques

Affichage des données dans l’interface Weights & Biases