감독 Agent와 함께 연구 코디네이터 구축

이 가이드에서는 감독 Agent를 사용하여 여러 전문 Agent를 조율하는 연구 코디네이터를 구축합니다. 코디네이터는 연구 업무를 연구 대리인에게, 집필 업무를 저술 대리인에게 위임한 후, 그 결과를 종합하여 상세한 보고서를 작성합니다.

명확한 역할을 가진 하위 Agent를 설정하고 감독 Agent를 구성하여 이를 조정합니다. 또한 위임 후크를 사용하여 실행을 제어하고 채점자를 사용하여 작업 완료를 검증합니다.

전제조건

• Node.js v22.13.0 이상 설치
• 지원되는 Model Provider의 API 키
• 기존 Mastra 프로젝트(새 프로젝트를 설정하려면 설치 가이드를 따르세요)

연구 Agent 만들기

연구 대리인은 모든 주제에 대한 사실 정보 수집을 전문으로 합니다. 주요 사실과 출처가 포함된 간결한 요점 요약을 반환합니다.

새 파일 만들기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',
})

description 필드는 매우 중요합니다. 감독자가 언제 이 Agent에 위임해야 하는지 이해하는 데 도움이 됩니다. 명확한 설명은 위임 정확도를 높입니다.

쓰기 Agent 만들기

글쓰기 Agent는 연구 결과를 완전한 단락과 적절한 흐름을 갖춘 잘 구조화된 기사로 변환합니다.

새 파일 만들기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',
})

감독자 Agent 만들기

감독자는 연구 및 작문 작업을 조정합니다. 해당 지침은 위임 전략, 즉 각 하위 Agent를 사용할 시기와 결과를 종합하는 방법을 정의합니다. Memory는 Agent에서 직접 구성됩니다.

새 파일 만들기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)
      },
    },
  },
})

Mastra에 감독자를 등록합니다.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 },
})

감독자 Agent의 defaultOptions는 위임 훅과 반복 모니터링을 구성합니다.

• onDelegationStart최근 데이터를 요청하도록 연구 대리인의 Prompt를 수정합니다.
• onDelegationComplete완료를 기록하고 오류가 발생하면 중지한 다음 피드백을 제공합니다.
• messageFilter효율성을 위해 컨텍스트를 마지막 10개 메시지로 제한합니다.
• onIterationComplete각 반복 후 진행 상황을 모니터링합니다.

기본 감독자 테스트

감독자와 상호 작용할 파일을 만듭니다.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()

감독자는 다음에 구성된 위임 후크 및 반복 모니터링을 사용합니다.defaultOptions.

작업 완료 점수 추가

작업 완료 채점자는 작업이 완료되었는지 자동으로 확인합니다. 이는 감독자가 조기에 끝내는 것을 방지합니다.

득점원 생성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
})

평가 패키지를 설치합니다:

npm

npm install @mastra/evals

pnpm

pnpm add @mastra/evals

Yarn

yarn add @mastra/evals

Bun

bun add @mastra/evals

src/mastra/agents/supervisor-agent.ts의 defaultOptions에 작업 완료 채점기를 포함하도록 감독자 Agent를 업데이트하세요.

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`)
      },
    },
  },
})

채점기는 실질적인 내용, 적절한 구조, 컨텍스트 정보를 확인합니다. 작업이 완료되지 않으면 감독자가 계속 반복합니다. 이제 모든 훅과 작업 완료 점수가 Agent의 defaultOptions에 포함되어 모든 호출에 자동으로 적용됩니다.

연구 코디네이터 테스트

코디네이터를 실행하여 실제로 작동하는 모습을 확인하세요.

npx tsx src/index.ts

위임 흐름을 보여주는 로그와 함께 감독자가 먼저 연구 Agent에 위임한 다음 쓰기 Agent에 위임하는 것을 볼 수 있습니다.

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...]

Agent 응답은 비결정적이므로 출력은 다양할 수 있지만 위임 패턴은 동일합니다.

다음 단계

이 연구 코디네이터를 다음으로 확장할 수 있습니다.

• 더 많은 전문 Agent 추가(사실 확인기, 편집자, 인용 형식 지정자)
• 품질 지표(가독성, 소스 품질)에 대한 사용자 정의 채점자 구현
• 웹 검색 또는 데이터베이스 액세스를 위한 Tool 추가
• 복잡한 다단계 연구 프로세스를 위한 Workflow 생성
• 구조화된 출력을 사용하여 특정 형식의 보고서 생성

자세히 알아보기:

• 감독자 Agent
• Agent.stream() 참조