> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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 :**

```typescript
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 :**

```typescript
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 :

```typescript
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 :**

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

**Après :**

```typescript
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.

```typescript
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 :

```typescript
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 :

```typescript
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 :

```typescript
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 :

```typescript
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 :

```typescript
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](https://mastra.zisheng.pro/fr/docs/capabilities/subagents)
- [Réseaux d’Agents](https://mastra.zisheng.pro/fr/docs/agents/networks)
- [Référence Agent.stream()](https://mastra.zisheng.pro/fr/reference/streaming/agents/stream)
- [Référence Agent.generate()](https://mastra.zisheng.pro/fr/reference/agents/generate)
- [Approbation d’Agent](https://mastra.zisheng.pro/fr/docs/agents/agent-approval)
- [Guide : coordinateur de recherche](https://mastra.zisheng.pro/fr/guides/guide/research-coordinator)