Kiro IDE で作ったカスタムエージェントが Kiro Crew に出てこない原因を調べてみた
いわさです。
最近は Kiro IDE のエージェントフォーカスモードを使って、複数のセッションを並行で回す作業に慣れてきました。ただ、それでもまだ管理しにくいところがあって、今回ためしに Kiro Crew をあらためて使ってみることにしました。
Kiro Crew を使ってみようとしたところ、問題があることに気が付きました。
私は Kiro IDE では、自分で作ったカスタムエージェントを切り替えながらタスクを処理しています。
確認してみたところ、Kiro Crew でセッションを作るときのエージェント選択には、Kiro IDE で使っていた自作のエージェントの多くが出てきませんでした。
よく見ると、自作エージェントでも JSON 形式で作ったものは表示されていて、出てこないのは Markdown 形式で作ったものだけのようです。どういうことでしょう。
Kiro Crew では V2 で起動されるため .md のエージェントが読み込まれない
何が違うのか ~/.kiro/agents/ を見てみると、IDE 用に自分で作ったエージェントは Markdown 形式（.md）、Kiro Crew 側にもとからあるエージェントは JSON 形式（.json）でした。
実は現在の Kiro のエージェント定義には Markdown 形式（.md）と JSON 形式（.json）の2つがあります。
もともとは JSON 形式でしたが、Kiro IDE 1.0 / Kiro CLI 3.0 の統合エージェントハーネスで Markdown 形式が追加され、今は両方が使えます。
デフォルト（V2 エンジン）の Kiro CLI を起動して /agent を開くと、.json のエージェントは並びますが、.md のエージェントは出てきません。
› /agent
Select agent: type to search
❯ my-json-agent-a Global （JSON 形式の自作エージェント）
my-json-agent-b Global （JSON 形式の自作エージェント）
kiro_default Built-in The default agent for Kiro CLI
kiro_guide Built-in Guide agent that answers questions about Kiro CLI features using documentation
kiro_planner Built-in Specialized planning agent that helps break down ideas into implementation plans
kirocrew Global Autonomous personal AI agent ...
kirocrew-conductor Global Owns a long-horizon goal ...
(+3 more)
並んでいるのは JSON 形式のエージェントと組み込みのエージェントだけで、Markdown 形式で作った自作エージェントは1つも出てきません。
しかしkiro-cli --v3 で V3 モードにして起動すると、同じ .md のエージェントが一覧に出てきました。
› /agent
Select agent: type to search
Name Source Scope Description
❯ Default local Bundled [active] General coding assistance
Spec local Bundled Structured feature development
Plan local Bundled Plan-only mode ...
my-md-agent-a local Global （Markdown 形式の自作エージェント）
my-md-agent-b local Global （Markdown 形式の自作エージェント）
my-md-agent-c local Global （Markdown 形式の自作エージェント）
(+more)
おお、Kiro IDE で自作したカスタムエージェントが表示されましたね。
.md 形式のエージェントは、V3 で起動したときだけ読み込まれるようです。
では Kiro Crew はどう起動しているのか調べてみましょう。
内部では Kiro CLI を次のように kiro-cli acp --agent <name> の形で起動しています。この acp サブコマンドは、起動するエンジンのデフォルトが V2 でした。
kiro-cli acp --help
# --agent-engine <ENGINE> Agent engine to use: "v1", "v2" (default), or "v3" [default: v2]
そのため、CLI を V2 で起動したときと同じく .md のエージェントを認識しません。
また、調査している中で気がついたのですが Kiro Crew 側のエージェントの探し方にも問題がありそうでした。
公式リポジトリの Issue で説明されているのですが、Kiro Crew のエージェント探索は ~/.kiro/agents/*.json を決め打ちで探していて、.md は読みこまないようになっているみたいです。
.json に変換すると出てきた
.md のままカスタムエージェントを使う方法は今のところ難しそうです。
ということで、Kiro Crew が認識できる .json に変換しましょう。
Markdown のいくつかの情報（description / tools / mcpServers）を JSON の属性に転記し、本文を prompt に入れるだけで良さそうです。
試しに1つ適当なカスタムエージェントを変換してみると、デフォルト（V2）の Kiro CLI の /agent 一覧に出るようになりました。
› /agent
Select agent: type to search
❯ AWSアーキテクチャ構成図エージェント Global draw.io MCPサーバーを使ってAWSアーキテクチャ構成図をdrawio XML形式で作成するエージェント
my-json-agent-a Global （JSON 形式の自作エージェント）
my-json-agent-b Global （JSON 形式の自作エージェント）
kiro_default Built-in The default agent for Kiro CLI
kiro_guide Built-in Guide agent that answers questions about Kiro CLI features using documentation
kiro_planner Built-in Specialized planning agent that helps break down ideas into implementation plans
kirocrew Global Autonomous personal AI agent ...
(+more)
Kiro Crew のダッシュボード（Agent Capabilities → Agents）にも表示されました。
しかしこのままカスタムエージェントを使ってみると、セッション作成時に invalid agent name になりました。
調べてみたのですが Kiro Crew のエージェント名は次の正規表現で検証されていて、英数字・ハイフン・アンダースコアしか通りません。どうやらエージェント名が日本語のままだとダメそうです。
^[a-zA-Z0-9][a-zA-Z0-9_-]{0,62}[a-zA-Z0-9]$|^[a-zA-Z0-9]$
試しにエージェント名を変えたあとは MCP サーバーも読み込まれ、Kiro Crew から実行して成果物が出力されるところまで動きました。
視認性が悪いのだが、本日時点では仕方ないですね。早く Kiro Crew 側で対応してほしいです。
あるいは OSS だったと思うのでプルリクエストを出してみるかな。
さいごに
本日は Kiro IDE で作ったカスタムエージェントが Kiro Crew に出てこない原因を調べてみました。
原因としてはエージェント定義の形式が２パターンあって、本日時点では Kiro Crew では.mdをサポートしていないのが原因でした。
.json に変換して名前を英数字にすれば Kiro Crew でも使えます。ただし新しい .md からわざわざ古い .json に戻す形になり、IDE 用の .md との二重管理になっちゃいますね。
Kiro Crew 側で対応され次第また更新したいなと思います。
