> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-docs-sandboxes-integrations-placement.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Démarrage rapide : tracer un agent

> Tracez un agent sur plusieurs tours de conversation avec le SDK Weave. Les sessions, les tours de conversation, les appels LLM et les appels d’outil s’affichent dans la vue Agents de votre projet.

<Note>
  Weave for Agents est en préversion publique. Les fonctionnalités, les API et l’interface utilisateur de la vue Agents peuvent encore évoluer avant la disponibilité générale.
</Note>

[Essayer dans Colab](https://colab.research.google.com/github/wandb/docs/blob/main/weave/cookbooks/source/agents-quickstart.ipynb) · [Code source sur GitHub](https://github.com/wandb/docs/blob/main/weave/cookbooks/source/agents-quickstart.ipynb)

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 à un agent sur plusieurs tours de conversation personnalisé afin d’émettre et de capturer des spans OpenTelemetry. Pour une compréhension conceptuelle de Weave pour les agents, voir [Tracer vos agents](/fr/weave/guides/tracking/trace-agents).

Si vous cherchez à intégrer Weave à des SDK ou à des harnesses comme le Claude Agent SDK ou Codex, voir [Tracer les intégrations d’agents](/fr/weave/guides/tracking/trace-agent-integrations). Weave applique automatiquement des patchs à plusieurs SDK de création d’agents ainsi qu’à des harnesses d’agents pour une intégration rapide.

<div id="what-youll-learn">
  ## Ce que vous allez apprendre
</div>

À 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 sessions, les tours de conversation, les appels LLM et les appels d’outil au code de votre agent, afin que vous puissiez appliquer le même modèle à vos propres agents personnalisés.

Le code de ce guide met en place un petit agent de recherche capable de consulter Wikipédia. Il pose trois questions (trois tours de conversation) et utilise le LLM pour décider quand interroger Wikipédia afin d’obtenir une réponse. Weave enregistre chaque étape (la conversation, chaque question, chaque réponse de l’IA et chaque recherche sur Wikipédia) afin 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 des agents avec `weave.init()`.
* Ouvrir une session et un tour de conversation avec `start_session` / `startSession` et `start_turn` / `startTurn`.
* Encapsuler les appels LLM avec `start_llm` / `startLLM` et enregistrer l’utilisation.
* Encapsuler les exécutions d’outils avec `start_tool` / `startTool` et enregistrer les résultats.
* Voir la session, les tours de conversation et les appels d’outil obtenus dans la vue Agents.

<div id="how-the-weave-sdk-works-with-agents">
  ## Fonctionnement du SDK Weave avec les agents
</div>

Le SDK Weave inclut un système générique d'ingestion OTel 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 une gestion particulière 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_session(...)` | `weave.startSession(...)` | (aucun 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 sortie, elles terminent le span et vident les 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 convention sémantique GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/), tels que `gen_ai.usage.*` et `gen_ai.agent.name`, permettent un rendu supplémentaire, mais ils sont facultatifs.

<div id="prerequisites">
  ## Prérequis
</div>

* Un compte W\&B et une [clé API](https://wandb.ai/authorize).
* Une clé API OpenAI.
* Python 3.10+ (pour les exemples en Python).
* Node.js 18+ (les exemples en TypeScript requièrent `fetch` intégré).

<div id="install-packages">
  ## Installer les paquets
</div>

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

<CodeGroup>
  ```bash Python theme={null}
  pip install weave openai requests
  ```

  ```bash TypeScript theme={null}
  npm install weave openai
  ```
</CodeGroup>

<div id="initialize-weave">
  ## Initialiser Weave
</div>

`weave.init()` s’authentifie auprès de W\&B et configure l’exporter 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 de la première écriture.

<CodeGroup>
  ```python lines Python theme={null}
  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}")
  ```

  ```typescript lines highlight="4" TypeScript twoslash theme={null}
  // @noErrors
  // 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]`);
  ```
</CodeGroup>

<div id="define-a-tool">
  ## Définir un outil
</div>

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

<CodeGroup>
  ```python lines Python theme={null}
  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"],
          },
      },
  }
  ```

  ```typescript lines TypeScript twoslash theme={null}
  // @noErrors
  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'],
      },
    },
  };
  ```
</CodeGroup>

<div id="run-a-traced-multi-turn-agent">
  ## Exécuter un agent tracé sur plusieurs tours de conversation
</div>

Une fois l’outil et l’initialisation de Weave en place, l’étape suivante consiste à les intégrer dans une boucle d’agent complète. Cette boucle montre comment les sessions, 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 même session. Chaque tour de conversation :

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

<CodeGroup>
  ```python lines highlight="9,11,17,29,42,46,53" Python theme={null}
  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 "")
              llm.usage = weave.Usage(
                  input_tokens=resp.usage.prompt_tokens,
                  output_tokens=resp.usage.completion_tokens,
              )
              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.usage = weave.Usage(
                  input_tokens=resp.usage.prompt_tokens,
                  output_tokens=resp.usage.completion_tokens,
              )
              history.append({"role": "assistant", "content": msg.content})
              return msg.content

  with weave.start_session(agent_name="research-bot") as session:
      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")
  ```

  ```typescript lines highlight="10,13,39,54,76" TypeScript twoslash theme={null}
  // @noErrors
  import OpenAI from 'openai';

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

  // history is a list of OpenAI chat messages; typed loosely for brevity.
  async function runTurn(history: any[], userMessage: string): Promise<string | null> {
    history.push({ role: 'user', content: userMessage });

    const turn = weave.startTurn({ userMessage, 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 ?? '');
        llm1.usage = {
          inputTokens: resp.usage?.prompt_tokens,
          outputTokens: resp.usage?.completion_tokens,
        };
        history.push(msg);
      } finally {
        llm1.end();
      }

      // Si aucun outil n'a été demandé, la première réponse du LLM est 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) {
        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.usage = {
          inputTokens: resp.usage?.prompt_tokens,
          outputTokens: resp.usage?.completion_tokens,
        };
        history.push({ role: 'assistant', content: msg2.content });
        return msg2.content ?? null;
      } finally {
        llm2.end();
      }
    } finally {
      turn.end();
    }
  }

  const session = weave.startSession({ 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 {
    session.end();
  }
  ```
</CodeGroup>

<div id="see-your-agent-traces-in-the-agents-view">
  ## Voir les traces de votre agent dans la vue Agents
</div>

Lorsque `weave.init()` s'exécute, un lien vers votre projet s'affiche, où vous pouvez voir :

* Une ligne dans l'onglet **Agents** pour `research-bot`.
* Une session contenant trois tours de conversation.
* Chaque tour (`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 pour inspecter les entrées, les sorties, les arguments de l'outil et les résultats de l'outil.

<div id="next-steps">
  ## Étapes suivantes
</div>

* Découvrez comment [tracer des agents avec Weave](/fr/weave/guides/tracking/trace-agents), ainsi que des fonctionnalités et options disponibles dans le SDK Weave.
* Consultez [Tracer les intégrations d’agents](/fr/weave/guides/tracking/trace-agent-integrations) pour découvrir d’autres options permettant d’intégrer Weave à vos agents.