> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# 하위 Agent

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

파일 기반 규칙에 대해서는 이 페이지를 사용하십시오. 더 광범위한 위임 패턴, 후크, Memory 격리, Tool 승인 전파 및 채점에 대해서는 다음을 참조하세요.[Supervisor agents](https://mastra.zisheng.pro/ko/docs/capabilities/subagents).

## 빠른 시작

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

```text
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은 위임 여부를 결정할 때 이를 읽습니다.

```typescript
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 설명](https://mastra.zisheng.pro/ko/reference/file-based-agents/tools)처럼 작성하여 하위 Agent가 하는 일과 위임해야 하는 시점을 설명하세요. 검색된 하위 Agent가 비어 있지 않은 설명을 제공하지 않으면 빌드가 실패합니다.

## 격리

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

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

## 중첩

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

```text
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를 담당합니다.

```text
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
```

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

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

```markdown
You coordinate research and writing.

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

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

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