하위 Agent

추가된 항목: @mastra/core@1.8.0

하위 Agent는 다른 Agent가 작업을 위임할 수 있는 특수 Agent입니다. 상위 Agent에 추가하세요.agents property, then call Agent.stream()또는Agent.generate(). 상위 Agent는 자신의 지침과 각 하위 Agent의description작업을 위임할 시기와 방법을 결정합니다.

하위 Agent를 사용하는 경우

작업에 서로 다른 전문 분야를 가진 Agent가 함께 작업해야 하는 경우 하위 Agent를 사용합니다. 상위 Agent는 위임 시기를 결정하고 컨텍스트를 각 하위 Agent에 전달합니다. 그런 다음 결과를 종합합니다.

일반적인 사용 사례:

• 한 Agent가 데이터를 수집하고 다른 Agent가 콘텐츠를 생성하는 연구 및 작성 Workflow
• 각 단계마다 다른 전문성이 필요한 다단계 업무
• 위임 동작을 세밀하게 제어해야 하는 작업

노트

하위 Agent를 조정하는 상위 Agent를 종종 감독자라고 합니다. 감독자 패턴은 Mastra에서 다중 Agent 시스템을 구축하는 한 가지 접근 방식입니다. 다른 패턴에 대해서는 다음을 읽어보세요.conceptual overview.

빠른 시작

명확한 설명으로 하위 Agent를 정의한 후 상위 Agent에 추가합니다.

src/mastra/agents/parent-agent.ts

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

const researchAgent = new Agent({
  id: 'research-agent',
  description: 'Gathers factual information and returns bullet-point summaries.',
  model: 'openai/gpt-5-mini',
})

const writingAgent = new Agent({
  id: 'writing-agent',
  description: 'Transforms research into well-structured articles.',
  model: 'openai/gpt-5-mini',
})

const parentAgent = new Agent({
  id: 'parent-agent',
  instructions: `You coordinate research and writing using specialized agents.
    Delegate to research-agent for facts, then writing-agent for content.`,
  model: 'openai/gpt-5.6-sol',
  agents: { researchAgent, writingAgent },
  memory: new Memory({
    storage: new LibSQLStore({ id: 'storage', url: 'file:mastra.db' }),
  }),
})

const stream = await parentAgent.stream('Research AI in education and write an article', {
  maxSteps: 10,
})

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

위임 후크

위임 후크를 사용하면 위임이 발생할 때 이를 가로채거나 수정하거나 거부할 수 있습니다. 아래에서 구성하십시오.delegation option, either in the agent's defaultOptions or per-call.

onDelegationStart

상위 Agent가 하위 Agent에 위임하기 전에 호출됩니다. 위임을 제어하기 위한 객체를 반환합니다:

• proceed: true: 위임을 허용합니다(기본 동작).
• proceed: false: 다음을 사용하여 위임을 거부합니다.rejectionReason
• modifiedPrompt: 하위 Agent로 전송된 Prompt를 다시 작성합니다.
• modifiedMaxSteps: 하위 Agent의 반복 횟수를 제한합니다.

src/mastra/agents/parent-agent.ts

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

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

      // Reject delegation after too many iterations
      if (context.iteration > 8) {
        return {
          proceed: false,
          rejectionReason: 'Max iterations reached. Synthesize current findings.',
        }
      }

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

그만큼context object includes:

부동산	설명
primitiveId	The ID of the subagent being delegated to
prompt	The prompt the parent agent is sending
iteration	Current iteration number
requestContext	subagent 실행이 전달받을 요청 컨텍스트

위임 경계에서 컨텍스트 요청

각 위임은 실행 범위 ID 키를 제외하고 상위 실행에서 항목이 얕게 복사된 요청 컨텍스트를 받습니다. 하위 Agent 실행 중에 항목을 설정하거나 삭제해도 상위 컨텍스트에는 영향을 주지 않습니다. 항목 설정context.requestContext in onDelegationStart to pass values to the delegated run:

src/mastra/agents/parent-agent.ts

const stream = await parentAgent.stream('Research AI trends', {
  maxSteps: 10,
  delegation: {
    onDelegationStart: async context => {
      context.requestContext.set('audience', 'technical')
    },
  },
})

하위 Agent는 Tool 및 동적 구성에서 다음과 같은 항목을 읽습니다.instructions: ({ requestContext }) => .... See Request Context 에서 자세한 내용을 확인하세요. 내구성 Agent에서 작동하려면 값이 JSON으로 직렬화 가능해야 합니다.

onDelegationComplete

위임이 완료된 후 호출됩니다. 이를 사용하여 결과를 검사하거나 피드백을 제공하거나 실행을 중지합니다.

• context.bail(): 상위 Agent의 루프를 즉시 중지합니다.
• 반품{ feedback: '...' }: 상위 Agent의 Memory에 저장되고 후속 반복에서 확인할 수 있는 피드백을 추가합니다

src/mastra/agents/parent-agent.ts

const stream = await parentAgent.stream('Research AI trends', {
  maxSteps: 10,
  delegation: {
    onDelegationComplete: async context => {
      console.log(`Completed: ${context.primitiveId}`)

      // Bail on errors
      if (context.error) {
        context.bail()
        return {
          feedback: `Delegation to ${context.primitiveId} failed: ${context.error}. Try a different approach.`,
        }
      }
    },
  },
})

그만큼context object includes:

부동산	설명
primitiveId	The ID of the subagent that ran
result	The subagent's response
error	Error if the delegation failed
bail()	Function to stop the parent agent's loop

메시지 필터링

기본적으로 하위 Agent는 상위 Agent로부터 전체 대화 컨텍스트를 받습니다. 사용messageFilter 를 사용하여 공유할 메시지를 제어할 수 있습니다. 예를 들어 민감한 데이터를 제거하거나 컨텍스트 크기를 제한할 수 있습니다.

src/mastra/agents/parent-agent.ts

const stream = await parentAgent.stream('Research AI trends', {
  maxSteps: 10,
  delegation: {
    messageFilter: ({ messages, primitiveId, prompt }) => {
      // Remove messages containing sensitive data
      return messages
        .filter(msg => {
          const content =
            typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content)
          return !content.includes('confidential')
        })
        .slice(-10) // Only pass the last 10 messages
    },
  },
})

콜백이 수신됩니다.messages (the full conversation history), primitiveId (the subagent ID), and prompt (위임 Prompt)입니다. 필터링된 메시지 배열을 반환합니다.

하위 Agent 결과 컨텍스트

하위 Agent가 완료되면 상위 Agent의 Model은 이후 반복에서 하위 Agent의 텍스트 응답을 받습니다. 중첩된 Tool 호출과 하위 Agent 메타데이터(예: 스레드 및 리소스 ID)는 상위 Agent의 Model 컨텍스트에 추가되지 않습니다.

애플리케이션 코드 및 UI 통합으로 계속 검사할 수 있습니다.subAgentToolResults 및 나머지 원시 위임 결과를 Tool 결과 페이로드에 포함합니다.

이렇게 하면 중첩된 Tool 인수나 출력을 상위 Agent의 다음 Model 호출로 다시 보내지 않고도 디버깅 및 표시 데이터를 계속 사용할 수 있습니다.

세트includeSubAgentToolResultsInModelContext 를 사용하여 중첩된 Tool 결과와 subagent 메타데이터를 포함한 전체 subagent 결과를 상위 Agent의 Model 컨텍스트에 포함합니다.

src/mastra/agents/parent-agent.ts

await parentAgent.generate('Research AI trends', {
  delegation: {
    includeSubAgentToolResultsInModelContext: true,
  },
})

반복 모니터링

onIterationComplete상위 Agent 루프가 반복될 때마다 호출됩니다. 이를 사용하여 실행을 모니터링하거나 다음 반복을 안내합니다. 실행을 일찍 중지할 수도 있습니다.

src/mastra/agents/parent-agent.ts

const stream = await parentAgent.stream('Research AI trends', {
  maxSteps: 10,
  onIterationComplete: async context => {
    console.log(`Iteration ${context.iteration}/${context.maxIterations}`)
    console.log(`Finish reason: ${context.finishReason}`)

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

    // Stop early when the response is sufficient
    if (context.text.length > 1000 && context.finishReason === 'stop') {
      return { continue: false }
    }

    return { continue: true }
  },
})

반품{ continue: true } to keep iterating, or { continue: false } to stop. Include optional feedback to inject guidance into the conversation. When feedback is combined with continue: false인 경우, Model이 피드백을 반영한 텍스트 응답을 생성하도록 마지막 턴을 한 번 더 받을 수 있습니다. 단, 현재 반복이 아직 활성 상태인 경우(예: Tool 호출 후)에만 가능하며, 그렇지 않으면 추가 턴이 제공되지 않습니다.

Memory 격리

Mastra는 위임 중에 하위 Agent Memory를 격리합니다. 하위 Agent는 더 나은 의사 결정을 위해 전체 대화 컨텍스트를 받지만 특정 위임 Prompt와 응답만 Memory에 저장됩니다.

작동 방식:

1. 전체 컨텍스트 전달: 상위 Agent가 위임하면 하위 Agent는 상위 Agent의 대화에서 모든 메시지를 받습니다.
2. 범위 Memory 저장: 위임 Prompt와 하위 Agent의 응답만 하위 Agent의 Memory에 저장됩니다.
3. 호출당 신선한 스레드: 각 위임은 고유한 스레드 ID를 사용하여 깔끔한 분리를 보장합니다.

결과적으로 하위 Agent는 상위 Agent의 전체 대화로 Memory를 복잡하게 만들지 않고도 필요한 컨텍스트를 갖게 됩니다. 방문하다memory in multi-agent systems for more details.

Tool 승인 전파

Tool 승인은 위임 체인을 통해 전파됩니다. 하위 Agent가 다음과 같은 Tool을 사용하는 경우requireApproval: true or calls suspend()인 경우, 승인 요청이 상위 Agent의 스트림에 표시됩니다.

const sensitiveDataTool = createTool({
  id: 'get-user-data',
  requireApproval: true,
  execute: async input => {
    return await database.getUserData(input.userId)
  },
})

const dataAgent = new Agent({
  id: 'data-agent',
  tools: { sensitiveDataTool },
})

const parentAgent = new Agent({
  id: 'parent-agent',
  agents: { dataAgent },
  memory: new Memory(),
})

const stream = await parentAgent.stream('Get data for user 123')

for await (const chunk of stream.fullStream) {
  if (chunk.type === 'tool-call-approval') {
    console.log('Tool requires approval:', chunk.payload.toolName)
  }
}

해제

당신이abortSignal to the parent agent's stream() or generate() 호출 시 Mastra는 동일한 신호를 위임된 subagent에도 전달합니다. AbortController.abort() 를 호출하면 실행 중인 subagent 실행이 완료될 때까지 계속되지 않고 다음 단계에서 취소됩니다.

const controller = new AbortController()

const stream = await parentAgent.stream('Research AI trends', {
  abortSignal: controller.signal,
})

// Cancel the parent agent and any in-flight subagents
controller.abort()

작업 완료 점수

Agent가 첫 번째 시도에서 항상 완전하고 올바른 출력을 생성하는 것은 아닙니다. 작업 완료 채점자는 각 반복 후에 작업이 완료되었는지 확인하여 도움을 줄 수 있습니다. 유효성 검사가 실패하면 상위 Agent는 계속 반복합니다. 실패한 득점자의 피드백이 대화 컨텍스트에 포함되므로 하위 Agent가 누락된 내용을 확인할 수 있습니다.

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 parentAgent.stream('Research AI in education', {
  maxSteps: 10,
  isTaskComplete: {
    scorers: [taskCompleteScorer],
    strategy: 'all',
    onComplete: async result => {
      console.log('Task complete:', result.complete)
    },
  },
})

루브릭 채점자

내장된 루브릭 채점기를 사용하면 "올바른" 것이 무엇인지 체크리스트로 정의하고 Agent가 모든 기준이 충족될 때까지 자체 평가하고 반복하도록 할 수 있습니다.maxSteps is reached.

그것은로 작동합니다LLM-as-judge scorer입니다. 각 반복 후 별도의 grader Model이 rubric에 따라 Agent의 출력을 검토합니다. 모든 필수 기준을 통과하면 루프가 종료됩니다. 기준을 통과하지 못하면 해당 피드백이 대화에 추가되어 Agent가 다시 시도할 수 있습니다.

이는 명확하고 검증 가능한 성공 기준이 있는 작업에 가장 효과적입니다. 다음과 같이 사용할 수 있습니다.

src/mastra/agents/rubric-scorer.ts

import { Agent } from '@mastra/core/agent'
import { createRubricScorer } from '@mastra/evals/scorers/prebuilt'

const parentAgent = new Agent({
  id: 'parent-agent',
  instructions: 'You coordinate research and writing using specialized agents.',
  model: 'openai/gpt-5.6-sol',
  agents: { researchAgent, writingAgent },
})

const rubricScorer = createRubricScorer({
  model: 'openai/gpt-5-mini',
  criteria: [
    { description: 'The response includes an analysis section' },
    { description: 'The response includes concrete recommendations' },
  ],
})

const stream = await parentAgent.stream('Research AI in education', {
  maxSteps: 10,
  isTaskComplete: {
    scorers: [rubricScorer],
    strategy: 'all',
  },
})

전체 API 세부정보는 다음을 참조하세요.rubric scorer reference.

효과적인 지침 작성

효과적인 위임을 위해서는 명확한 지침이 필수적입니다.

모 대리인의instructions 에는 사용 가능한 리소스와 각 리소스를 사용해야 하는 시점을 명시해야 합니다. 또한 조정 방식과 성공 기준도 정의해야 합니다.

각 하위 Agent에는 명확한description 에는 목적과 반환 형식뿐 아니라 상위 Agent가 이를 사용해야 하는 시점도 설명해야 합니다.

상위 Agent는 이러한 설명을 사용하여 위임 결정을 내립니다.

const parentAgent = new Agent({
  id: 'parent-agent',
  instructions: `You coordinate research and writing tasks.

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
3. For complex requests: Delegate to researchAgent first, then writingAgent

Success criteria:
- All user questions are fully answered
- Response is well-formatted and complete`,
  agents: { researchAgent, writingAgent },
})

백그라운드에서 하위 Agent 실행

하위 Agent 호출은 Tool 호출로 전달되므로 다음과 같이 실행할 수 있습니다.background tasks입니다. 하나 이상의 위임 작업이 오래 실행되고 상위 Agent의 응답을 차단하지 않도록 하려는 경우 유용합니다.

활성화backgroundTasks manager 를 Mastra 인스턴스에 설정한 다음 상위 Agent에서 subagent를 사용하도록 옵트인합니다:

src/mastra/agents/parent-agent.ts

const parentAgent = new Agent({
  id: 'parent-agent',
  instructions: 'Coordinate research and writing using the available agents.',
  model: 'openai/gpt-5.6-sol',
  agents: { researchAgent, writingAgent },
  backgroundTasks: {
    tools: {
      researchAgent: { enabled: true, timeoutMs: 900_000 },
      writingAgent: { enabled: true, timeoutMs: 900_000 },
    },
  },
})

const stream = await parentAgent.streamUntilIdle('Research AI in education and write an article', {
  memory: { thread: 't1', resource: 'u1' },
})

사용streamUntilIdle() instead of stream() 를 사용하면 subagent가 완료되고 상위 Agent가 그 결과에 응답할 기회를 얻을 때까지 스트림이 열린 상태로 유지됩니다.

하위 Agent가 상위 Agent 아래에 나열되지 않은 경우backgroundTasks.tools 이지만 자체적으로 백그라운드 실행이 가능한 Tool이 있는 경우, 상위 Agent는 여전히 subagent를 백그라운드 작업으로 디스패치하고 해당 구성을 상속합니다. Inheriting from the subagent for details.

하위 Agent 버전 관리

사용할 때editor을 사용하면 런타임에 상위 Agent가 각 subagent의 저장된 버전 중 어느 것을 사용할지 제어할 수 있습니다. Mastra 인스턴스 또는 호출별로 버전 재정의를 설정하세요:

const result = await parentAgent.generate('Research and write about AI safety', {
  versions: {
    agents: {
      'research-agent': { status: 'published' },
      'writing-agent': { versionId: 'draft-456' },
    },
  },
})

버전 재정의는 위임을 통해 자동으로 전파됩니다. 보다Subagent versioning 에서 결정 순서와 서버 API 사용법에 대한 자세한 내용을 확인하세요.

관련된

• 백그라운드 작업
• 하위 Agent 버전 관리
• 가이드: 연구 코디네이터
• Agent.stream() 참조
• Agent.streamUntilIdle() 참조
• Agent.generate() 참조
• 대리인 승인
• 다중 Agent 시스템의 Memory
• 개념: 다중 Agent 시스템
• 📹 Mastra supervisor agents workshop