Tracer les sous-agents - CoreWeave Docs

Ce guide explique comment utiliser CoreWeave Agent Lens 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 Agent Lens. 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é. Lorsqu’ils sont instrumentés avec Agent Lens, les sous-agents émettent un span OpenTelemetry (OTel) invoke_agent imbriqué dans la même trace que le tour de conversation parent. Dans l’onglet Conversations, 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 Agent Lens représente les sous-agents dans une trace. Le span tracing.start_subagent correspond au span OTel invoke_agent et émet le même nom d’opération que le tour de conversation parent. Agent Lens les distingue par leur relation parent-enfant dans la trace :

Tour de conversation (span invoke_agent 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 élabore la réponse finale

Les sous-agents héritent du conversation_id de la conversation active et sont donc regroupés avec le reste de la conversation dans l’onglet Conversations.

sub = tracing.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.
)

tracing.start_subagent crée un span invoke_agent qui devient automatiquement l’enfant du span actif dans le contexte OTel, généralement le tour de conversation parent ou l’appel LLM qui a déclenché 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. Agent Lens capture la hiérarchie complète en encapsulant la conversation dans tracing.start_conversation, puis dans un conversation.start_turn. Agent Lens capture ensuite la trace du sous-agent à l’aide du bloc tracing.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 agents.

from coreweave.forge.agentlens import tracing
from coreweave.forge.agentlens.tracing import Message, Usage

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

with tracing.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 tracing.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 tracing.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 tracing.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 tracing.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 l’onglet Conversations, 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 une première version de l’article et un reviewer qui peaufine le résultat final. Agent Lens capture les trois sous-agents au même niveau, sous le même tour de conversation, en ouvrant un bloc tracing.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 tracing.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 : rassembler les faits.
        with tracing.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 tracing.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 tracing.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 tracing.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 l’onglet Conversations, le tour de conversation contient trois appels de sous-agents au même niveau, chacun avec son propre appel LLM imbriqué en dessous, et le researcher comprend 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 dans le contexte OTel à ce moment-là.

with tracing.start_conversation(agent_name="orchestrator") as conversation:
    with conversation.start_turn(user_message="Compare Anthropic and OpenAI.") as turn:

        with tracing.start_subagent(name="research-coordinator") as coordinator:
            with tracing.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)

                # Imbrication : l’agent de recherche délègue à son propre sous-agent de synthèse.
                with tracing.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 tracing.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 génère 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 l’onglet Conversations, research-coordinator s’affiche comme sous-agent du tour de conversation, anthropic-researcher et openai-researcher s’affichent au même niveau sous le coordinateur, et anthropic-summarizer s’affiche comme sous-agent d’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