Migrer de .network() aux Agents superviseurs

Les Agents superviseurs qui utilisent Agent.stream() et Agent.generate() sont l’approche recommandée pour coordonner plusieurs Agents et remplacent l’ancienne API .network(). Ce guide présente chaque étape de la migration.

Obsolescence de .network()

.network() est obsolète et sera supprimé dans une prochaine version. Le code existant continuera de fonctionner jusque-là, mais le développement se concentre désormais sur les Agents superviseurs. Migrez vers les Agents superviseurs dès que possible.

Remplacer .network() par .stream() ou .generate()

La modification principale consiste à remplacer les appels .network() par .stream(), pour le streaming, ou .generate(), hors streaming. La configuration de l’Agent reste identique. Vous définissez toujours agents, workflows, tools et memory sur l’Agent. La différence réside dans la manière de l’appeler et de traiter les résultats.

Avec .network(), vous itériez sur des types d’événements personnalisés tels que network-execution-event-step-finish. Avec .stream(), vous utilisez les itérateurs standard textStream ou fullStream.

Avant :

const result = await routingAgent.network('Research AI in education')

for await (const chunk of result) {
  if (chunk.type === 'network-execution-event-step-finish') {
    console.log(chunk.payload.result)
  }
}

Après :

const stream = await supervisorAgent.stream('Research AI in education', {
  maxSteps: 10,
})

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk)
}

L’option maxSteps limite le nombre d’itérations que le superviseur peut effectuer. Elle remplace la limite d’itération implicite de .network().

Pour les cas d’utilisation hors streaming, utilisez generate() avec les mêmes options :

const result = await supervisorAgent.generate('Research AI in education', {
  maxSteps: 10,
})

console.log(result.text)

Rédiger des instructions de supervision claires

Avec .network(), l’Agent de routage s’appuyait sur des instructions génériques et des descriptions de primitives pour décider quoi appeler. Les Agents superviseurs fonctionnent de la même manière, mais des instructions claires et précises améliorent l’exactitude de la délégation.

Les instructions de votre superviseur doivent identifier les ressources disponibles et préciser quand utiliser chacune d’elles. Elles doivent également expliquer comment coordonner ces ressources et reconnaître le moment où la tâche est terminée.

Avant :

const routingAgent = new Agent({
  id: 'routing-agent',
  instructions: 'You are a network of researchers and writers...',
  agents: { researchAgent, writingAgent },
  memory: new Memory(),
})

Après :

const supervisorAgent = new Agent({
  id: 'supervisor-agent',
  instructions: `You coordinate research and writing tasks using specialized agents.

Available resources:
- researchAgent: Gathers factual data and sources (returns bullet points)
- writingAgent: Transforms research into narrative content (returns full paragraphs)

Delegation strategy:
1. For research requests: Delegate to researchAgent first
2. For writing requests: Delegate to writingAgent (provide research if available)
3. For complex requests: Delegate to researchAgent first, then writingAgent

Success criteria:
- All user questions are fully answered
- Response is well-formatted and complete
- If information is incomplete, continue iterating`,
  agents: { researchAgent, writingAgent },
  memory: new Memory(),
})

Ajouter des descriptions aux sous-agents

Chaque sous-agent doit avoir un champ description qui explique son objectif et son format de retour. La description doit également indiquer quand utiliser le sous-agent. Le superviseur utilise ces descriptions pour décider à quel Agent déléguer.

const researchAgent = new Agent({
  id: 'research-agent',
  description: `Specializes in gathering factual information and data on any topic.
    Returns concise bullet-point summaries with key facts and sources.
    Does not write full articles or narrative content.`,
})

const writingAgent = new Agent({
  id: 'writing-agent',
  description: `Transforms research material into well-structured written content.
    Produces full paragraphs and complete articles.
    Best used after research has been gathered.`,
})

Mettre à jour la gestion des événements

Si vous gériez des événements .network() spécifiques, mettez-les à jour pour utiliser les types de segments de flux standard :

Événement .network()	Segment d’Agent superviseur
routing-agent-start	step-start
routing-agent-end	step-finish
agent-execution-start	step-start (lors de la délégation)
agent-execution-event-text-delta	text-delta
agent-execution-event-finish	step-finish
network-execution-event-step-finish	step-finish + finishReason: 'stop'
network-object	object-delta (avec structuredOutput)
network-object-result	object (avec structuredOutput)

Ajouter des hooks de délégation

Les Agents superviseurs vous permettent d’utiliser des hooks dans le cycle de vie de délégation pour surveiller, modifier ou rejeter les délégations. Ces hooks peuvent être configurés dans defaultOptions de l’Agent ou transmis par appel.

onDelegationStart est appelé avant que le superviseur délègue à un sous-agent. Vous pouvez modifier le prompt ou limiter les étapes du sous-agent. Le hook peut aussi rejeter entièrement la délégation :

const stream = await supervisorAgent.stream('Research AI in education', {
  maxSteps: 10,
  delegation: {
    onDelegationStart: async context => {
      console.log(`Delegating to: ${context.primitiveId}`)

      if (context.primitiveId === 'research-agent') {
        return {
          proceed: true,
          modifiedPrompt: `${context.prompt}\n\nFocus on 2024-2025 data.`,
          modifiedMaxSteps: 5,
        }
      }

      if (context.iteration > 8) {
        return {
          proceed: false,
          rejectionReason: 'Max iterations reached. Synthesize current findings.',
        }
      }

      return { proceed: true }
    },
  },
})

onDelegationComplete est appelé après la fin d’une délégation. Examinez le résultat et appelez context.bail() lorsque la boucle du superviseur doit s’arrêter. Vous pouvez aussi retourner des retours enregistrés dans la mémoire du superviseur :

const stream = await supervisorAgent.stream('Research AI in education', {
  maxSteps: 10,
  delegation: {
    onDelegationComplete: async context => {
      if (context.error) {
        context.bail() // Stop further delegations
        return {
          feedback: `Delegation to ${context.primitiveId} failed: ${context.error}. Try a different approach.`,
        }
      }
    },
  },
})

Ajouter un filtrage des messages

Par défaut, les sous-agents reçoivent le contexte complet de la conversation depuis le superviseur. Utilisez messageFilter pour contrôler les messages partagés. Par exemple, supprimez les données sensibles ou limitez le nombre de messages :

const stream = await supervisorAgent.stream('Research AI in education', {
  maxSteps: 10,
  delegation: {
    messageFilter: ({ messages, primitiveId, prompt }) => {
      return messages
        .filter(msg => {
          const content =
            typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content)
          return !content.includes('confidential')
        })
        .slice(-10)
    },
  },
})

Ajouter une surveillance des itérations

onIterationComplete est appelé après chaque itération de la boucle du superviseur. Utilisez-le pour consigner la progression ou fournir des retours qui guident l’Agent. Le hook peut également arrêter l’exécution de manière anticipée :

const stream = await supervisorAgent.stream('Research AI in education', {
  maxSteps: 10,
  onIterationComplete: async context => {
    console.log(`Iteration ${context.iteration}/${context.maxIterations}`)

    if (!context.text.includes('recommendations')) {
      return {
        continue: true,
        feedback: 'Please include specific recommendations in your analysis.',
      }
    }

    if (context.text.length > 1000 && context.finishReason === 'stop') {
      return { continue: false }
    }

    return { continue: true }
  },
})

Ajouter une évaluation de l’achèvement des tâches

Les évaluateurs d’achèvement de tâche valident automatiquement si la tâche est terminée. Si la validation échoue, le superviseur poursuit les itérations. Les retours des évaluateurs en échec sont inclus dans le contexte de conversation afin que les sous-agents puissent voir ce qui manquait :

import { createScorer } from '@mastra/core/evals'

const taskCompleteScorer = createScorer({
  id: 'task-complete',
  name: 'Task Completeness',
}).generateScore(async context => {
  const text = (context.run.output || '').toString()
  const hasAnalysis = text.includes('analysis')
  const hasRecommendations = text.includes('recommendation')
  return hasAnalysis && hasRecommendations ? 1 : 0
})

const stream = await supervisorAgent.stream('Research AI in education', {
  maxSteps: 10,
  isTaskComplete: {
    scorers: [taskCompleteScorer],
    strategy: 'all',
    onComplete: async result => {
      console.log('Task complete:', result.complete)
    },
  },
})

Voir aussi

• Agents superviseurs
• Réseaux d’Agents
• Référence Agent.stream()
• Référence Agent.generate()
• Approbation d’Agent
• Guide : coordinateur de recherche