whchoi98.github.io
홈Home / Workshop / Kiro CLI Workshop

에이전트 구성 레퍼런스

에이전트 구성 레퍼런스

Table of contents

  1. 1. Name Field
  2. 2. Description Field
  3. 3. Prompt Field
    1. Inline 프롬프트 예시
    2. File URI 프롬프트 예시
    3. 파일 경로 처리 규칙
  4. 4. MCP Servers Field
  5. 5. Tools Field
  6. 6. ToolAliases Field
  7. 7. AllowedTools Field
    1. 패턴 매칭 (Wildcard) 지원
  8. 8. ToolsSettings Field
  9. 9. Resources Field
  10. 10. Hooks Field
    1. Hook 타입
  11. 11. includeMcpJson Field
  12. 12. Model Field
  13. 13. 전체 예시
  14. 14. 에이전트 파일 위치
    1. Local Agents (프로젝트 전용)
    2. Global Agents (사용자 전역)
  15. 15. 에이전트 우선순위
  16. 16. 모범 사례
    1. 1. Security
    2. 2. Organization
    3. 3. Workflow

에이전트 구성 파일(Agent Configuration File)에는 다음과 같은 섹션을 포함할 수 있습니다:

1. Name Field

에이전트 식별용 이름을 지정합니다.

{
  "name": "aws-expert"
}

2. Description Field

에이전트의 역할을 설명하는 인간 친화적 텍스트입니다.

{
  "description": "An agent specialized for AWS infrastructure tasks"
}

3. Prompt Field

에이전트에 고수준 지침을 부여하는 시스템 프롬프트 역할을 합니다.

텍스트 또는 file:// URI를 사용하여 외부 파일을 참조할 수 있습니다.

Inline 프롬프트 예시

{
  "prompt": "You are an expert AWS infrastructure specialist"
}

File URI 프롬프트 예시

{
  "prompt": "file://./my-agent-prompt.md"
}

파일 경로 처리 규칙

4. MCP Servers Field

에이전트가 사용할 Model Context Protocol(MCP) 서버를 정의합니다.

{
  "mcpServers": {
    "fetch": {
      "command": "fetch3.1",
      "args": []
    },
    "git": {
      "command": "git-mcp",
      "args": [],
      "env": { "GIT_CONFIG_GLOBAL": "/dev/null" },
      "timeout": 120000
    }
  }
}

각 서버 설정 항목:

5. Tools Field

에이전트가 사용할 수 있는 도구 목록을 정의합니다.

도구 참조 방식:

예시:

{
  "tools": [
    "read",
    "write",
    "shell",
    "@git",
    "@rust-analyzer/check_code"
  ]
}

전체 도구 허용:

{
  "tools": ["*"]
}

6. ToolAliases Field

서버 간 동일 이름 도구 충돌 해결 또는 보다 직관적인 도구 이름 제공을 위해 사용합니다.

{
  "toolAliases": {
    "@github-mcp/get_issues": "github_issues",
    "@gitlab-mcp/get_issues": "gitlab_issues"
  }
}

짧은 alias 생성 예시:

{
  "toolAliases": {
    "@aws-cloud-formation/deploy_stack_with_parameters": "deploy_cf",
    "@kubernetes-tools/get_pod_logs_with_namespace": "pod_logs"
  }
}

7. AllowedTools Field

사용자 승인 없이 자동 실행을 허용할 도구를 지정합니다.

보안 기능이므로 신중하게 구성해야 합니다.

{
  "allowedTools": [
    "read",
    "write",
    "@git/git_status",
    "@server/read_*",
    "@fetch"
  ]
}

패턴 매칭 (Wildcard) 지원

주의: allowedTools는 “*” 로 전체 허용을 지원하지 않습니다. (보안 이유)

8. ToolsSettings Field

개별 도구에 특화된 설정을 제공합니다.

{
  "toolsSettings": {
    "write": {
      "allowedPaths": ["~/**"]
    },
    "@git/git_status": {
      "git_user": "$GIT_USER"
    }
  }
}

9. Resources Field

에이전트가 로드할 파일 기반 리소스를 지정합니다.

반드시 file:// 접두사 사용.

{
  "resources": [
    "file://AmazonQ.md",
    "file://README.md",
    "file://.amazonq/rules/**/*.md"
  ]
}

지원 기능:

10. Hooks Field

에이전트 생명주기(Lifecycle) 및 도구 실행 시점에서 특정 명령을 실행합니다.

{
  "hooks": {
    "agentSpawn": [{ "command": "git status" }],
    "userPromptSubmit": [{ "command": "ls -la" }],
    "preToolUse": [
      {
        "matcher": "shell",
        "command": "{ echo \"$(date) - Bash command:\"; cat; } >> /tmp/bash_audit_log"
      }
    ],
    "postToolUse": [
      {
        "matcher": "write",
        "command": "cargo fmt --all"
      }
    ]
  }
}

Hook 타입

Hook설명
agentSpawn에이전트 초기화 시 실행
userPromptSubmit사용자가 메시지를 제출할 때
preToolUse도구 실행 전(차단 가능)
postToolUse도구 실행 후
stopAssistant 응답 종료 시

11. includeMcpJson Field

글로벌 및 로컬 MCP 설정 파일에 정의된 MCP 서버를 자동 포함할지 여부:

{
  "includeMcpJson": true
}

12. Model Field

에이전트가 사용할 모델 ID를 지정합니다.

{
  "model": "claude-sonnet-4"
}

모델이 사용 가능하지 않으면 기본 모델로 폴백(fallback)되며 경고가 표시됩니다.

13. 전체 예시

{
  "name": "aws-rust-agent",
  "description": "Specialized agent for AWS and Rust development",
  "prompt": "file://./prompts/aws-rust-expert.md",
  "mcpServers": {
    "fetch": { "command": "fetch-server", "args": [] },
    "git": { "command": "git-mcp", "args": [] }
  },
  "tools": ["read", "write", "shell", "aws", "@git", "@fetch/fetch_url"],
  "toolAliases": {
    "@git/git_status": "status",
    "@fetch/fetch_url": "get"
  },
  "allowedTools": ["read", "@git/git_status"],
  "toolsSettings": {
    "write": { "allowedPaths": ["src/**", "tests/**", "Cargo.toml"] },
    "aws": { "allowedServices": ["s3", "lambda"], "autoAllowReadonly": true }
  },
  "resources": ["file://README.md", "file://docs/**/*.md"],
  "hooks": {
    "agentSpawn": [{ "command": "git status" }],
    "postToolUse": [
      { "matcher": "write", "command": "cargo fmt --all" }
    ]
  },
  "model": "claude-sonnet-4"
}

14. 에이전트 파일 위치

Local Agents (프로젝트 전용)

.kiro/agents/

해당 워크스페이스에서만 사용 가능하며 팀과 버전 관리하기 용이합니다.

예시:

my-project/
  .kiro/
    agents/
      dev-agent.json
      aws-specialist.json

Global Agents (사용자 전역)

~/.kiro/agents/

어디서든 사용 가능하며 개인화된 에이전트에 적합합니다.

15. 에이전트 우선순위

  1. Local 에이전트 우선
  2. 동일 이름이 존재할 경우 Global 에이전트는 무시되며 경고 표시

16. 모범 사례

1. Security

2. Organization

3. Workflow