Démarrage rapide : Configurer l’observabilité personnalisée d’un agent

Essayer dans Colab · Code source GitHub Le SDK Weave vous permet de tracer des agents créés avec des SDK populaires ou des harnesses personnalisés. Ce Démarrage rapide vous montre comment intégrer manuellement Weave dans un agent personnalisé sur plusieurs tours de conversation afin d’émettre et de capturer des spans OpenTelemetry. Pour une compréhension conceptuelle de Weave pour les agents, voir Tracer vos agents. Si vous souhaitez intégrer Weave à des SDK ou à des harnesses comme Claude Agent SDK ou Codex, voir Choisir une intégration d’agent. Weave applique automatiquement des patchs à plusieurs SDK de création d’agents et harness d’agents pour une intégration rapide.

Ce que vous allez apprendre

À la fin de ce démarrage rapide, vous disposerez d’un agent fonctionnel sur plusieurs tours de conversation qui émet des spans OTel compatibles avec Weave. Vous comprendrez également comment Weave fait correspondre les conversations, les tours de conversation, les appels LLM et les appels d’outil à votre code d’agent, afin de pouvoir appliquer le même modèle à vos propres agents personnalisés. Le code de ce guide configure un petit agent de recherche capable d’interroger Wikipédia. Il pose trois questions (trois tours de conversation) et utilise le LLM pour choisir quand effectuer une recherche sur Wikipédia afin de trouver une réponse. Weave enregistre chaque étape (la conversation, chaque question, chaque réponse de l’IA et chaque recherche sur Wikipédia) pour que vous puissiez voir ce qui s’est passé dans la vue Agents de Weave. Ce guide vous montre comment :

Initialiser Weave pour le traçage d’agent avec weave.init().
Ouvrir une conversation et un tour de conversation avec start_conversation / startConversation et start_turn / startTurn.
Encapsuler les appels LLM avec start_llm / startLLM et enregistrer l’utilisation.
Encapsuler les exécutions d’outil avec start_tool / startTool et enregistrer les résultats.
Enregistrer l’utilisation complète des jetons et un modèle avec tarification afin que le nombre de jetons et le coût soient affichés.
Afficher la conversation, les tours de conversation et les appels d’outil obtenus dans la vue Agents.

Fonctionnement du SDK Weave avec les agents

Le SDK Weave inclut un système d’ingestion OTel générique pour les agents, ce qui signifie que Weave peut capturer des informations à partir de n’importe quel span OTel dans le code de votre agent. Cependant, Weave nécessite un traitement particulier des spans suivants pour afficher les traces de votre agent dans la vue Agents de l’interface Weave.

Concept	Python	TypeScript	span OTel
Une conversation	`weave.start_conversation(...)`	`weave.startConversation(...)`	(pas de span, regroupe les tours de conversation)
Un échange utilisateur ou agent	`weave.start_turn(...)`	`weave.startTurn(...)`	`invoke_agent`
Un appel d’API LLM	`weave.start_llm(...)`	`weave.startLLM(...)`	`chat`
Une exécution d’outil	`weave.start_tool(...)`	`weave.startTool(...)`	`execute_tool`

En Python, les quatre fonctions s’utilisent comme des gestionnaires de contexte (with weave.start_*(...) as obj:). À la fin du contexte, elles ferment le span et effectuent le vidage des attributs, y compris en cas d’exception. En TypeScript, appelez .end() sur chaque objet renvoyé. Utilisez try { ... } finally { obj.end(); } pour garantir le nettoyage en cas d’exception. D’autres attributs de conventions sémantiques GenAI, tels que gen_ai.usage.* et gen_ai.agent.name, permettent un rendu supplémentaire, mais ils sont facultatifs.

Prérequis

Un compte W&B et une clé API.
Une clé API OpenAI.
Python 3.10+ (pour les exemples en Python).
Node.js 18+ (les exemples TypeScript nécessitent la fonction fetch intégrée).

Installer les paquets

Installez les paquets suivants dans votre environnement de développement :

pip install weave openai requests

npm install weave openai

Initialiser Weave

weave.init() s’authentifie auprès de W&B et configure l’exporteur OTel qui envoie les spans d’agent vers la vue Agents. Si le projet n’existe pas dans votre équipe, Weave le crée lors du premier envoi de données.

import getpass
import os

os.environ["WANDB_API_KEY"] = getpass.getpass("Enter your W&B API key: ")
os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter your OpenAI API key: ")

TEAM = input("Enter your W&B team name: ")
PROJECT = input("Enter your W&B project name: ")

import weave
weave.init(f"{TEAM}/{PROJECT}")

// Définissez WANDB_API_KEY et OPENAI_API_KEY dans votre environnement avant d’exécuter ce projet
import * as weave from 'weave';

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

Définir un outil

Le code suivant définit l’outil de recherche Wikipédia de l’agent, ainsi qu’un schéma d’outil OpenAI qui indique quand et comment utiliser cet outil.

import json
import requests

def wikipedia_search(query: str) -> str:
    r = requests.get(
        "https://en.wikipedia.org/w/api.php",
        params={
            "action": "query", "generator": "search", "gsrsearch": query, "gsrlimit": 1,
            "prop": "extracts", "exintro": True, "explaintext": True, "format": "json",
        },
        headers={"User-Agent": "weave-demo"},
    ).json()
    return next(iter(r["query"]["pages"].values()))["extract"]

wikipedia_tool_schema = {
    "type": "function",
    "function": {
        "name": "wikipedia_search",
        "description": "Search Wikipedia for a topic and return its intro paragraph.",
        "parameters": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    },
}

async function wikipediaSearch(query: string): Promise<string> {
  const url = new URL('https://en.wikipedia.org/w/api.php');
  url.search = new URLSearchParams({
    action: 'query',
    generator: 'search',
    gsrsearch: query,
    gsrlimit: '1',
    prop: 'extracts',
    exintro: 'true',
    explaintext: 'true',
    format: 'json',
  }).toString();
  const res = await fetch(url, { headers: { 'User-Agent': 'weave-demo' } });
  const data = (await res.json()) as {
    query: { pages: Record<string, { extract: string }> };
  };
  return Object.values(data.query.pages)[0].extract;
}

const wikipediaToolSchema = {
  type: 'function' as const,
  function: {
    name: 'wikipedia_search',
    description: 'Search Wikipedia for a topic and return its intro paragraph.',
    parameters: {
      type: 'object',
      properties: { query: { type: 'string' } },
      required: ['query'],
    },
  },
};

Exécuter un agent tracé sur plusieurs tours de conversation

Une fois l’outil et l’initialisation de Weave en place, l’étape suivante consiste à les intégrer dans une boucle d’exécution complète de l’agent. Cette boucle montre comment les conversations, les tours de conversation, les appels LLM et les appels d’outil s’imbriquent. L’exemple suivant exécute trois tours de conversation dans une seule conversation. Chaque tour de conversation :

Ouvre un span chat et laisse le LLM choisir s’il doit appeler l’outil.
Si le LLM demande à utiliser l’outil, ouvre un span execute_tool autour de l’appel et renvoie le résultat au LLM.
Ouvre un second span chat pour produire la réponse finale.

import weave
from openai import OpenAI

openai_client = OpenAI()
MODEL = "gpt-4o-mini"

def run_turn(history, user_message):
    history.append({"role": "user", "content": user_message})

    with weave.start_turn(user_message=user_message, model=MODEL):
        # Appel LLM 1 : le modèle peut décider d'utiliser un outil.
        with weave.start_llm(model=MODEL, provider_name="openai") as llm:
            resp = openai_client.chat.completions.create(
                model=MODEL, messages=history, tools=[wikipedia_tool_schema],
            )
            msg = resp.choices[0].message
            llm.output(msg.content or "")
            # record() définit l'utilisation, le modèle facturé et l'ID de réponse en un seul appel.
            llm.record(
                usage=weave.Usage(
                    input_tokens=resp.usage.prompt_tokens,
                    output_tokens=resp.usage.completion_tokens,
                    cache_read_input_tokens=getattr(
                        resp.usage.prompt_tokens_details, "cached_tokens", 0
                    ),
                ),
                response_id=resp.id,
                response_model=resp.model,
            )
            history.append(msg.model_dump(exclude_none=True))

        # Si aucun outil n'a été demandé, la première réponse LLM est la réponse finale.
        if not msg.tool_calls:
            return msg.content

        # Exécuter chaque appel d'outil demandé.
        for tc in msg.tool_calls:
            with weave.start_tool(
                name=tc.function.name,
                arguments=tc.function.arguments,
                tool_call_id=tc.id,
            ) as tool:
                tool.result = wikipedia_search(**json.loads(tc.function.arguments))
                history.append({
                    "role": "tool",
                    "tool_call_id": tc.id,
                    "content": tool.result,
                })

        # Appel LLM 2 : synthétiser la réponse finale.
        with weave.start_llm(model=MODEL, provider_name="openai") as llm:
            resp = openai_client.chat.completions.create(model=MODEL, messages=history)
            msg = resp.choices[0].message
            llm.output(msg.content)
            llm.record(
                usage=weave.Usage(
                    input_tokens=resp.usage.prompt_tokens,
                    output_tokens=resp.usage.completion_tokens,
                    cache_read_input_tokens=getattr(
                        resp.usage.prompt_tokens_details, "cached_tokens", 0
                    ),
                ),
                response_id=resp.id,
                response_model=resp.model,
            )
            history.append({"role": "assistant", "content": msg.content})
            return msg.content

with weave.start_conversation(agent_name="research-bot") as conversation:
    history = []
    for question in [
        "Who founded Anthropic?",
        "What is Claude (the AI assistant)?",
        "Summarize what we discussed in one sentence.",
    ]:
        print(f"USER: {question}")
        print(f"AGENT: {run_turn(history, question)}\n")

// @noErrors
import * as weave from 'weave';
import OpenAI from 'openai';

const openaiClient = new OpenAI();
const MODEL = 'gpt-4o-mini';

// history est une liste de messages de chat OpenAI ; typé de façon souple par souci de concision.
async function runTurn(history: any[], userMessage: string): Promise<string | null> {
  history.push({ role: 'user', content: userMessage });

  const turn = weave.startTurn({ model: MODEL });
  try {
    // Appel LLM 1 : le modèle peut décider d'utiliser un outil.
    const llm1 = weave.startLLM({ model: MODEL, providerName: 'openai' });
    let msg;
    try {
      const resp = await openaiClient.chat.completions.create({
        model: MODEL,
        messages: history,
        tools: [wikipediaToolSchema],
      });
      msg = resp.choices[0].message;
      llm1.output(msg.content ?? '');
      // record() définit l'utilisation, le modèle facturé et l'ID de réponse en un seul appel.
      llm1.record({
        usage: {
          inputTokens: resp.usage?.prompt_tokens,
          outputTokens: resp.usage?.completion_tokens,
          cacheReadInputTokens: resp.usage?.prompt_tokens_details?.cached_tokens,
        },
        responseId: resp.id,
        responseModel: resp.model,
      });
      history.push(msg);
    } finally {
      llm1.end();
    }

    // Si aucun outil n'a été demandé, la première réponse LLM constitue la réponse finale.
    if (!msg.tool_calls?.length) {
      return msg.content ?? null;
    }

    // Exécuter chaque appel d'outil demandé.
    for (const tc of msg.tool_calls) {
      if (tc.type !== 'function') continue;
      const tool = weave.startTool({
        name: tc.function.name,
        args: tc.function.arguments,
        toolCallId: tc.id,
      });
      try {
        const { query } = JSON.parse(tc.function.arguments);
        tool.result = await wikipediaSearch(query);
        history.push({ role: 'tool', tool_call_id: tc.id, content: tool.result });
      } finally {
        tool.end();
      }
    }

    // Appel LLM 2 : synthétiser la réponse finale.
    const llm2 = weave.startLLM({ model: MODEL, providerName: 'openai' });
    try {
      const resp = await openaiClient.chat.completions.create({
        model: MODEL,
        messages: history,
      });
      const msg2 = resp.choices[0].message;
      llm2.output(msg2.content ?? '');
      llm2.record({
        usage: {
          inputTokens: resp.usage?.prompt_tokens,
          outputTokens: resp.usage?.completion_tokens,
          cacheReadInputTokens: resp.usage?.prompt_tokens_details?.cached_tokens,
        },
        responseId: resp.id,
        responseModel: resp.model,
      });
      history.push({ role: 'assistant', content: msg2.content });
      return msg2.content ?? null;
    } finally {
      llm2.end();
    }
  } finally {
    turn.end();
  }
}

const conversation = weave.startConversation({ agentName: 'research-bot' });
try {
  const history: any[] = [];
  for (const question of [
    'Who founded Anthropic?',
    'What is Claude (the AI assistant)?',
    'Summarize what we discussed in one sentence.',
  ]) {
    console.log(`USER: ${question}`);
    console.log(`AGENT: ${await runTurn(history, question)}\n`);
  }
} finally {
  conversation.end();
}

Enregistrer l’utilisation des jetons et le coût

Chaque span de chat inclut une utilisation des jetons et un ID du modèle. Weave affiche le nombre de jetons à partir de l’utilisation et calcule le coût à partir de l’utilisation et de l’ID du modèle. Ainsi, une valeur incomplète ou non tarifable affiche 0 in / 0 out tokens ou Cost -, même lorsque le reste de la trace semble correct. record(...) définit ces champs (ainsi que output_messages, response_id, reasoning, etc.) en un seul appel. Seuls les champs que vous transmettez sont pris en compte. Deux éléments doivent être corrects pour que le coût s’affiche :

Utilisation complète. input_tokens correspond au total des jetons en entrée, y compris ceux mis en cache. Weave facture les lectures et les écritures du cache à leurs propres tarifs et les soustrait du total d’entrée. cache_read_input_tokens et cache_creation_input_tokens doivent donc être signalés en plus d’un total input_tokens qui les inclut. Pour les providers avec mise en cache des prompts (par exemple, Anthropic), les jetons mis en cache représentent souvent la majeure partie de l’entrée. Les omettre fait donc apparaître l’utilisation et le coût comme quasiment nuls.
Un ID du modèle tarifable. Le coût repose sur une recherche basée sur le modèle. Weave privilégie response_model (le modèle exact servi par le provider) et se rabat sur le model que vous avez transmis à start_llm. Un alias tel que opus ou sonnet n’est pas tarifable et affiche Cost - ; transmettez donc l’ID exact renvoyé dans la réponse (resp.model) comme response_model.

OpenAI comptabilise les jetons mis en cache dans prompt_tokens, donc l’exemple ci-dessus s’applique directement. Anthropic signale les jetons mis en cache séparément de input_tokens ; ajoutez-les donc au total sur lequel Weave applique la tarification :

with weave.start_llm(model=MODEL, provider_name="anthropic") as llm:
    resp = anthropic_client.messages.create(
        model=MODEL, max_tokens=1024, messages=history,
    )
    u = resp.usage
    llm.output(resp.content[0].text)
    llm.record(
        usage=weave.Usage(
            input_tokens=u.input_tokens
            + u.cache_read_input_tokens
            + u.cache_creation_input_tokens,
            output_tokens=u.output_tokens,
            cache_read_input_tokens=u.cache_read_input_tokens,
            cache_creation_input_tokens=u.cache_creation_input_tokens,
        ),
        response_id=resp.id,
        response_model=resp.model,
    )

const u = resp.usage;
llm.record({
  usage: {
    inputTokens:
      u.input_tokens + u.cache_read_input_tokens + u.cache_creation_input_tokens,
    outputTokens: u.output_tokens,
    cacheReadInputTokens: u.cache_read_input_tokens,
    cacheCreationInputTokens: u.cache_creation_input_tokens,
  },
  responseId: resp.id,
  responseModel: resp.model,
});

Voir les traces de votre agent dans la vue Agents

Lorsque weave.init() s’exécute, il affiche un lien vers votre project dans lequel vous pouvez voir :

Une ligne dans l’onglet Agents pour research-bot.
Une conversation contenant trois tours de conversation.
Chaque tour de conversation (invoke_agent) avec deux spans chat et un span execute_tool imbriqué.
Le nombre de jetons, la latence, le modèle et l’échange complet de messages pour chaque chat.

Cliquez sur n’importe quel tour de conversation pour inspecter les entrées, les sorties, les arguments de l’outil et les résultats de l’outil.

Lien vers une conversation depuis votre application

Pour créer un lien direct depuis votre propre interface utilisateur vers une conversation dans la vue Weave Agents, construisez l’URL à partir de votre entité, de votre projet et de l’ID de la conversation. weave.init() renvoie un client qui contient entity et project, et start_conversation expose conversation_id.

from weave.trace.urls import agent_conversation_path

client = weave.init(f"{TEAM}/{PROJECT}")

with weave.start_conversation(agent_name="research-bot") as conversation:
    # ... exécuter des tours de conversation ...
    url = agent_conversation_path(
        client.entity, client.project, conversation.conversation_id
    )
    print(f"Affichez cette conversation à l’adresse {url}")

Cette fonctionnalité n’est pas disponible en TypeScript.

Prochaines étapes

Découvrez comment tracer des agents avec Weave, ainsi que les fonctionnalités et options disponibles dans le SDK Weave.
Voir Choisir une intégration d’agent pour découvrir d’autres options d’intégration de Weave avec vos agents.

Premiers pas

Guides

Guides pratiques

Référence

Détails et assistance

Démarrage rapide : Configurer l’observabilité personnalisée d’un agent

Ce que vous allez apprendre

Fonctionnement du SDK Weave avec les agents

Prérequis

Installer les paquets

Initialiser Weave

Définir un outil

Exécuter un agent tracé sur plusieurs tours de conversation

Enregistrer l’utilisation des jetons et le coût

Voir les traces de votre agent dans la vue Agents

Lien vers une conversation depuis votre application

Prochaines étapes

​Ce que vous allez apprendre

​Fonctionnement du SDK Weave avec les agents

​Prérequis

​Installer les paquets

​Initialiser Weave

​Définir un outil

​Exécuter un agent tracé sur plusieurs tours de conversation

​Enregistrer l’utilisation des jetons et le coût

​Voir les traces de votre agent dans la vue Agents

​Lien vers une conversation depuis votre application

​Prochaines étapes

Ce que vous allez apprendre

Fonctionnement du SDK Weave avec les agents

Prérequis

Installer les paquets

Initialiser Weave

Définir un outil

Exécuter un agent tracé sur plusieurs tours de conversation

Enregistrer l’utilisation des jetons et le coût

Voir les traces de votre agent dans la vue Agents

Lien vers une conversation depuis votre application

Prochaines étapes