커스텀 에이전트

목표

기본 에이전트 외에 특정 역할과 전문성을 가진 커스텀 에이전트를 정의하고 활용하는 방법을 이해합니다.

개념

기본 에이전트 외에 특정 역할/전문성을 가진 에이전트를 정의하여 활용할 수 있습니다.

활용 사례

• 코드 리뷰 전문 에이전트
• 문서 작성 전문 에이전트
• 테스트 생성 전문 에이전트
• 보안 검사 전문 에이전트

정의 방법

커스텀 에이전트는 JSON(.json) 또는 Markdown(.md) 설정 파일로 정의합니다. 두 형식은 같은 필드를 지원하며, 프롬프트가 길거나 사람이 읽기 쉽게 관리해야 할 때는 Markdown을 권장합니다.

• 프로젝트 설정: .kiro/agents/에 저장하여 버전 관리로 공유합니다. 신뢰된 워크스페이스에서만 로드됩니다.
• 글로벌 설정: ~/.kiro/agents/에 저장하여 모든 프로젝트에서 사용합니다.
• 같은 이름이 두 위치에 있으면 프로젝트 설정이 우선합니다.
• 중첩 디렉터리를 사용할 수 있으며, 에이전트 이름은 agents 디렉터리 아래의 상대 경로에서 확장자를 뺀 값입니다.

현재 커스텀 에이전트는 IDE와 CLI에서만 선택할 수 있습니다. Web(Preview)과 Mobile(Preview)에서는 built-in agent만 사용할 수 있으며 커스텀 에이전트를 선택할 수 없습니다.

주요 필드

모든 신규 필드는 선택 사항입니다.

필드	설명	예
name	에이전트 이름	"docs-writer"
description	에이전트 용도 설명	"문서 작성 작업을 돕습니다"
tools	노출할 built-in 또는 MCP 도구	["read", "write", "shell"]
excludedTools	사용에서 제외할 도구	["knowledge"]
includeMcpJson	MCP 설정 포함 여부	true
includePowers	Powers 포함 여부	false
resources	자동으로 포함할 파일 또는 Skill	["file://./README.md", "skill://docs"]
permissions.rules	도구별 승인 규칙	shell에서 npm * 허용
prompt	에이전트의 작업 지침	"문서를 명확하게 작성하세요"
model	사용할 모델	환경에 따라 지원 값이 다름
welcomeMessage	선택했을 때 표시할 안내 문구	"문서 작업을 시작할까요?"

커스텀 에이전트는 built-in tools와 MCP 서버의 외부 도구를 함께 사용할 수 있습니다. tools로 노출할 도구를 지정하고, 이름이 충돌할 때는 toolAliases를 이름 충돌 해결용으로 사용합니다.

Powers, Agent Skills, MCP와 조합하는 선택 기준은 Context Engineering에서 이어서 확인하세요.

사전 준비

• Kiro IDE 또는 CLI 로그인 완료
• Kiro에서 신뢰된 프로젝트 폴더 열기

해볼 것

1단계: 최소 에이전트 만들기

프로젝트 루트에 .kiro/agents/docs-writer.json 파일을 만들고 다음 내용을 저장합니다:

{
  "name": "docs-writer",
  "description": "프로젝트 문서 작성을 돕는 에이전트",
  "tools": ["read", "write", "shell"],
  "prompt": "프로젝트의 기존 문체를 유지하며 문서를 명확하게 작성하세요."
}

신뢰할 수 있는 프로젝트에서 반복 명령의 확인 절차를 줄이려면 permissions.rules를 추가할 수 있습니다:

{
  "name": "docs-writer",
  "description": "프로젝트 문서 작성을 돕는 에이전트",
  "tools": ["read", "write", "shell"],
  "permissions": {
    "rules": [
      {
        "capability": "shell",
        "match": ["npm *", "git *"],
        "effect": "allow"
      }
    ]
  },
  "prompt": "프로젝트의 기존 문체를 유지하며 문서를 명확하게 작성하세요."
}

권한 범위 확인

allow 규칙은 신뢰하는 명령에만 사용하세요. 위 예제는 문법을 보여주기 위한 것이므로 실제 프로젝트에서는 필요한 명령 범위로 더 좁히는 것이 좋습니다.

2단계: 에이전트 선택하기

IDE 또는 CLI의 에이전트 선택 영역에서 docs-writer를 찾아 선택합니다. 목록에 표시되지 않으면 파일 저장 위치와 이름, 워크스페이스 신뢰 상태를 먼저 확인합니다.

3단계: 동작 확인하기

선택한 에이전트에서 다음과 같이 요청합니다:

README.md를 읽고 오래된 설명이 있는지 확인해줘.

에이전트가 설정한 도구만 사용하는지 확인합니다. 이어서 신뢰하는 프로젝트에서 허용 규칙과 일치하는 작업을 요청하고, 사전 승인된 shell 명령이 추가 확인 없이 실행되는지 살펴봅니다.

기대 결과

• 프로젝트 커스텀 에이전트가 IDE 또는 CLI의 선택 목록에 표시됨
• 선택한 에이전트가 설정한 프롬프트와 도구 범위에 따라 응답함
• permissions.rules와 일치하는 신뢰 도구 작업이 추가 확인 없이 실행됨

0 / 4항목을 클릭해 체크 · 진행 상태는 이 브라우저에 저장됩니다

• .kiro/agents/docs-writer.json 생성 및 저장필수
• IDE 또는 CLI에서 docs-writer 선택필수
• 선택한 에이전트로 README.md 확인 요청 실행필수
• permissions.rules 적용 동작 확인선택

다른 기능과의 조합

커스텀 에이전트를 헤드리스 실행과 조합하면 CI/CD 파이프라인에서 전문화된 에이전트를 자동으로 실행할 수 있습니다. Checkpoints와 함께 사용하면 에이전트가 수행한 작업을 안전하게 되돌릴 수도 있습니다.

🚨 문제 해결

• 에이전트가 목록에 안 뜸: .kiro/agents/ 경로와 파일 이름을 확인하고, 프로젝트 워크스페이스가 신뢰 상태인지 확인하세요. 같은 이름의 글로벌 설정이 있다면 프로젝트 설정이 우선합니다.
• 도구 실행 시 계속 확인을 요구함: permissions.rules의 capability, match, effect 문법과 요청한 명령이 match 범위에 포함되는지 확인하세요.

✅ 핵심 요약

커스텀 에이전트 = 역할별 전문 에이전트 정의. Steering·MCP와 결합하여 정밀한 자동화 가능

함께 보기

• Sub-agents — custom agent를 포함한 독립 작업을 별도 컨텍스트에 위임하는 실행 방식