はじめてのカスタムエージェント【Kiro CLI編】

こんにちは。
アプリケーションサービス部、DevOps担当の兼安です。

今回は、以下の記事の続きとして、Kiro CLIを使って、カスタムエージェントを作成する手順をご紹介します。

blog.serverworks.co.jp

本記事のターゲット
カスタムエージェントとは
Kiro CLIとは
Kiro CLIにおけるカスタムエージェントの作成
開発者とプロジェクトマネージャー用のカスタムエージェントを作成してみる
カスタムエージェントを使ってみる
おわりに

本記事のターゲット

本記事は、AIコーディングアシスタントを使った開発に興味があるエンジニアの方を対象にしています。
IDEにVS Codeを想定した内容となっています。
カスタムエージェントの説明に重きをおいており、AIコーディングアシスタントそのもの、IDE、MCPサーバーの基本的な使い方については触れませんので、あらかじめご了承ください。

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

Kiro CLIにおけるカスタムエージェントとは、AIコーディングアシスタントを特定のタスクや役割に合わせてチューニングし、その設定を保存したものです。

Kiro CLIとは

Kiro CLIは、Amazon Q Developer CLIから発展した、コマンドラインで操作するAIエージェントツールです。
詳細はこちらをご覧ください。

aws.amazon.com

blog.serverworks.co.jp

Kiro CLIにおけるカスタムエージェントの作成

Kiro CLIにおけるカスタムエージェントの作成は、こちらの公式ドキュメントに詳しく記載されています。
Kiro CLIは元がAmazon Q Developer CLIなので、Amazon Q Developer CLIにも同様のドキュメントがありますが、現時点ではKiro CLIのドキュメントを参照するのが良いと思います。

kiro.dev

手順に従ってカスタムエージェントを作成してみますが、今回はMCPサーバーの設定を用意しておきます。
Kiro CLIでリポジトリ内にMCPサーバーを設定する場合は、以下の場所に作ります。

.kiro
└── settings
    └── mcp.json

この状態でKiro CLIを起動し、カスタムエージェントの作成コマンドを実行します。
カスタムエージェントの作成には、kiro-cli custom-agent createではなく、Kiro CLIのチャットを起動後に実行する/agent generateコマンドの方が良いと思います。
kiro-cli custom-agent createをそのまま実行してカスタムエージェントを作成すると、全体用のカスタムエージェントとなり設定ファイルが~/.kiro/agentsに作成されます。
リポジトリの方を眺めても変化が現れず、困惑する可能性があるため、まずは/agent generateコマンドを使うことをお勧めします。
以下は、VS CodeのターミナルでKiro CLIを起動し、/agent generateコマンドを実行した例です。

> kiro-cli

途中省略しますが、ここでKiro CLIが起動します。  

> /agent generate

✔ Enter agent name:  · example
✔ Enter agent description:  · example
✔ Agent scope · Local (current workspace)
Select MCP servers (use Space to toggle, Enter to confirm):
  [ ] backlog (npx)
> [x] awslabs.aws-documentation-mcp-server (uvx)

/agent generateコマンドを実行すると、ウィザード形式でカスタムエージェントの名前、説明、スコープ、MCPサーバーの選択ができます。
スコープで「Local (current workspace)」を選択すると、リポジトリ内にカスタムエージェントの設定ファイルが作成されます。
MCPサーバーの選択肢は、.kiro/settings/mcp.jsonで定義したMCPサーバーが表示されます。
ただし、mcp.jsonで定義したMCPサーバーが多すぎると、すべての選択肢が表示されないことを確認しています。
その場合は、後で手動で設定ファイルを編集すると良いでしょう。

設定を終えてEnterキーを押すと、VS Codeのエディタでカスタムエージェントの設定ファイルが開きます。
ファイル名が一時的なものになっているのに着目してください。
これを閉じることでウィザードが終了し、カスタムエージェントの設定ファイルがリポジトリ内に保存されます。

ウィザード終了後、リポジトリ内に以下のようにカスタムエージェントの設定ファイルが作成されます。

.kiro
├── agents
│   └── example.json
└── settings
    └── mcp.json

カスタムエージェントの設定ファイルの中身は、以下のようになっています。

{
  "name": "example",
  "description": "example",
  "prompt": "You are an example agent designed to assist with general tasks and provide helpful responses.",
  "mcpServers": {
    "aws-knowledge-mcp-server": {
      "url": "",
      "headers": {},
      "oauthScopes": [
        "openid",
        "email",
        "profile",
        "offline_access"
      ],
      "command": "uvx",
      "args": [
        "fastmcp",
        "run",
        "https://knowledge-mcp.global.api.aws"
      ],
      "timeout": 120000,
      "disabled": false,
      "disabledTools": []
    }
  },
  "tools": [
    "*"
  ],
  "toolAliases": {},
  "allowedTools": [],
  "resources": [
    "file://AGENTS.md",
    "file://README.md"
  ],
  "hooks": {},
  "toolsSettings": {},
  "useLegacyMcpJson": false,
  "model": null
}

設定ファイルの各項目については、こちらに詳しく記載されています。

kiro.dev

promptにどんな役割をしてほしいかを記載します。
ちなみに、公式ドキュメントの説明ではpromptは「High-level context for the agent.」とありますが、ここでの「High-level」は高度なという意味ではなく、概要的なという意味合いです。

GitHub Copilot Agent Modeのカスタムエージェントの設定ファイルと大きく違うのは、カスタムエージェント側でMCPサーバーの指定とコンテキストの指定ができる点です。
コンテキストの指定は、resourcesで行います。
MCPサーバー単位で指定できる点は、ツール単位での指定よりわかりやすいですが、mcp.jsonとの二重管理になり得るため、注意が必要です。

開発者とプロジェクトマネージャー用のカスタムエージェントを作成してみる

実際にカスタムエージェントを2つ作成してみます。
作成するのは、開発者用とプロジェクトマネージャー用の2つです。
先ほどは/agent generateのウィザードの挙動を説明するために.kiro/settings/mcp.jsonを用意しましたが、必須ではないのでカットします。

ディレクトリ構造は以下のようになります。

.kiro
└── agents
    ├── developer.json
    └── pm.json

ファイルの中身は以下のようにしてみました。
まずは、開発者用です。
resourcesには、リポジトリ内のドキュメントディレクトリを追加してコンテキストの一部とするようにしています。

{
  "name": "developer",
  "description": "developer",
  "prompt": "You are a developer proficient in AWS, Python, and TypeScript. In system development centred around AWS, you must provide information and code professionally, based on accurate and up-to-date knowledge.",
  "mcpServers": {
    "aws-knowledge-mcp-server": {
      "url": "",
      "headers": {},
      "oauthScopes": [
        "openid",
        "email",
        "profile",
        "offline_access"
      ],
      "command": "uvx",
      "args": [
        "fastmcp",
        "run",
        "https://knowledge-mcp.global.api.aws"
      ],
      "timeout": 120000,
      "disabled": false,
      "disabledTools": []
    }
  },
  "tools": [
    "*"
  ],
  "toolAliases": {},
  "allowedTools": [],
  "resources": [
    "file://AGENTS.md",
    "file://README.md",
    "file://docs/**/*.md"
  ],
  "hooks": {},
  "toolsSettings": {},
  "useLegacyMcpJson": false,
  "model": null
}

こちらはプロジェクトマネージャー用です。
プロジェクトマネージャー用は、マネジメント重視でBacklogのMCPサーバーのツールを利用可能にしています。
参考：BacklogのMCPサーバーでタスクのサマリを見てみる

{
  "name": "pm",
  "description": "pm",
  "prompt": "You are the project manager. The project uses Backlog for task management. As project manager, you must focus on overall progress and quality rather than the details of individual tasks. You must monitor deadlines, bottlenecks, and whether schedules are correctly defined, and provide appropriately summarised information.",
  "mcpServers": {
    "backlog": {
      "url": "",
      "headers": {},
      "oauthScopes": [
        "openid",
        "email",
        "profile",
        "offline_access"
      ],
      "command": "npx",
      "args": [
        "backlog-mcp-server"
      ],
      "env": {
        "BACKLOG_API_KEY": "{your-api-key}",
        "PREFIX": "backlog_",
        "ENABLE_TOOLSETS": "issue,wiki",
        "BACKLOG_DOMAIN": "{your-domain}.backlog.jp"
      },
      "timeout": 120000,
      "disabled": false,
      "disabledTools": []
    }
  },
  "tools": [
    "*"
  ],
  "toolAliases": {},
  "allowedTools": [],
  "resources": [
    "file://AGENTS.md",
    "file://README.md"
  ],
  "hooks": {},
  "toolsSettings": {},
  "useLegacyMcpJson": false,
  "model": null
}

GitHub Copilot Agent Modeに比べて、promptに改行が入れられないのでちょっと書き辛さを感じますね。
これについてはpromptを外部ファイル化して読み込む方法があるため、他の設定項目の詳しい使い方とあわせて別途記事にまとめたいと思います。

カスタムエージェントを使ってみる

Kiro CLIでカスタムエージェントを使う場合は、以下のようにするのが簡単です。

kiro-cli --agent {agent-name}

Kiro CLIのチャットを起動後に、/agent swapで切り替えることもできます。
私はエージェントを切り替えるならそれまでの状態をきれいさっぱり忘れてほしいので、チャットを丸ごと終了し、再起動時にエージェントを指定し直す方が好きです。

エージェントを指定してKiro CLIのチャットを起動すると、チャットのプロンプトにエージェント名が表示されます。
そして、MCPサーバーやコンテキストも切り替わっていることも確認できます。

> kiro-cli --agent developer

[developer] > /mcp

aws-knowledge-mcp-server
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
[2025:11:00]: ✓ aws-knowledge-mcp-server loaded in 2.92 s



[developer] > /context show

省略、コンテキストとしてロードされたドキュメントの一覧が表示されます。

質問すると、カスタムエージェントのpromptとmcpServersなどに基づいて応答が返ってきます。
開発者用だとMCPサーバーとしてAWSナレッジのMCPサーバーが利用しつつ、比較的技術的な回答が返ってきます。

[developer] > AWS DevOps Agentとはなんですか？

Running tool aws___search_documentation with the param (from mcp server: aws-knowledge-mcp-server)
 ⋮  {
 ⋮    "search_phrase": "AWS DevOps Agent",
 ⋮    "topics": [
 ⋮      "current_awareness",
 ⋮      "general"
 ⋮    ]
 ⋮  }

Allow this action? Use 't' to trust (always allow) this tool for the session. [y/n/t]:

[developer] > t

 - Completed in 7.304s

> AWS DevOps Agentは、2025年12月にプレビューとして発表されたAWSの新しいAIエージェントサービスです。  

## 主な機能

インシデント対応の自動化
- システム障害の自動検知と根本原因の特定
- 平均復旧時間（MTTR）の短縮
- 観測可能性ツール、ランブック、コードリポジトリ、CI/CDパイプラインとの連携

以下、省略

プロジェクトマネージャー用だとAWSナレッジのMCPサーバーは設定していないため、利用されませんでした。
この時は、WEB検索ツールなどが利用されて、やや概要的な回答が返ってくるのを確認できました。