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

# config.ts

대리인의`config.ts`Model 및 런타임 옵션을 설정합니다. 다음에 속하는 옵션에 사용합니다.[`Agent`](https://mastra.zisheng.pro/ko/reference/agents/agent)형제 파일은 지침, Tool, 기술 등을 제공합니다.

## 에 속하는 것`config.ts`

`config.ts`파일 기반 Agent의 Model 및 런타임 옵션에 대한 필수 진입점입니다. Model, 설명, 기본 실행 옵션, 재시도 동작, 채점자, 표시 ID 등 자체 파일이 필요하지 않은 경우 Agent 수준 설정을 여기에 입력하세요.

파일 기반 라우팅을 통해 형제 파일을 Agent에 병합하려면 관련 항목을 서로 인접한 형제 파일로 유지하세요. 예를 들어 상시 Prompt에는 `instructions.md`, Model이 호출할 수 있는 작업에는 `tools/`를 사용합니다.

## 빠른 시작

다음 `config.ts`와 `instructions.md` 파일로 작동하는 파일 기반 Agent를 만들 수 있습니다.

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

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

```markdown
You are a helpful weather assistant. Answer questions about current conditions and forecasts.
```

Mastra는 `weather` 디렉터리 이름을 기본 Agent `id` 및 `name`으로 사용합니다. 형제 `instructions.md`가 필수 지침을 제공합니다.

## Model 설정

`model` 필드는 `agentConfig()`에서 유일한 필수 필드입니다. Agent 디렉터리에서 Model을 제공하지 않으면 빌드가 실패합니다. 다른 기능은 형제 파일에서 가져오거나 기본값을 사용합니다.

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

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

## 디렉토리의 신원

파일 기반 Agent의 `id`와 `name`은 기본적으로 디렉터리 이름입니다. 해당 필드를 재정의하지 않으면 Mastra는 `src/mastra/agents/weather/`의 Agent를 `weather`로 등록합니다. 안정적인 라우팅 키와 표시 이름이 달라야 하면 `id` 또는 `name`을 재정의하세요.

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

export default agentConfig({
  id: 'weather-assistant',
  name: 'Weather Assistant',
  model: 'openai/gpt-5.6-sol',
})
```

## 런타임 옵션 설정

`agentConfig()`는 [`Agent` 생성자 옵션](https://mastra.zisheng.pro/ko/reference/agents/agent)을 허용하지만, `id`, `name` 및 형제 파일 필드는 파일 기반 규칙으로 제공할 수 있습니다. 전체 옵션 목록은 Agent 참조를 확인하세요. 참고:

- 파일 기반 하위 Agent에는 비어 있지 않은 `description`이 필요합니다. 상위 Model이 이를 위임 라우팅에 사용하기 때문입니다.
- 별도 파일이 필요하지 않은 `defaultOptions`, `maxRetries`, `scorers` 및 기타 Agent 옵션은 `config.ts`에 둘 수 있습니다.

## 인접한 환경이 살고 있는 곳

`config.ts`는 런타임 옵션에 집중하세요. 별도 위치에서 관리하는 편이 좋은 항목에는 형제 파일을 사용하세요.

| 설정        | 파일 또는 폴더                                                                                                         | 해당 위치를 사용하는 이유                                             |
| --------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| 지침        | [`instructions.md` 또는 `instructions.ts`](https://mastra.zisheng.pro/ko/reference/file-based-agents/instructions) | 상시 Prompt를 Markdown으로 읽기 쉽게 유지하거나 TypeScript에서 동적으로 생성합니다. |
| Tools     | [`tools/`](https://mastra.zisheng.pro/ko/reference/file-based-agents/tools)                                      | 호출 가능한 각 작업에 자체 타입 지정 모듈을 제공합니다.                           |
| Skills    | [`skills/`](https://mastra.zisheng.pro/ko/reference/file-based-agents/skills)                                    | 필요할 때 로드하는 절차를 상시 지침과 분리합니다.                               |
| Memory    | [`memory.ts`](https://mastra.zisheng.pro/ko/reference/file-based-agents/memory)                                  | 런타임 옵션을 복잡하게 만들지 않고 영구 Memory를 구성합니다.                      |
| Workspace | [`workspace.ts`](https://mastra.zisheng.pro/ko/reference/file-based-agents/workspace)                            | 파일 및 Sandbox 동작을 Model 설정과 별도로 구성합니다.                      |
| 프로세서      | [`processors/`](https://mastra.zisheng.pro/ko/reference/file-based-agents/processors)                            | 입력 및 출력 처리 파이프라인을 분리합니다.                                   |
| 하위 Agent  | [`subagents/`](https://mastra.zisheng.pro/ko/reference/file-based-agents/subagents)                              | 전문화된 각 하위 Agent에 자체 디렉터리를 제공합니다.                           |

## 상위

`config.ts`다음 규칙에 따라 Agent의 다른 파일과 병합됩니다.

| 영역                                                                                                                                       | 소스 A                                                                                        | 소스 B                                                                                                             | 우선 적용                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| 지침                                                                                                                                       | 동적 `config.instructions`                                                                    | [`instructions.ts` 또는 `instructions.md`](https://mastra.zisheng.pro/ko/reference/file-based-agents/instructions) | 동적 `config.instructions`                   |
| 지침                                                                                                                                       | 정적 `config.instructions`                                                                    | [`instructions.ts` 또는 `instructions.md`](https://mastra.zisheng.pro/ko/reference/file-based-agents/instructions) | 지침 파일                                      |
| 지침                                                                                                                                       | [`instructions.ts`](https://mastra.zisheng.pro/ko/reference/file-based-agents/instructions) | [`instructions.md`](https://mastra.zisheng.pro/ko/reference/file-based-agents/instructions)                      | `instructions.ts`                          |
| Tool                                                                                                                                     | `config.tools`                                                                              | [`tools/`](https://mastra.zisheng.pro/ko/reference/file-based-agents/tools)                                      | 둘 다 병합되며 키가 충돌하면 `config.tools`가 우선합니다.    |
| Tool                                                                                                                                     | 함수 `config.tools`                                                                           | [`tools/`](https://mastra.zisheng.pro/ko/reference/file-based-agents/tools)                                      | 함수 `config.tools`가 우선하며 검색된 Tool은 무시됩니다.   |
| Skill                                                                                                                                    | `config.skills`                                                                             | [`skills/`](https://mastra.zisheng.pro/ko/reference/file-based-agents/skills)                                    | 둘 다 병합되며 이름이 충돌하면 `config.skills`가 우선합니다.  |
| Skill                                                                                                                                    | 함수 `config.skills`                                                                          | [`skills/`](https://mastra.zisheng.pro/ko/reference/file-based-agents/skills)                                    | 함수 `config.skills`가 우선하며 검색된 Skill은 무시됩니다. |
| Memory                                                                                                                                   | `config.memory`                                                                             | [`memory.ts`](https://mastra.zisheng.pro/ko/reference/file-based-agents/memory)                                  | `config.memory`                            |
| Workspace                                                                                                                                | `config.workspace`                                                                          | [`workspace.ts`](https://mastra.zisheng.pro/ko/reference/file-based-agents/workspace)                            | `config.workspace`                         |
| `instructions.md`, `instructions.ts`, `config.instructions`가 모두 없으면 빌드가 실패합니다. `config.memory`와 `memory.ts`가 모두 없으면 Agent에 Memory가 없습니다. |                                                                                             |                                                                                                                  |                                            |

## 검색 수명 주기

파일 기반 프리미티브는 `mastra dev` 및 `mastra build` 실행 시 Mastra 번들러가 검색합니다. 검색 과정에서 Mastra는 `src/mastra/` 아래의 지원되는 파일을 확인하고, TypeScript 및 JavaScript 모듈을 가져오며, Markdown 지침과 Skill을 읽고, Workspace 시드 파일을 복사한 다음, 조립된 프리미티브를 Mastra 앱에 등록합니다. 검색된 파일 기반 Agent는 일반 [`Agent`](https://mastra.zisheng.pro/ko/reference/agents/agent)로 실행됩니다. Agent API, Studio, Workflow 또는 애플리케이션 코드에서 호출하면 코드로 정의한 Agent와 동일한 런타임을 사용합니다. 발견은 소스 기반이며 보수적입니다.

심볼릭 링크, 테스트 파일 및 Agent 디렉터리가 아닌 디렉터리를 건너뜁니다. Workflow 및 싱글톤 프로젝트 파일은 기본 내보내기가 있는 경우에만 파일 라우팅됩니다.

검색이 실행되도록 Mastra CLI를 통해 앱을 시작하세요.

**npm**:

```bash
npx mastra dev
```

**pnpm**:

```bash
pnpm dlx mastra dev
```

**Yarn**:

```bash
yarn dlx mastra dev
```

**Bun**:

```bash
bun x mastra dev
```

`mastra` 인스턴스를 직접 가져오면 `agents/<name>/` 디렉터리 및 기타 규칙이 검색되지 않습니다. Mastra를 라이브러리로 사용할 때는 해당 프리미티브를 코드에서 등록하세요.