Subagents

Subagents는 Kiro가 여러 작업을 병렬로 처리하거나 특화된 작업을 별도의 컨텍스트로 위임할 수 있게 해주는 보조 에이전트입니다.

개요

Kiro는 작업의 성격을 판단해 자동으로 Subagent를 호출하지만, 사용자가 채팅에서 "Run subagents to..."처럼 직접 요청해 명시적으로 실행할 수도 있습니다. 기본 제공되는 Subagent는 다음 두 가지입니다.

• Context gathering Subagent — 프로젝트를 탐색하면서 작업에 필요한 맥락 정보를 수집합니다.
• General purpose Subagent — 위에 해당하지 않는 일반적인 작업을 병렬로 분산 처리합니다.

동작 방식

1. 메인 Agent가 필요한 시점에 하나 또는 여러 개의 Subagent를 동시에 띄웁니다.
2. 모든 Subagent가 작업을 마칠 때까지 메인 Agent는 대기합니다.
3. 각 Subagent는 자체 컨텍스트 윈도우에서 동작하므로, 메인 Agent의 컨텍스트가 도구 호출 로그나 부수적인 출력으로 오염되지 않습니다.
4. 작업이 끝나면 결과만 메인 Agent로 회수되어 후속 단계에 활용됩니다.

Custom subagents

고유한 역할을 가진 커스텀 Subagent는 마크다운(.md) 파일로 정의합니다. 저장 위치에 따라 적용 범위가 달라집니다.

• Global 범위: ~/.kiro/agents
• Workspace 범위: <workspace>/.kiro/agents

마크다운 본문에는 에이전트의 행동 지침(프롬프트)을 작성하고, 파일 상단의 YAML front matter에 속성을 정의합니다.

예시: ~/.kiro/agents/code-reviewer.md

---
name: code-reviewer
description: Expert code review assistant.
tools: ["read", "@context7"]
model: claude-sonnet-4
---
You are a senior code reviewer.

## Your Responsibilities
- Review code for correctness, performance, and security
...

호출 방법

Kiro는 각 커스텀 에이전트의 description 필드를 보고 적절한 Subagent를 자동으로 선택합니다. 특정 에이전트를 직접 지정해 호출할 수도 있습니다.

1. 자연어로 호출: "Use the code-reviewer subagent to find performance issues in my code"
2. 슬래시 명령으로 호출: /code-reviewer find performance issues in my code

Front matter 속성

name은 필수이며 나머지는 선택 항목입니다.

tools 필드에 쓸 수 있는 값

내장 도구 그룹은 다음과 같습니다.

• read — 파일 읽기 관련 내장 도구 일체
• write — 파일 쓰기 관련 내장 도구 일체
• shell — 셸 명령 관련 내장 도구 일체
• web — 웹 관련 내장 도구 일체
• spec — Spec 관련 내장 도구 (Spec mode에서만 유효)
• @builtin — 모든 내장 도구

MCP 서버의 도구는 다음과 같은 패턴으로 지정합니다.

• @<mcp_server> — 특정 MCP 서버의 모든 도구 (예: @figma)
• @<mcp_server>/<tool> — 특정 서버의 특정 도구 (예: @figma/get_figjam)

와일드카드도 사용할 수 있습니다.

• tools: ["*"] — 모든 내장 도구와 MCP 도구
• tools: ["@figma/*"] — figma MCP 서버의 모든 도구