지침

Agent의 지시 사항에는 항상 켜져 있는 시스템 Prompt가 포함되어 있습니다. Model은 매 턴마다 이를 읽습니다. 이를 사용하여 Agent의 신원, 어조, 역할 및 입장 규칙을 정의합니다.

Agent 루트에 있는 두 파일 중 하나에 지침을 작성합니다. Prompt가 고정 텍스트이면 instructions.md를 사용하세요. 공유 상수로 빌드하거나 요청에 따라 결정하는 등 Prompt에 코드가 필요하면 instructions.ts를 사용하세요. 지침은 항상 컨텍스트에 포함되므로 모든 요청에 적용되는 안정적인 동작만 담으세요. 조건부이거나 규모가 크거나 작업 중심인 항목은 tools/ 또는 skills/로 옮기세요. Model은 관련이 있을 때만 이를 사용합니다.

빠른 시작

Agent 루트에 instructions.md를 추가하세요. 작성한 내용이 그대로 Prompt가 되므로 가장 짧은 형태는 한 문장입니다.

src/mastra/agents/weather/instructions.md

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

지침에 들어가는 내용

효과적인 지침은 요청 간에 변경되지 않는 Agent 동작의 일부를 다룹니다.

• 역할과 정체성
• 톤과 스타일
• 상임 규칙
• 출력 형식

조건부이거나 규모가 크거나 작업 중심인 지침은 tools/ 또는 skills/로 옮기세요. Model은 관련이 있을 때만 이를 사용합니다.

TypeScript의 지침

Markdown으로 Prompt를 표현할 수 없으면 instructions.ts를 사용하세요. 이 파일은 문자열, 시스템 메시지 또는 이를 반환하는 함수를 기본 내보내기하며, agentInstructions()는 내보내기를 변경하지 않고 타입을 지정합니다. 예를 들어 앱의 나머지 부분과 공유되는 상수에서 Prompt가 코드로 조합되면 문자열을 내보냅니다.

src/mastra/agents/weather/instructions.ts

import { agentInstructions } from '@mastra/core/agent'
import { SUPPORTED_UNITS } from '../../constants'

export default agentInstructions(`
You are a helpful weather assistant.
Report conditions using one of these units: ${SUPPORTED_UNITS.join(', ')}.
`)

Prompt가 요청에 따라 달라지면 함수를 내보냅니다. Mastra는 매 턴마다 이를 호출하고 요청 컨텍스트를 전달합니다.

src/mastra/agents/support/instructions.ts

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

export default agentInstructions(({ requestContext }) => {
  const tier = requestContext.get('tier') ?? 'standard'
  return `You are a support agent. Treat this as a ${tier}-tier customer.`
})

함수는 async일 수 있으며 requestContext와 함께 mastra를 받으므로, Prompt를 반환하기 전에 스토리지나 등록된 다른 프리미티브에서 데이터를 읽을 수 있습니다. 두 파일 모두 동일한 규칙을 따르는 하위 Agent 디렉터리에서도 작동합니다.

빌드 타임 동작

instructions.md와 instructions.ts는 서로 다른 방식으로 배포된 Agent에 반영됩니다.

• instructions.md: Mastra는 파일을 읽고 빌드 시 생성된 코드에 해당 내용을 인라인합니다.
• instructions.ts: 생성된 코드는 모듈을 가져오므로 다른 TypeScript 파일처럼 번들로 제공되며 프로젝트의 나머지 부분에서 가져올 수 있습니다.

mastra dev에서는 두 파일 중 하나를 편집하면 다시 빌드됩니다. 배포된 앱에서는 런타임에 어느 파일도 디스크에서 읽지 않으므로 변경 사항은 다음 빌드 후 적용됩니다.

구성 우선순위

지침은 instructions.ts, instructions.md 또는 config.ts의 instructions 필드에서 가져올 수 있습니다.

• config.ts에서 런타임에 정의한 함수형 instructions가 두 파일보다 우선합니다.
• 그렇지 않으면 instructions.ts가 instructions.md보다 우선합니다.
• instructions.md가 config.ts의 정적 instructions 문자열보다 우선합니다.
• 아무것도 없으면 Agent 디렉터리 이름을 명시한 오류와 함께 빌드가 실패합니다. 여러 곳에서 지침을 정의하면 두 소스의 이름과 어느 소스가 승리하는지에 대한 경고가 기록됩니다. Agent당 하나의 소스를 유지하세요.