Réseaux d’Agents

Obsolète

Les réseaux d’Agents sont obsolètes et seront supprimés dans une prochaine version majeure. Les Agents superviseurs qui utilisent agent.stream() ou agent.generate() constituent désormais l’approche recommandée. Ils offrent la même coordination multi-Agent avec un meilleur contrôle, une API plus simple et un débogage facilité.

Consultez le guide de migration pour effectuer la mise à niveau.

Un Agent de routage utilise un LLM pour interpréter une requête et décider quelles primitives (sous-Agents, Workflows ou Tools) appeler, dans quel ordre et avec quelles données.

Créer un réseau d’Agents

Configurez un Agent de routage avec agents, workflows et tools. La Memory est obligatoire, car .network() l’utilise pour stocker l’historique des tâches et déterminer quand une tâche est terminée.

Chaque primitive doit posséder une description claire afin que l’Agent de routage puisse choisir laquelle utiliser. Pour les Workflows et les Tools, inputSchema et outputSchema aident également le routeur à déterminer les entrées appropriées.

src/mastra/agents/routing-agent.ts

import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { LibSQLStore } from '@mastra/libsql'

import { researchAgent } from './research-agent'
import { writingAgent } from './writing-agent'
import { cityWorkflow } from '../workflows/city-workflow'
import { weatherTool } from '../tools/weather-tool'

export const routingAgent = new Agent({
  id: 'routing-agent',
  name: 'Routing Agent',
  instructions: `
    You are a network of writers and researchers. The user will ask you to research a topic. Always respond with a complete report—no bullet points. Write in full paragraphs, like a blog post. Do not answer with incomplete or uncertain information.`,
  model: 'openai/gpt-5.6-sol',
  agents: {
    researchAgent,
    writingAgent,
  },
  workflows: {
    cityWorkflow,
  },
  tools: {
    weatherTool,
  },
  memory: new Memory({
    storage: new LibSQLStore({
      id: 'mastra-storage',
      url: 'file:../mastra.db',
    }),
  }),
})

remarque

Les sous-Agents ont besoin d’une description sur l’instance Agent. Les Workflows et les Tools nécessitent une description, ainsi que inputSchema et outputSchema sur createWorkflow() ou createTool().

Appeler le réseau

Appelez .network() avec un message utilisateur. La méthode renvoie un flux d’événements que vous pouvez parcourir.

const result = await routingAgent.network('Tell me three cool ways to use Mastra')

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

Sortie structurée

Transmettez structuredOutput pour obtenir des résultats typés et validés. Utilisez objectStream afin de recevoir les objets partiels au fil de leur génération.

import { z } from 'zod'

const resultSchema = z.object({
  summary: z.string().describe('A brief summary of the findings'),
  recommendations: z.array(z.string()).describe('List of recommendations'),
  confidence: z.number().min(0).max(1).describe('Confidence score'),
})

const stream = await routingAgent.network('Research AI trends', {
  structuredOutput: { schema: resultSchema },
})

for await (const partial of stream.objectStream) {
  console.log('Building result:', partial)
}

const final = await stream.object
console.log(final?.summary)

Approuver et refuser les appels de Tool

Lorsqu’une primitive requiert une approbation, le flux émet un fragment agent-execution-approval ou tool-execution-approval. Répondez avec approveNetworkToolCall() ou declineNetworkToolCall().

L’approbation du réseau utilise des snapshots pour capturer l’état d’exécution. Vérifiez qu’un Provider de stockage est activé dans votre instance Mastra.

src/approve-network.ts

const stream = await routingAgent.network('Perform some sensitive action', {
  memory: {
    thread: 'user-123',
    resource: 'my-app',
  },
})

for await (const chunk of stream) {
  if (chunk.type === 'agent-execution-approval' || chunk.type === 'tool-execution-approval') {
    // Approve
    const approvedStream = await routingAgent.approveNetworkToolCall(chunk.payload.toolCallId, {
      runId: stream.runId,
      memory: { thread: 'user-123', resource: 'my-app' },
    })

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

Pour refuser l’appel, utilisez plutôt declineNetworkToolCall() avec les mêmes arguments.

Suspendre et reprendre

Lorsqu’une primitive appelle suspend(), le flux émet un fragment de suspension (par exemple, tool-execution-suspended). Utilisez resumeNetwork() pour fournir les données demandées et poursuivre l’exécution.

src/resume-network.ts

const stream = await routingAgent.network('Delete the old records', {
  memory: { thread: 'user-123', resource: 'my-app' },
})

for await (const chunk of stream) {
  if (chunk.type === 'workflow-execution-suspended') {
    console.log(chunk.payload.suspendPayload)
  }
}

// Resume with user confirmation
const resumedStream = await routingAgent.resumeNetwork(
  { confirmed: true },
  {
    runId: stream.runId,
    memory: { thread: 'user-123', resource: 'my-app' },
  },
)

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

Reprise automatique

Définissez autoResumeSuspendedTools sur true afin que le réseau reprenne les primitives suspendues en fonction du message suivant de l’utilisateur. Vous obtenez ainsi un échange conversationnel dans lequel les utilisateurs fournissent naturellement les informations requises.

const stream = await routingAgent.network('Delete the old records', {
  autoResumeSuspendedTools: true,
  memory: { thread: 'user-123', resource: 'my-app' },
})

Conditions requises pour la reprise automatique :

• Memory configurée : l’Agent a besoin de la Memory pour suivre les Tools suspendus entre les messages.
• Même thread : le message de suivi doit utiliser les mêmes identifiants thread et resource.
• resumeSchema défini : le Tool doit définir un resumeSchema afin que le réseau puisse extraire les données du message de l’utilisateur.

	Manuelle (resumeNetwork)	Automatique (autoResumeSuspendedTools)
Idéal pour	Interfaces personnalisées avec boutons d’approbation	Interfaces de type chat
Contrôle	Contrôle complet du moment de la reprise et des données	Le réseau extrait les données du message de l’utilisateur
Configuration	Gérer les fragments de suspension et appeler resumeNetwork	Définir l’option et resumeSchema sur les Tools

Pages connexes

• Agents superviseurs
• Migration de .network() vers les Agents superviseurs