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

# Tracer les sous-agents

> Utilisez le span de sous-agent de Weave pour tracer les délégations à des sous-agents et visualiser les appels d’agent imbriqués.

export const AgentLensBanner = ({href}) => <Tip>
    <strong>This workflow is also available in CoreWeave Agent Lens.</strong> Agent Lens is the Forge experience built for tracing, monitoring, and analyzing AI agents, with automated insights into agent failures and user intents. It uses the same trace data as Weights & Biases Weave, so the traces you already send appear there with nothing to migrate.{' '}
    <a href={href || '/products/agent-lens'}>{href ? 'See how to do this in Agent Lens' : 'Learn about Agent Lens'}</a>.
  </Tip>;

<AgentLensBanner href="/fr/products/agent-lens/tracing/sub-agents" />

Ce guide explique comment utiliser W\&B Weave pour tracer les sous-agents, afin que les appels d’agent délégués apparaissent sous forme de spans imbriqués dans la même trace que le tour de conversation parent. Le traçage des sous-agents vous permet de visualiser la hiérarchie complète du raisonnement d'un agent : quels agents spécialisés l'agent parent a appelés, ce qu'ils ont fait et comment ils ont contribué à la réponse finale. Ce guide s'adresse aux développeurs qui instrumentent des systèmes multi-agents avec Weave.

Un sous-agent est un appel d’agent délégué qui s'exécute au sein d'un tour de conversation. Utilisez des sous-agents lorsqu'un agent passe le relais à un autre, par exemple lorsqu'un agent superviseur confie une tâche à un agent spécialisé.

Une fois instrumentés avec Weave, les sous-agents émettent un span OpenTelemetry (OTel) `invoke_agent` imbriqué dans la même trace que le tour de conversation parent. Dans la vue **Agents**, cette imbrication s'affiche sous la forme d'un appel de sous-agent placé sous le tour de conversation qui l'a déclenché, avec ses propres appels LLM et appels d’outil regroupés en dessous.

<h2 id="sub-agent-data-model">
  Modèle de données des sous-agents
</h2>

Avant d’instrumenter votre code, il est utile de comprendre comment Weave représente les sous-agents dans une trace. Le span `weave.start_subagent` correspond au span OTel `invoke_agent` et émet le même nom d’opération que le tour de conversation parent. Weave les distingue grâce à leur relation parent-enfant dans la trace :

```plaintext theme={"system"}
Turn (invoke_agent — span racine)
├── Appel LLM (chat)             ← raisonnement de l’agent parent
│   └── SubAgent (invoke_agent)  ← c’est ici qu’a lieu la délégation
│       ├── Appel LLM (chat)     ← appel LLM propre au sous-agent
│       └── Appel d’outil (execute_tool)
└── Appel LLM (chat)             ← l’agent parent synthétise la réponse finale
```

Les sous-agents héritent du `conversation_id` de la conversation active, ce qui les regroupe avec le reste de la conversation dans la vue **Agents**.

```python lines theme={"system"}
sub = weave.start_subagent(
    name="research-specialist",   # Requis : identifie ce sous-agent dans l’interface utilisateur.
    model="gpt-4o",               # Facultatif : si vide, le modèle de la conversation parente est utilisé par défaut.
)
```

`weave.start_subagent` crée un span `invoke_agent` qui devient automatiquement l’enfant du span actif dans le contexte OTel, en général le tour de conversation parent ou l’appel LLM à l’origine de la délégation. La propagation du contexte OTel gère la relation parent-enfant ; vous n'avez donc pas besoin de déclarer explicitement la délégation.

<h2 id="trace-a-single-sub-agent">
  Tracer un seul sous-agent
</h2>

L’exemple suivant exécute un agent superviseur qui reçoit une requête et la délègue à un sous-agent spécialisé dans la recherche, lequel utilise un outil de recherche Wikipédia pour trouver la réponse.

Weave capture la hiérarchie complète en encapsulant la conversation dans `weave.start_conversation`, puis dans un `conversation.start_turn`. Weave capture ensuite la trace du sous-agent à l’aide du bloc `weave.start_subagent` dédié au spécialiste, et enregistre chaque appel LLM et chaque exécution d’outil sous forme de spans enfants.

La logique d’acheminement est volontairement omise de ces exemples pour mettre l’accent sur le traçage entre les agents.

```python lines highlight="4,10,16,22,30" theme={"system"}
import weave
from weave.conversation import Message, Usage

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

with weave.start_conversation(agent_name="supervisor") as conversation:
    with conversation.start_turn(user_message="Research the founders of Anthropic.") as turn:

        # Appel LLM du superviseur : choisir le spécialiste auquel déléguer la tâche.
        with weave.start_llm(model="gpt-4o", provider_name="openai") as llm:
            llm.input_messages = [Message(role="user", content="Research the founders of Anthropic.")]
            llm.output("Delegating to the research specialist.")
            llm.usage = Usage(input_tokens=80, output_tokens=10)

        # Déléguer la tâche au spécialiste de la recherche, en tant que sous-agent.
        with weave.start_subagent(name="research-specialist", model="gpt-4o") as sub:
            with sub.llm(model="gpt-4o", provider_name="openai") as sub_llm:
                sub_llm.input_messages = [Message(role="user", content="Find founders of Anthropic.")]
                sub_llm.output("I should search for this.")
                sub_llm.usage = Usage(input_tokens=120, output_tokens=15)

                with weave.start_tool(name="wikipedia_search", arguments='{"query":"Anthropic"}') as tool:
                    tool.result = "Anthropic was founded by Dario and Daniela Amodei in 2021."

            with sub.llm(model="gpt-4o", provider_name="openai") as sub_llm:
                sub_llm.output("Anthropic was founded by Dario and Daniela Amodei in 2021.")
                sub_llm.usage = Usage(input_tokens=200, output_tokens=25)

        # Retour au tour de conversation du superviseur : synthétiser la réponse finale.
        with weave.start_llm(model="gpt-4o", provider_name="openai") as llm:
            llm.output("Anthropic was founded by Dario and Daniela Amodei in 2021.")
            llm.usage = Usage(input_tokens=300, output_tokens=20)
```

Dans la vue **Agents**, le sous-agent apparaît sous la forme d’un bloc `invoke_agent` imbriqué dans le tour de conversation, ses propres appels LLM et appels d’outils étant regroupés en dessous. Les appels LLM directs du superviseur restent au même niveau que le sous-agent.

<h2 id="trace-multiple-sub-agents">
  Tracer plusieurs sous-agents
</h2>

L’exemple suivant exécute un agent de pipeline de contenu qui traite une requête unique en la déléguant successivement à trois sous-agents au même niveau : un `researcher` qui rassemble les faits, un `writer` qui rédige l’article et un `reviewer` qui peaufine le résultat final.

Weave capture les trois sous-agents au même niveau dans le même tour de conversation en ouvrant un bloc `weave.start_subagent` distinct pour chacun. Comme chaque sous-agent hérite du contexte OTel du tour de conversation actif, les sous-agents apparaissent comme des spans `invoke_agent` de même niveau, imbriqués dans le tour de conversation plutôt que les uns dans les autres.

```python lines highlight="1,5,11,15,22" theme={"system"}
with weave.start_conversation(agent_name="content-pipeline") as conversation:
    with conversation.start_turn(user_message="Write a short blog post about Anthropic.") as turn:

        # Sous-agent researcher : recueillir les faits.
        with weave.start_subagent(name="researcher", model="gpt-4o") as researcher:
            with researcher.llm(model="gpt-4o", provider_name="openai") as sub_llm:
                sub_llm.input_messages = [Message(role="user", content="Find key facts about Anthropic.")]
                sub_llm.output("I should search Wikipedia.")
                sub_llm.usage = Usage(input_tokens=80, output_tokens=15)

                with weave.start_tool(name="wikipedia_search", arguments='{"query":"Anthropic"}') as tool:
                    tool.result = "Anthropic was founded by Dario and Daniela Amodei in 2021."

        # Sous-agent writer : rédiger un premier jet de l’article.
        with weave.start_subagent(name="writer", model="gpt-4o") as writer:
            with writer.llm(model="gpt-4o", provider_name="openai") as sub_llm:
                sub_llm.input_messages = [Message(role="user", content="Draft a post using the research.")]
                sub_llm.output("Anthropic, founded in 2021 by Dario and Daniela Amodei, builds AI safety research...")
                sub_llm.usage = Usage(input_tokens=180, output_tokens=120)

        # Sous-agent reviewer : peaufiner le brouillon.
        with weave.start_subagent(name="reviewer", model="gpt-4o") as reviewer:
            with reviewer.llm(model="gpt-4o", provider_name="openai") as sub_llm:
                sub_llm.input_messages = [Message(role="user", content="Review and tighten the draft.")]
                sub_llm.output("Final post: Anthropic, founded in 2021 by Dario and Daniela Amodei, builds AI safety research...")
                sub_llm.usage = Usage(input_tokens=200, output_tokens=140)
```

Dans la vue **Agents**, le tour de conversation contient trois appels de sous-agents au même niveau, chacun accompagné de son propre appel LLM imbriqué en dessous, et le `researcher` inclut son appel d’outil. Aucun sous-agent n’est l’enfant d’un autre.

<h2 id="trace-nested-sub-agents">
  Tracer des sous-agents imbriqués
</h2>

Un sous-agent peut lui-même déléguer une tâche à un autre sous-agent. Chaque appel à `start_subagent` s’imbrique sous le span actif à ce moment-là dans le contexte OTel.

```python lines highlight="1,2,4,5,11,16" theme={"system"}
with weave.start_conversation(agent_name="orchestrator") as conversation:
    with conversation.start_turn(user_message="Compare Anthropic and OpenAI.") as turn:

        with weave.start_subagent(name="research-coordinator") as coordinator:
            with weave.start_subagent(name="anthropic-researcher") as r1:
                with r1.llm(model="gpt-4o", provider_name="openai") as sub_llm:
                    sub_llm.output("Anthropic facts...")
                    sub_llm.usage = Usage(input_tokens=120, output_tokens=30)

                # Imbriqué : l’agent de recherche délègue le travail à son propre sous-agent de synthèse.
                with weave.start_subagent(name="anthropic-summarizer") as summarizer:
                    with summarizer.llm(model="gpt-4o", provider_name="openai") as sub_llm:
                        sub_llm.output("Anthropic summary: ...")
                        sub_llm.usage = Usage(input_tokens=80, output_tokens=20)

            with weave.start_subagent(name="openai-researcher") as r2:
                with r2.llm(model="gpt-4o", provider_name="openai") as sub_llm:
                    sub_llm.output("OpenAI facts...")
                    sub_llm.usage = Usage(input_tokens=120, output_tokens=30)
```

Cet exemple produit trois niveaux d’imbrication sous le tour de conversation :

```plaintext theme={"system"}
turn (invoke_agent)
└── research-coordinator (invoke_agent)
    ├── anthropic-researcher (invoke_agent)
    │   ├── chat
    │   └── anthropic-summarizer (invoke_agent)   ← imbriqué dans anthropic-researcher
    │       └── chat
    └── openai-researcher (invoke_agent)          ← au même niveau qu’anthropic-researcher
        └── chat
```

Dans la vue **Agents**, `research-coordinator` apparaît comme sous-agent du tour de conversation, `anthropic-researcher` et `openai-researcher` apparaissent au même niveau sous le coordinateur, et `anthropic-summarizer` apparaît comme sous-agent de `anthropic-researcher`.