하위 Agent

파일 기반 Agent는 다음을 선언할 수 있습니다.subagents, 전문 아동 대리인에게 위임합니다. 상위 Model은 각 하위 Agent를 하위 Agent 디렉터리 이름을 딴 위임 Tool로 보고 해당 Tool을 호출하여 작업을 전달합니다. 하위 Agent의 결과는 상위 대화로 반환됩니다.

파일 기반 규칙에 대해서는 이 페이지를 사용하십시오. 더 광범위한 위임 패턴, 후크, Memory 격리, Tool 승인 전파 및 채점에 대해서는 다음을 참조하세요.Supervisor agents.

빠른 시작

하위 Agent당 하나의 디렉터리를 선언합니다.subagents/:

Subagent layout

src/mastra/agents/
└── supervisor/
    ├── config.ts
    ├── instructions.md
    └── subagents/
        └── researcher/
            ├── config.ts
            ├── instructions.md
            └── tools/
                └── search.ts

Mastra는 researcher를 독립 Agent로 조립하고 감독자의 agents 맵에 연결합니다. 상위 Model은 생성된 researcher 위임 Tool을 사용하여 해당 Agent에 위임할 수 있습니다. 하위 Agent의 config.ts에는 비어 있지 않은 description을 설정해야 합니다. 상위 Model은 위임 여부를 결정할 때 이를 읽습니다.

src/mastra/agents/supervisor/subagents/researcher/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
  description: 'Researches a topic and returns cited findings.',
})

Model이 위임하는 방법

하위 Agent의 description은 상위 Model을 위한 라우팅 텍스트입니다. Tool 설명처럼 작성하여 하위 Agent가 하는 일과 위임해야 하는 시점을 설명하세요. 검색된 하위 Agent가 비어 있지 않은 설명을 제공하지 않으면 빌드가 실패합니다.

격리

하위 Agent는 격리됩니다. 하위 Agent는 상위 Agent의 Tool, 기술, 작업 영역, Memory, 프로세서 또는 하위 Agent를 상속하지 않습니다. 각 하위 항목은 자체 디렉토리가 있는 독립형 Agent입니다.

여러 Agent가 동일한 종속성을 공유해야 하는 경우 이를 코드에서 정의하고 각 Agent의 구성을 통해 할당하세요.

중첩

하위 Agent는 자체 subagents/ 디렉터리를 선언할 수 있으며 최상위 Agent 아래에서 최대 3개 수준까지 중첩할 수 있습니다. 그보다 깊게 중첩된 subagents/ 디렉터리는 경고와 함께 무시됩니다.

Nested subagents

src/mastra/agents/
└── supervisor/            # depth 0
    └── subagents/
        └── researcher/    # depth 1
            └── subagents/
                └── summarizer/ # depth 2

명명 규칙

• 상위 Tool 키 중 하나와 충돌하는 하위 Agent ID는 빌드 오류를 일으킵니다.
• 동일한 상위 Agent 아래에서 중복된 하위 Agent ID는 빌드 오류를 일으킵니다.
• 하위 Agent ID가 상위 Agent의 config.agents에도 있으면 config.agents 항목이 우선하며 경고가 기록됩니다.
• config.agents가 함수이면 정적으로 병합할 수 없으므로 검색된 하위 Agent가 경고와 함께 무시됩니다.

예

이 감독자는 조사 및 작성 흐름을 조정합니다. researcher 하위 Agent는 검색 Tool을 담당하고, writer 하위 Agent는 초안 파일을 작성할 Workspace를 담당합니다.

Research supervisor

src/mastra/agents/
└── research-supervisor/
    ├── config.ts
    ├── instructions.md
    └── subagents/
        ├── researcher/
        │   ├── config.ts
        │   ├── instructions.md
        │   └── tools/
        │       └── search_web.ts
        └── writer/
            ├── config.ts
            ├── instructions.md
            └── workspace/
                └── draft-template.md

src/mastra/agents/research-supervisor/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
})

src/mastra/agents/research-supervisor/instructions.md

You coordinate research and writing.

Delegate fact gathering to `researcher`. Delegate final drafting to `writer`.

src/mastra/agents/research-supervisor/subagents/researcher/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5-mini',
  description: 'Use to gather facts, sources, and concise research notes for a topic.',
})

src/mastra/agents/research-supervisor/subagents/writer/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
  description: 'Use to turn research notes into a structured draft.',
})