はじめに
AWS マネジメントコンソールをみると AgentCore optimization に AgentCore Insights（プレビュー中）がしれっとあるのに今更ですが気づきました。
AWS whats new を見落としていました。
忙しい人のための要約
- Insights はエージェントのセッション群を分析し、次のようなパターンを抽出します
- 失敗パターン（Failure analysis）
- ユーザーの意図（User intent）
- 実行内容の要約（Execution summary）
- 個々のセッションを分析するだけでなく、複数セッションを横断してクラスタリングし、「よくある失敗カテゴリ」を根本原因つきで教えてくれます
AgentCore Insights とは何か・何がうれしいのか
AgentCore エージェントは呼び出しのたびに「トレース」を CloudWatch に残します。
これまでの AgentCore Evaluations は、そのトレースにスコアを付ける（役に立ったか、正しかったか等）機能でした。
Insights はそれをもう一歩進めて、「なぜ失敗したか」「ユーザーは何をしたかったか」を LLM に要約・分類させ、似たセッションをクラスタとしてまとめる機能です。
個々のトレースを目視で追わなくても、エージェントがよく間違えるパターンとユーザーの実際の要望が自動で見えるようになります。
分析結果は後述する Recommendations（システムプロンプトの改善案生成）や A/B テストとも連携でき、「Insights で原因特定 → Recommendations で修正 → A/B テストで検証」という改善ループの起点になります。
やってみた
CLI の更新とプロジェクト作成
# CLI の更新
agentcore update
# プロジェクト作成
agentcore create --project-name InsightsDemo --name InsightsAgent --framework Strands --language Python --model-provider Bedrock --memory none --protocol HTTP --region ap-northeast-1
# プロジェクトディレクトリに移動
cd InsightsDemo
ツールを追加する
生成された app/InsightsAgent/main.py に、わざとエラーを起こしやすいツールを 2 つ追加します（架空のガジェットショップの注文照会・割引計算という設定です）。
既存の add_numbers ツールの下に貼り付けてください。
_ORDERS = {
"A1001": {"status": "shipped", "eta_days": 2},
"A1002": {"status": "processing", "eta_days": 5},
}
@tool
def check_order_status(order_id: str) -> dict:
"""Look up the shipping status of an order by its order ID (format: A####)."""
if order_id not in _ORDERS:
raise ValueError(f"Unknown order_id '{order_id}': no matching order in the system")
return _ORDERS[order_id]
tools.append(check_order_status)
@tool
def calculate_discount(price: float, discount_percent: float) -> float:
"""Calculate the discounted price given an original price and a discount percentage (0-100)."""
if not (0 <= discount_percent <= 100):
raise ValueError(f"discount_percent must be between 0 and 100, got {discount_percent}")
return round(price * (1 - discount_percent / 100), 2)
tools.append(calculate_discount)
コストを抑えたい場合は app/InsightsAgent/model/load.py のモデル ID を安価なモデルに変更できます。
return BedrockModel(model_id="jp.amazon.nova-2-lite-v1:0")
デプロイして何回か呼び出す
# デプロイしてエージェントを起動
agentcore deploy
デプロイ完了後、少し間を置いてから、正常系と異常系を混ぜたプロンプトをそれぞれ別セッションで投げます。
prompts=(
"注文A1001の状況を教えて"
"注文A1002はいつ届きますか"
"注文B9999はどうなっていますか"
"注文Z0000の配送状況を確認して"
"1000円の商品を20%オフにするといくらになりますか"
"5000円の商品を150%オフにしてください"
"3000円の商品を200%割引したらいくらですか"
"返品したいのですが、返金は何日でされますか"
"御社の実店舗の営業時間を教えてください"
"注文A1001の追跡番号を教えて"
"注文C1234の状況はどうなっていますか"
"注文X9999が届きません"
"8000円の商品を120%オフで買いたい"
"2000円の商品を90%オフにして"
"注文A1002の中身を教えてください"
)
i=0
for p in "${prompts[@]}"; do
i=$((i+1))
sid=$(printf "insights-demo-session-%02d-%s" "$i" "$(date +%s)")
agentcore invoke --runtime InsightsAgent --session-id "$sid" --prompt "$p"
done
Insights を実行する
トレースが CloudWatch に取り込まれるのを 2 〜 5 分待ってから、直近 1 日分のセッションを対象に Insights を実行します。
# Insights を実行
agentcore run insights --runtime InsightsAgent --insights Builtin.Insight.FailureAnalysis Builtin.Insight.UserIntent Builtin.Insight.ExecutionSummary --lookback-days 1 --name InsightDemo01 --wait
なお、実行はしませんが今回のように都度コマンドを叩く一回限りの実行だけでなく、日次・週次・月次のスケジュールで自動的にInsightsを再実行し、レポートを生成し続けることもできます。
# オンライン Insights のスケジュールを設定してデプロイ
agentcore add online-insights --runtime InsightsAgent --insights Builtin.Insight.FailureAnalysis Builtin.Insight.UserIntent Builtin.Insight.ExecutionSummary --clustering-frequency DAILY WEEKLY MONTHLY --enable-on-create
agentcore deploy
結果を確認する
まず、AWS マネジメントコンソールの AgentCore Insights から確認してみます。あわせて、AI に AgentCore CLI からも確認してもらいます。agentcore view insights は 3 種類のインサイトの結果をまとめて 1 つの JSON で返してくれるので、種類ごとに見ていきます。
agentcore view insights InsightDemo01-XXXXXXXXXXXX --json
Failure analysis（失敗パターン）
15 セッション中 4 セッションが失敗として検出され、いずれもcheck_order_statusに存在しない注文ID（B9999、Z0000、C1234、X9999）を渡したケースでした。エージェント自身は「注文が見つかりません、番号をご確認ください」と適切にエラーを吸収していますが、Insights はそれでも 「本来は事前にIDの形式をユーザーに確認させれば防げた失敗」 として、システムプロンプトへの修正案を返してきます。
{
"name": "Invalid User-Provided Identifiers in Tool Lookups",
"rootCause": "ユーザーが実在しない注文IDを入力し、ツール呼び出しがresource-not-foundエラーで失敗する。エージェントはエラーをユーザーに正しく伝えているが、事前にIDの形式を案内・検証していないことが根本原因。",
"recommendation": "システムプロンプトに、ツール呼び出し前にIDの形式（例: A####）をユーザーに確認させる、またはメールアドレス等の代替手段を提示するよう追記する",
"fixType": "SYSTEM_PROMPT_FIX"
}
なお、fixTypeは API 仕様上ただの文字列で、決まった選択肢（enum）としては定義されていません。今回の検証ではSYSTEM_PROMPT_FIX（システムプロンプトを直せば防げる）、TOOL_DESCRIPTION_FIX（ツールの説明文が原因）、OTHERS（それ以外）の 3 種類が実際に返ってきました。SYSTEM_PROMPT_FIXとTOOL_DESCRIPTION_FIXは後述のRecommendations が生成できる改善案の種類とちょうど対応しているので、Insights が「自動で直せる」と判断したものにはこの 2 つが、それ以外はOTHERS が付くようです。
User intents（ユーザーの意図）
こちらは「ユーザーが結局何を聞きたかったか」を横断的にまとめたものです。今回は 8 クラスタに分かれ、「注文状況確認」に 2 セッション、「割引・価格計算」に5セッション、といった形でどの意図が多いかが一目でわかります。実運用では、ここで想定外に多いクラスタが見つかれば、そのユースケース向けにツールやドキュメントを増強する判断材料になります。
Execution summaries（実行内容の要約）
こちらは「エージェントが実際に何をして、どう終わったか」の要約で、5 クラスタに分かれました。ここで注目するのが、割引率が範囲外（150%オフなど）だった 3 セッションの扱いです。Execution summary では「Invalid Discount Rate Constraint Violations（3件）」というクラスタとしてはっきり現れるのに、Failure analysis の失敗クラスタには一件も含まれていません。つまりFailure analysis だけを見ていると、ツール呼び出し自体は成功していても実質的に「望んだ結果が得られなかった」ケースを見落とすことがあるようです。3 種類のインサイトはそれぞれ別の切り口なので、失敗の全体像をつかむには Failure analysis 単体ではなく Execution summary も合わせて確認するのが良さそうです。
Recommendations で改善案をもらう
ここまでのInsightDemo01-XXXXXXXXXXXXをそのまま Recommendations に渡し、システムプロンプトの改善案を生成させてみます。--from-insightsに先ほどの Insights のジョブ名を指定すると、裏でトレースのソースとして自動的に紐付けてくれます。
agentcore run recommendation --type system-prompt --runtime InsightsAgent --evaluator Builtin.GoalSuccessRate --inline "You are a helpful assistant. Use tools when appropriate." --from-insights InsightDemo01-XXXXXXXXXXXX --run RecoDemo01 --wait
AWS マネジメントコンソール の Recommendations 画面から設定する場合、データソースとして Batch evaluation を指定する感じですね。
3 分ほど待って完了すると、改善前のシステムプロンプトと改善版のシステムプロンプトが返ってきます。
ちゃんと、Failure analysis で指摘のあった 「本来は事前にIDの形式をユーザーに確認させれば防げた失敗」 という点も「Tool usage guidelines」という部分で改善案となるシステムプロプトを提案してくれているようですね。