config.ts

대리인의config.tsModel 및 런타임 옵션을 설정합니다. 다음에 속하는 옵션에 사용합니다.Agent형제 파일은 지침, Tool, 기술 등을 제공합니다.

에 속하는 것config.ts

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

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

빠른 시작

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

src/mastra/agents/weather/config.ts

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

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

src/mastra/agents/weather/instructions.md

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을 제공하지 않으면 빌드가 실패합니다. 다른 기능은 형제 파일에서 가져오거나 기본값을 사용합니다.

src/mastra/agents/weather/config.ts

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을 재정의하세요.

src/mastra/agents/weather/config.ts

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

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

런타임 옵션 설정

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

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

인접한 환경이 살고 있는 곳

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

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

상위

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

영역	소스 A	소스 B	우선 적용
지침	동적 config.instructions	instructions.ts 또는 instructions.md	동적 config.instructions
지침	정적 config.instructions	instructions.ts 또는 instructions.md	지침 파일
지침	instructions.ts	instructions.md	instructions.ts
Tool	config.tools	tools/	둘 다 병합되며 키가 충돌하면 config.tools가 우선합니다.
Tool	함수 config.tools	tools/	함수 config.tools가 우선하며 검색된 Tool은 무시됩니다.
Skill	config.skills	skills/	둘 다 병합되며 이름이 충돌하면 config.skills가 우선합니다.
Skill	함수 config.skills	skills/	함수 config.skills가 우선하며 검색된 Skill은 무시됩니다.
Memory	config.memory	memory.ts	config.memory
Workspace	config.workspace	workspace.ts	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로 실행됩니다. Agent API, Studio, Workflow 또는 애플리케이션 코드에서 호출하면 코드로 정의한 Agent와 동일한 런타임을 사용합니다. 발견은 소스 기반이며 보수적입니다.

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

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

npm

npx mastra dev

pnpm

pnpm dlx mastra dev

Yarn

yarn dlx mastra dev

Bun

bun x mastra dev

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