Aller au contenu principal

Créer un coordinateur de recherche avec des Agents superviseurs

Dans ce guide, vous créerez un coordinateur de recherche qui orchestre plusieurs Agents spécialisés à l’aide d’Agents superviseurs. Le coordinateur délègue les tâches de recherche à un Agent de recherche et les tâches de rédaction à un Agent de rédaction, puis synthétise les résultats dans un rapport détaillé.

Vous configurerez des sous-agents aux rôles clairement définis et un Agent superviseur pour les coordonner. Vous utiliserez également des hooks de délégation pour contrôler l’exécution et des scorers pour valider l’achèvement des tâches.

Prérequis
Lien direct vers Prérequis

Créer l’Agent de recherche
Lien direct vers Créer l’Agent de recherche

L’Agent de recherche est spécialisé dans la collecte d’informations factuelles sur tout sujet. Il renvoie des résumés concis sous forme de listes à puces contenant les faits essentiels et leurs sources.

Créez un fichier src/mastra/agents/research-agent.ts :

src/mastra/agents/research-agent.ts
import { Agent } from '@mastra/core/agent'

export const researchAgent = new Agent({
  id: 'research-agent',
  name: 'Research Specialist',
  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.',
  instructions:
    'You are a research specialist. When given a topic, gather key facts, ' +
    'statistics, and information. Present findings as clear bullet points. ' +
    'Include sources when possible. Focus on accuracy and completeness.',
  model: 'openai/gpt-5-mini',
})

Le champ description est essentiel : il aide le superviseur à savoir quand déléguer à cet Agent. Des descriptions claires améliorent la précision de la délégation.

Créer l’Agent de rédaction
Lien direct vers Créer l’Agent de rédaction

L’Agent de rédaction transforme la recherche en articles bien structurés, composés de paragraphes complets et fluides.

Créez un fichier src/mastra/agents/writing-agent.ts :

src/mastra/agents/writing-agent.ts
import { Agent } from '@mastra/core/agent'

export const writingAgent = new Agent({
  id: 'writing-agent',
  name: 'Writing Specialist',
  description:
    'Transforms research material into well-structured written content. ' +
    'Produces full paragraphs and complete articles with proper flow. ' +
    'Best used after research has been gathered.',
  instructions:
    'You are a writing specialist. Transform research and information into ' +
    'well-written articles. Use complete paragraphs, clear structure, and ' +
    'engaging language. Maintain a professional yet accessible tone. ' +
    'Ensure the content flows naturally from introduction to conclusion.',
  model: 'openai/gpt-5-mini',
})

Créer l’Agent superviseur
Lien direct vers Créer l’Agent superviseur

Le superviseur coordonne les tâches de recherche et de rédaction. Ses instructions définissent la stratégie de délégation : quand utiliser chaque sous-agent et comment synthétiser les résultats. La mémoire est configurée directement sur l’Agent.

Créez un fichier src/mastra/agents/supervisor-agent.ts :

src/mastra/agents/supervisor-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'

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

Available resources:
- research-agent: Gathers factual data and sources (returns bullet points)
- writing-agent: Transforms research into well-structured articles (returns full paragraphs)

Delegation strategy:
1. For research requests: Delegate to research-agent first to gather facts
2. For writing requests: Delegate to writing-agent with any available research context
3. For comprehensive reports: Delegate to research-agent first, then writing-agent
4. Always ensure you have gathered sufficient information before producing final output

Success criteria:
- All aspects of the user's request are addressed
- Information is accurate and well-sourced
- Final output is well-formatted and complete
- If anything is missing or uncertain, continue gathering information`,
  model: 'openai/gpt-5.6-sol',
  agents: {
    researchAgent,
    writingAgent,
  },
  memory: new Memory({
    storage: new LibSQLStore({
      id: 'mastra-storage',
      url: 'file:mastra.db',
    }),
  }),
  defaultOptions: {
    maxSteps: 10,

    // Monitor progress after each iteration
    onIterationComplete: async context => {
      console.log(`\n✓ Iteration ${context.iteration} complete`)
      console.log(`  Finish reason: ${context.finishReason}`)
      console.log(`  Response length: ${context.text.length} chars\n`)

      // Continue until task is complete
      return { continue: true }
    },

    // Control delegations
    delegation: {
      onDelegationStart: async context => {
        console.log(`→ Delegating to: ${context.primitiveId}`)

        // Add context for specific agents
        if (context.primitiveId === 'research-agent') {
          return {
            proceed: true,
            modifiedPrompt: `${context.prompt}\n\nFocus on recent developments (2024-2025) and include statistics.`,
          }
        }

        return { proceed: true }
      },

      onDelegationComplete: async context => {
        console.log(`✓ Completed: ${context.primitiveId}\n`)

        // Handle errors: bail to stop execution and provide feedback
        if (context.error) {
          console.error('Delegation failed:', context.error)
          context.bail() // Stop further delegations
          return {
            feedback: `Delegation to ${context.primitiveId} failed: ${context.error}. Try a different approach.`,
          }
        }
      },

      // Only pass last 10 messages to subagents
      messageFilter: ({ messages }) => {
        return messages.slice(-10)
      },
    },
  },
})

Enregistrez le superviseur auprès de Mastra dans src/mastra/index.ts :

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { supervisorAgent } from './agents/supervisor-agent'

export const mastra = new Mastra({
  agents: { supervisorAgent },
})

Les defaultOptions de l’Agent superviseur configurent les hooks de délégation et le suivi des itérations :

  • onDelegationStart modifie le prompt de l’Agent de recherche pour demander des données récentes
  • onDelegationComplete consigne la fin de l’opération, s’arrête en cas d’erreur, puis fournit un retour
  • messageFilter limite le contexte aux 10 derniers messages pour gagner en efficacité
  • onIterationComplete surveille la progression après chaque itération

Tester le superviseur de base
Lien direct vers Tester le superviseur de base

Créez un fichier pour interagir avec le superviseur dans src/index.ts :

src/index.ts
import { supervisorAgent } from './mastra/agents/supervisor-agent'

async function main() {
  const topic = 'artificial intelligence in education'
  console.log(`\nTopic: ${topic}\n`)

  const stream = await supervisorAgent.stream(
    `Research ${topic} and write a comprehensive article about it`,
  )

  // Stream the response
  console.log('📝 Final Report:\n')
  for await (const chunk of stream.textStream) {
    process.stdout.write(chunk)
  }
  console.log('\n')
}

main()

Le superviseur utilise les hooks de délégation et le suivi des itérations configurés dans defaultOptions.

Ajouter l’évaluation de l’achèvement des tâches
Lien direct vers Ajouter l’évaluation de l’achèvement des tâches

Les scorers d’achèvement des tâches valident automatiquement que la tâche est terminée. Ils empêchent le superviseur de terminer prématurément.

Créez un scorer dans src/mastra/scorers/task-complete-scorer.ts :

src/mastra/scorers/task-complete-scorer.ts
import { createScorer } from '@mastra/core/evals'

export const taskCompleteScorer = createScorer({
  id: 'task-complete',
  name: 'Task Completeness',
  description: 'Checks if the research and writing task has been fully completed',
}).generateScore(async context => {
  const text = (context.run.output || '').toString()

  // Check if response contains required elements
  const hasSubstantialContent = text.length > 500
  const hasStructure = text.includes('\n\n') // Multiple paragraphs
  const hasContext = /\d{4}/.test(text) // Contains years/dates

  // Return 1 if complete, 0 if not
  if (hasSubstantialContent && hasStructure && hasContext) {
    return 1
  }

  return 0
})

Installez le package d’évaluations :

npm install @mastra/evals

Mettez à jour l’Agent superviseur afin d’inclure l’évaluation de l’achèvement des tâches dans defaultOptions, dans src/mastra/agents/supervisor-agent.ts :

src/mastra/agents/supervisor-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 { taskCompleteScorer } from '../scorers/task-complete-scorer'

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

Available resources:
- research-agent: Gathers factual data and sources (returns bullet points)
- writing-agent: Transforms research into well-structured articles (returns full paragraphs)

Delegation strategy:
1. For research requests: Delegate to research-agent first to gather facts
2. For writing requests: Delegate to writing-agent with any available research context
3. For comprehensive reports: Delegate to research-agent first, then writing-agent
4. Always ensure you have gathered sufficient information before producing final output

Success criteria:
- All aspects of the user's request are addressed
- Information is accurate and well-sourced
- Final output is well-formatted and complete
- If anything is missing or uncertain, continue gathering information`,
  model: 'openai/gpt-5.6-sol',
  agents: {
    researchAgent,
    writingAgent,
  },
  memory: new Memory({
    storage: new LibSQLStore({
      id: 'mastra-storage',
      url: 'file:mastra.db',
    }),
  }),
  defaultOptions: {
    maxSteps: 10,

    onIterationComplete: async context => {
      console.log(`\n✓ Iteration ${context.iteration} complete`)
      console.log(`  Finish reason: ${context.finishReason}`)
      console.log(`  Response length: ${context.text.length} chars\n`)
      return { continue: true }
    },

    delegation: {
      onDelegationStart: async context => {
        console.log(`→ Delegating to: ${context.primitiveId}`)

        if (context.primitiveId === 'research-agent') {
          return {
            proceed: true,
            modifiedPrompt: `${context.prompt}\n\nFocus on recent developments (2024-2025) and include statistics.`,
          }
        }

        return { proceed: true }
      },

      onDelegationComplete: async context => {
        console.log(`✓ Completed: ${context.primitiveId}\n`)

        if (context.error) {
          console.error('Delegation failed:', context.error)
          context.bail() // Stop further delegations
          return {
            feedback: `Delegation to ${context.primitiveId} failed: ${context.error}. Try a different approach.`,
          }
        }
      },

      messageFilter: ({ messages }) => {
        return messages.slice(-10)
      },
    },

    // Validate task completion
    isTaskComplete: {
      scorers: [taskCompleteScorer],
      strategy: 'all',
      onComplete: async result => {
        console.log('\n🎯 Completion Check:')
        console.log(`  Complete: ${result.complete}`)
        console.log(`  Score: ${result.scorers[0]?.score}\n`)
      },
    },
  },
})

Le scorer vérifie la présence d’un contenu substantiel, d’une structure adéquate et d’informations contextuelles. Si la tâche n’est pas terminée, le superviseur continuera les itérations. Tous les hooks et l’évaluation de l’achèvement des tâches sont désormais configurés dans les defaultOptions de l’Agent, ce qui les applique automatiquement à chaque appel.

Tester le coordinateur de recherche
Lien direct vers Tester le coordinateur de recherche

Exécutez le coordinateur pour le voir à l’œuvre :

npx tsx src/index.ts

Vous verrez le superviseur déléguer d’abord à l’Agent de recherche, puis à l’Agent de rédaction, avec des journaux montrant le déroulement de la délégation :

Topic: artificial intelligence in education

→ Delegating to: research-agent
✓ Iteration 1 complete
  Finish reason: tool-calls
  Response length: 0 chars

✓ Completed: research-agent

→ Delegating to: writing-agent
✓ Iteration 2 complete
  Finish reason: tool-calls
  Response length: 0 chars

✓ Completed: writing-agent

🎯 Completion Check:
  Complete: true
  Score: 1

✓ Iteration 3 complete
  Finish reason: stop
  Response length: 1247 chars

📝 Final Report:

Artificial Intelligence in Education: Transforming Learning in 2024-2025

[The coordinator will produce a comprehensive article combining research findings with well-structured writing...]

Comme les réponses des Agents ne sont pas déterministes, votre sortie peut varier, mais le schéma de délégation restera le même.

Étapes suivantes
Lien direct vers Étapes suivantes

Vous pouvez étendre ce coordinateur de recherche pour :

  • Ajouter davantage d’Agents spécialisés (vérificateur des faits, éditeur, formateur de citations)
  • Implémenter des scorers personnalisés pour les métriques de qualité (lisibilité, qualité des sources)
  • Ajouter des Tools de recherche web ou d’accès aux bases de données
  • Créer des Workflows pour les processus de recherche complexes à plusieurs étapes
  • Utiliser une sortie structurée pour générer des rapports dans des formats précis

En savoir plus :

On this page