Agent 기술

기술은 Agent에게 특정 작업을 수행하는 방법을 가르치는 재사용 가능한 지침입니다. 그들은 다음을 따릅니다.Agent Skills specification.

skills 구성을 통해 Skill을 Agent에 직접 연결하거나 Workspace에 구성할 수 있습니다. Skill이 특정 Agent에 속하고 Workspace가 필요하지 않은 코드에서 Skill을 정의하려면 Agent에 연결하세요. 파일 시스템에서 Skill을 검색하고 이를 사용하는 모든 Agent에서 공유하려면 Workspace를 사용하세요. 이 페이지에서는 코드로 Skill을 정의하고, 파일에서 불러오고, 요청별로 해석하는 Agent 수준 접근 방식을 다룹니다.

Agent 수준 기술을 사용해야 하는 경우

다음과 같은 경우 Agent 수준 기술을 사용하세요.

• 작업 영역에 의존하지 않는 독립형 Agent를 원합니다.
• 기술은 코드에 정의되어 있으며 파일 시스템 검색이 필요하지 않습니다.
• Agent 기능이 포함된 패키지 또는 라이브러리를 구축 중입니다.
• 상황에 따라 요청별 기술 해결이 필요합니다.

프로젝트 전체에서 파일 시스템 기반 기술을 검색하려면 다음을 사용하세요.workspace skills instead.

빠른 시작

스킬 인라인을 정의하고 이를 Agent에 연결합니다.

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { createSkill } from '@mastra/core/skills'

const codeReview = createSkill({
  name: 'code-review',
  description: 'Use when reviewing code changes.',
  instructions: `
    When reviewing code:
    1. Check for correctness and edge cases
    2. Verify style consistency
    3. Look for potential bugs
  `,
})

export const reviewer = new Agent({
  id: 'reviewer',
  model: 'openai/gpt-5.6-sol',
  instructions: 'You are a code review assistant.',
  skills: [codeReview],
})

Agent에는 대화 중 Skill을 검색하고 불러올 수 있도록 skill, skill_read, skill_search Tool이 자동으로 제공됩니다.

인라인 기술 정의

Skill 전체를 코드로 생성하려면 createSkill()을 사용하세요.

src/mastra/skills.ts

import { createSkill } from '@mastra/core/skills'

export const releaseChecklist = createSkill({
  name: 'release-checklist',
  description: 'Use when preparing a release.',
  instructions: `
    ## Release Checklist
    1. Run the full test suite
    2. Update CHANGELOG.md
    3. Bump version numbers
    4. Create a git tag
  `,
  references: {
    'changelog-format.md': '# Changelog Format\nUse Keep a Changelog...',
  },
})

references 필드는 파일 시스템 Skill의 references/ 파일처럼 Agent가 skill_read Tool로 읽을 수 있는 지원 문서를 묶습니다. 전체 API는 createSkill() 레퍼런스를 참조하세요.

파일 시스템 경로 기술

작업 영역 없이 디스크의 스킬 디렉터리를 가리킵니다.

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { createSkill } from '@mastra/core/skills'

export const agent = new Agent({
  id: 'my-agent',
  model: 'openai/gpt-5.6-sol',
  skills: [
    './skills/code-review', // path to a SKILL.md directory
    './skills/testing', // another filesystem skill
    createSkill({/* ... */}), // inline skill
  ],
})

파일 시스템 경로는 내부적으로 LocalSkillSource를 사용하며, Workspace Skill과 동일한 형식의 SKILL.md 파일을 읽습니다.

다이나믹한 스킬

요청별 기술 해결을 위해 다음 함수를 전달합니다.

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { createSkill } from '@mastra/core/skills'

const devSkill = createSkill({
  name: 'dev-tools',
  description: 'Developer productivity tools.',
  instructions: '...',
})

const supportSkill = createSkill({
  name: 'support-guide',
  description: 'Customer support guidelines.',
  instructions: '...',
})

export const agent = new Agent({
  id: 'dynamic-agent',
  model: 'openai/gpt-5.6-sol',
  skills: ({ requestContext }) => {
    const role = requestContext.get('userRole')
    if (role === 'developer') return [devSkill]
    return [supportSkill]
  },
})

리졸버 함수는 { requestContext, tracingContext }를 받아 SkillInput[] 배열 또는 Promise<SkillInput[]>을 반환합니다. 리졸버는 RequestContext마다 한 번 실행됩니다. Agent 실행 중에는 resolve-skills 범위 안에서 실행되며, Tool과 마찬가지로 tracingContext.currentSpan을 사용해 자체 작업을 위한 하위 범위를 만들 수 있습니다. 또한 리졸버는 agent.listSkills() 및 서버의 Agent 엔드포인트와 같은 메타데이터 읽기 작업에서도 실행됩니다. 이때는 범위가 존재하지 않아 tracingContext.currentSpan이 undefined이므로 빠르게 실행되도록 유지하고 범위 사용을 방어적으로 처리하세요.

src/mastra/agents/index.ts

skills: async ({ requestContext, tracingContext }) => {
  const span = tracingContext?.currentSpan?.createChildSpan({
    type: 'generic',
    name: 'entitlements-lookup',
  })
  const skills = await fetchSkillsFor(requestContext.get('userId'))
  span?.end()
  return skills
}

Agent 및 Workflow에서 요청 컨텍스트를 사용하는 방법에 관한 자세한 내용은 요청 컨텍스트를 참조하세요.

작업 공간 기술과 병합

Agent에 skills와 Skill이 구성된 Workspace가 모두 있으면 두 항목이 병합됩니다. 이름이 충돌할 때는 Agent 수준 Skill이 우선합니다.

src/mastra/agents/index.ts

import { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
import { createSkill } from '@mastra/core/skills'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['skills'], // provides "code-review" skill
})

const customReview = createSkill({
  name: 'code-review', // same name as workspace skill
  description: 'Custom review process.',
  instructions: '...',
})

export const reviewer = new Agent({
  id: 'reviewer',
  model: 'openai/gpt-5.6-sol',
  workspace,
  skills: [customReview], // agent-level "code-review" wins
})

프로그래밍 방식 기술 액세스

애플리케이션 코드(예: Workflow 또는 API 경로)에서 Skill에 접근하려면 agent.getSkill() 및 agent.listSkills()를 사용하세요.

src/routes/skills.ts

import { reviewer } from '../mastra/agents'

// Get a specific skill by name
const skill = await reviewer.getSkill('code-review')
if (skill) {
  console.log(skill.instructions)
}

// List all available skills
const allSkills = await reviewer.listSkills()
for (const meta of allSkills) {
  console.log(`${meta.name}: ${meta.description}`)
}

전체 API는 .getSkill() 레퍼런스 및 .listSkills() 레퍼런스를 참조하세요.

관련된

• 작업 공간 기술
• createSkill()참조
• .getSkill()참조
• .listSkills()참조
• Agent 기술 사양