> ## 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 d’Agent Lens pour tracer les délégations à des sous-agents et afficher les appels d’agent imbriqués.
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 :
```plaintext theme={"system"}
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**.
```python lines theme={"system"}
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.
```python lines highlight="6,7,10,16,22,30" theme={"system"}
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.
```python lines highlight="1,2,5,11,15,22" theme={"system"}
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à.
```python lines highlight="1,2,4,5,11,16" theme={"system"}
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 :
```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 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`.