Tracer les sous-agents - CoreWeave Docs

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.

Modèle de données des sous-agents

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 :

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.

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.

Tracer un seul sous-agent

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.

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.

Tracer plusieurs sous-agents

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.

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.

Tracer des sous-agents imbriqués

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.

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 :

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.

​Modèle de données des sous-agents

​Tracer un seul sous-agent

​Tracer plusieurs sous-agents

​Tracer des sous-agents imbriqués

Modèle de données des sous-agents

Tracer un seul sous-agent

Tracer plusieurs sous-agents

Tracer des sous-agents imbriqués