10日で覚えるKiro CLIDay 4: カスタムエージェント入門
books.chapter 410日で覚えるKiro CLI

カスタムエージェントとは

カスタムエージェントは、Kiro CLI の動作を特定のワークフローに合わせてカスタマイズする設定ファイルです。利用可能なツール、権限、自動的にロードするコンテキストを定義することで、タスクに特化したAIアシスタントを作れます。

なぜカスタムエージェントが必要か

デフォルトの Kiro CLI は汎用的で、すべてのツールに対して使用確認を求めます。実際の開発では、以下のような課題が生じます。

  • 確認プロンプトの頻発: ファイル読み書きのたびに確認が必要
  • コンテキスト不足: プロジェクト固有のルールや設定を毎回説明する必要がある
  • ツールの過剰: 使わないツールまで利用可能な状態
  • チーム間のばらつき: メンバーごとに異なる設定

カスタムエージェントは、これらをすべて解決します。

メリット 説明
ワークフロー最適化 タスク専用のエージェントで効率化
中断の削減 信頼するツールの確認をスキップ
コンテキスト強化 プロジェクト情報を自動ロード
チーム標準化 共有設定で一貫した環境
セキュリティ制御 必要なツールのみアクセス許可

エージェントの作成方法

AI支援モード（デフォルト）

最も簡単な方法は、チャットセッション内で /agent create を実行することです。

> /agent create

対話的に以下の情報を聞かれます。

  1. エージェント名
  2. エージェントの説明
  3. スコープ（ローカル or グローバル）
  4. 含める MCP サーバー

インラインで指定することもできます。

> /agent create backend-specialist -D "Backend API development specialist" -m code-analysis

CLI コマンドから作成

kiro-cli agent create backend-specialist

手動モード

JSON 設定ファイルを直接編集したい場合は --manual フラグを使います。

> /agent create my-agent --manual

デフォルトエディタが開き、基本的な設定テンプレートが表示されます。

テンプレートベース

既存のエージェントを元に新しいエージェントを作成できます。

> /agent create my-agent --from backend-specialist

作成オプション

フラグ 説明 利用可能場所
--directory 保存先（workspace/global/パス） CLI & スラッシュ
--from テンプレートエージェント CLI & スラッシュ
--description エージェントの説明 スラッシュのみ
--mcp-server MCP サーバー（複数指定可） スラッシュのみ
--manual エディタベースの作成 スラッシュのみ

設定ファイルの構造

カスタムエージェントは JSON ファイルで定義します。ファイル名（.json を除く）がエージェント名になります。

{
  "name": "frontend-dev",
  "description": "Frontend development specialist for React projects",
  "prompt": "You are a frontend development expert specializing in React, TypeScript, and modern web development.",
  "tools": ["read", "write", "shell", "code"],
  "allowedTools": ["read", "code"],
  "model": "claude-sonnet-4",
  "welcomeMessage": "Frontend Dev agent ready. What would you like to work on?"
}

主要フィールド

name

エージェントの識別名。表示やコマンドでの参照に使用されます。

{
  "name": "frontend-dev"
}

description

エージェントの役割を説明するテキスト。ユーザーが複数のエージェントを区別するのに役立ちます。

{
  "description": "Frontend development specialist for React projects"
}

prompt

AIへの高レベルな指示。システムプロンプトのような役割を果たします。インラインテキストまたは外部ファイルの参照が可能です。

{
  "prompt": "You are a frontend expert..."
}

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

相対パスはエージェント設定ファイルのディレクトリからの相対パスとして解決されます。

tools

エージェントが使用できるツールのリスト。

{
  "tools": ["read", "write", "shell", "aws", "@git"]
}
指定方法 例 説明
組み込みツール "read", "write", "shell" 標準ツール
MCP ツール（全体） "@server_name" サーバーの全ツール
MCP ツール（個別） "@server/tool_name" 特定のツール
全ツール "*" すべてのツール
全組み込み "@builtin" 組み込みツールすべて

allowedTools

確認なしで自動実行を許可するツール。ワイルドカードパターンに対応しています。

{
  "allowedTools": [
    "read",
    "code",
    "@git/git_status",
    "@git/git_log",
    "@server/read_*"
  ]
}
パターン マッチ対象
"read" read ツールのみ
"@git" git サーバーの全ツール
"@git/git_status" git_status のみ
"@server/read_*" read_ で始まるツール
"code_?" code_ + 1文字

model

使用する AI モデルを指定します。指定しない場合はデフォルトモデルが使われます。

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

welcomeMessage

エージェントに切り替えたときに表示されるメッセージ。

{
  "welcomeMessage": "Frontend Dev agent ready. What would you like to work on?"
}

keyboardShortcut

エージェントへの素早いアクセス用ショートカット。

{
  "keyboardShortcut": "ctrl+1"
}

フォーマット: [modifier+]key（modifier は ctrl または shift、key は a-z または 0-9）。

ファイルの保存場所

flowchart TB
    subgraph Global["グローバルエージェント<br/>~/.kiro/agents/"]
        G1["aws-specialist.json"]
        G2["code-reviewer.json"]
    end
    subgraph Local["ローカルエージェント<br/>.kiro/agents/"]
        L1["project-dev.json"]
        L2["api-specialist.json"]
    end
    Priority["同名の場合<br/>ローカルが優先"]
    Local --> Priority
    Global --> Priority
    style Global fill:#8b5cf6,color:#fff
    style Local fill:#3b82f6,color:#fff
    style Priority fill:#f59e0b,color:#fff
  • ローカル: .kiro/agents/（プロジェクト固有）
  • グローバル: ~/.kiro/agents/（全プロジェクト共通）

同名のエージェントが両方に存在する場合、ローカルが優先されます。

エージェントの使用と管理

特定のエージェントで起動

kiro-cli --agent frontend-dev

セッション中の切り替え

> /agent swap

利用可能なエージェント一覧から選択できます。

エージェント一覧

> /agent list

kiro-cli agent list

デフォルトエージェントの設定

kiro-cli agent set-default frontend-dev

エージェントの編集

> /agent edit frontend-dev

kiro-cli agent edit frontend-dev

エージェント設定の検証

> /agent validate

設定ファイルの構文や構造に問題がないか確認できます。

最初のエージェントを作ってみよう

実践として、簡単な開発用エージェントを作成してみましょう。

1. エージェントの作成

> /agent create dev-helper --manual

2. 設定の編集

{
  "name": "dev-helper",
  "description": "General development helper with safe defaults",
  "prompt": "You are a helpful development assistant. Follow project conventions and write clean, tested code.",
  "tools": ["read", "write", "shell", "code"],
  "allowedTools": ["read", "code"],
  "model": "auto",
  "welcomeMessage": "Dev helper ready! What are we building today?"
}

3. エージェントで起動

kiro-cli --agent dev-helper

4. 動作確認

> このプロジェクトの構造を教えてください

read と code は allowedTools に含まれているため、確認なしで実行されます。write や shell は確認が必要です。

まとめ

項目 内容
カスタムエージェント ツール、権限、コンテキストを定義した設定ファイル
作成方法 /agent create（AI支援）/ --manual（手動）
設定ファイル JSON 形式、ファイル名 = エージェント名
主要フィールド tools, allowedTools, prompt, model
保存場所 .kiro/agents/（ローカル）/ ~/.kiro/agents/（グローバル）
切り替え --agent name / /agent swap

Day 5 では、実践的なエージェント設定と高度なオプションを学びます。