@shinyaz

AgentCore CLI 実践 — Evaluations でエージェントの品質を計測する

約5分
ai-agents
#bedrock#agentcore#agentcore-cli#agentcore-evaluations#strands-agents#ai-agents
目次

はじめに

第1回では基本ライフサイクル、第2回では Memory、第3回では Gateway を検証した。シリーズ最終回の今回は、Evaluations を使ってエージェントの応答品質を計測する。

AgentCore Evaluations は、LLM-as-a-Judge パターンでエージェントの品質を評価する仕組みだ。カスタム評価器を定義し、過去のトレースに対して on-demand で評価を実行したり、ライブトラフィックの一定割合を自動的にサンプリング評価（online eval）したりできる。

本記事では、カスタム評価器を定義して on-demand 評価を実行し、エージェントの応答品質スコアを取得する一連の流れを検証する。Evaluations のCLI ドキュメントも参照。

AgentCore CLI は Public Preview（v0.3.0-preview）段階であり、コマンド体系や生成テンプレートは GA までに変更される可能性がある。本記事の内容は 2026年3月時点の動作に基づいている。

前提条件

  • 第1回の環境が構築済み（Node.js 20+、uv、AWS CLI、AgentCore CLI v0.3.0-preview）
  • us-east-1 リージョンの AWS アカウント — Evaluator の CloudFormation リソース（AWS::BedrockAgentCore::Evaluator）は一部リージョンでのみサポートされている。本記事執筆時点では ap-northeast-1 では未サポートのため、us-east-1 を使用する

AWS_REGION 環境変数が設定されている場合、aws-targets.json のリージョンより優先されることがある。AWS_REGION が us-east-1 以外に設定されている場合は、export AWS_REGION=us-east-1 で上書きするか、unset AWS_REGION で解除してから実行する。

Evaluations の概要

概念説明
評価器（Evaluator）LLM-as-a-Judge の定義。評価プロンプト、モデル、スコアリング基準を含む
On-demand eval過去のトレースに対する一回限りの評価実行
Online evalライブトラフィックの一定割合を自動サンプリング評価
Builtin 評価器AgentCore が提供する事前定義済み評価器（例: Builtin.Faithfulness）

評価レベル

レベル評価対象
SESSION会話全体の品質
TRACE個々のターンの正確性
TOOL_CALLツール選択の適切性

本記事では SESSION レベルのカスタム評価器を使う。

プロジェクト作成とデプロイ

Terminal
agentcore create --name AgentCoreEvalTest --defaults --skip-git
cd AgentCoreEvalTest
 
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
cat > agentcore/aws-targets.json << EOF
[{"name":"default","account":"${ACCOUNT_ID}","region":"us-east-1"}]
EOF
 
agentcore deploy -y

トレースデータの生成

評価を実行するには、エージェントのトレースデータが必要だ。数回 invoke してトレースを生成する。

Terminal
agentcore invoke "What is 100 + 200? Use the add_numbers tool." --stream
agentcore invoke "Explain what Kubernetes is in one sentence." --stream
Output
The sum of 100 + 200 is **300**.
Output
Kubernetes is an open-source container orchestration platform that automates
the deployment, scaling, and management of containerized applications across
clusters of machines.

トレースがインデックスされるまで約10分かかる。初回デプロイ後は Transaction Search の有効化にも時間がかかるため、余裕を持って待つ必要がある。

カスタム評価器の追加

agentcore add evaluator で LLM-as-a-Judge 評価器を定義する。

Terminal
agentcore add evaluator \
  --name ResponseQuality \
  --level SESSION \
  --model us.anthropic.claude-sonnet-4-5-20250929-v1:0 \
  --instructions "Evaluate the overall quality of the agent's response. Consider accuracy, helpfulness, and clarity. Context: {context}" \
  --rating-scale 1-5-quality \
  --json
Output
{"success": true, "evaluatorName": "ResponseQuality"}

agentcore.json に追加される設定

agentcore/agentcore.json（evaluators 部分）
{
  "evaluators": [
    {
      "type": "CustomEvaluator",
      "name": "ResponseQuality",
      "level": "SESSION",
      "config": {
        "llmAsAJudge": {
          "model": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
          "instructions": "Evaluate the overall quality of the agent's response. Consider accuracy, helpfulness, and clarity. Context: {context}",
          "ratingScale": {
            "numerical": [
              {"value": 1, "label": "Poor", "definition": "Fails to meet expectations"},
              {"value": 2, "label": "Fair", "definition": "Partially meets expectations"},
              {"value": 3, "label": "Good", "definition": "Meets expectations"},
              {"value": 4, "label": "Very Good", "definition": "Exceeds expectations"},
              {"value": 5, "label": "Excellent", "definition": "Far exceeds expectations"}
            ]
          }
        }
      }
    }
  ]
}

ポイントは以下の通り。

  • --instructions に {context} プレースホルダーを含める必要がある。SESSION レベルでは会話全体が {context} に展開される
  • --rating-scale 1-5-quality はプリセットで、1〜5の数値スケールが自動設定される。他に 1-3-simple、pass-fail、good-neutral-bad のプリセットや、カスタムスケールも指定できる
  • --model には評価に使う LLM を指定する。評価対象のエージェントとは別のモデルを使うことも可能

評価器のデプロイ

Terminal
agentcore deploy -y
Terminal
agentcore status --json
Output
{
  "success": true,
  "resources": [
    {
      "resourceType": "agent",
      "name": "AgentCoreEvalTest",
      "deploymentState": "deployed",
      "detail": "READY"
    },
    {
      "resourceType": "evaluator",
      "name": "ResponseQuality",
      "deploymentState": "deployed",
      "detail": "SESSION — LLM-as-a-Judge — ACTIVE"
    }
  ]
}

evaluator が ACTIVE になっていれば評価器のデプロイ完了だ。

On-demand 評価の実行

トレースがインデックスされた後（invoke から約10分後）、agentcore run evals で評価を実行する。

Terminal
agentcore run evals \
  --agent AgentCoreEvalTest \
  --evaluator ResponseQuality \
  --days 1
Output
Agent: AgentCoreEvalTest | Mar 23, 2026, 10:58 AM | Sessions: 2 | Lookback: 1d
 
  ResponseQuality: 5.00
 
Results saved to: agentcore/.cli/eval-results/eval_2026-03-23_10-58-52.json

2つのセッションが評価され、ResponseQuality の平均スコアは 5.00（Excellent）だった。

評価結果の詳細

保存された JSON ファイルには、セッションごとのスコア、ラベル、LLM による説明文、トークン使用量が含まれる。

eval_2026-03-23_10-58-52.json（抜粋）
{
  "results": [
    {
      "evaluator": "ResponseQuality",
      "aggregateScore": 5,
      "sessionScores": [
        {
          "sessionId": "3032aad5-...",
          "value": 5,
          "label": "Excellent",
          "explanation": "The agent's response demonstrates excellent performance... The mathematical calculation is correct (100 + 200 = 300). The agent properly used the add_numbers tool as instructed..."
        },
        {
          "sessionId": "6a79a90e-...",
          "value": 5,
          "label": "Excellent",
          "explanation": "The agent's response successfully meets the user's request... The user asked for a one-sentence explanation of Kubernetes, and the agent delivered exactly that..."
        }
      ],
      "tokenUsage": {
        "inputTokens": 1058,
        "outputTokens": 526,
        "totalTokens": 1584
      }
    }
  ]
}

各セッションに対して、評価 LLM が正確性・有用性・明瞭性を分析し、スコアと根拠を返している。tokenUsage で評価にかかった LLM のトークン消費量も確認できる。

評価履歴の確認

Terminal
agentcore evals history --agent AgentCoreEvalTest
Output
Date                   Agent                Evaluators                     Sessions
──────────────────────────────────────────────────────────────────────────────────────────
Mar 23, 2026, 10:58 AM AgentCoreEvalTest    ResponseQuality=5.00           2

Online eval と Builtin 評価器

本記事では on-demand 評価のみを検証したが、CLI は以下の機能もサポートしている。

Online eval（継続的モニタリング）

ライブトラフィックの一定割合を自動的にサンプリング評価する。

Terminal
agentcore add online-eval \
  --name QualityMonitor \
  --agent AgentCoreEvalTest \
  --evaluator ResponseQuality \
  --sampling-rate 10
agentcore deploy -y

--sampling-rate 10 はリクエストの10%を評価する設定だ。pause online-eval / resume online-eval で運用中の一時停止・再開もできる。

Builtin 評価器

AgentCore が提供する事前定義済み評価器も利用できる。カスタム評価器と組み合わせて使うことも可能だ。

Terminal
agentcore run evals \
  --agent AgentCoreEvalTest \
  --evaluator ResponseQuality Builtin.Faithfulness \
  --days 7

まとめ

AgentCore CLI の Evaluations 機能を使って、エージェントの応答品質を LLM-as-a-Judge で計測する一連の流れを検証した。

  • カスタム評価器は agentcore.json に宣言的に定義される — 評価プロンプト、モデル、スコアリング基準を add evaluator で設定し、deploy で反映する。コードの記述は不要で、設定ファイルだけで評価パイプラインが構築できる。
  • トレースの反映に時間がかかる — invoke 後、トレースが run evals で検出されるまで約10分かかる。初回デプロイ後は Transaction Search の有効化にも時間がかかるため、余裕を持ったスケジュールが必要だ。
  • 評価結果にはセッションごとの詳細な根拠が含まれる — スコアだけでなく、評価 LLM による正確性・有用性・明瞭性の分析と根拠が返される。品質改善のフィードバックとして活用できる。
  • Evaluator の CloudFormation サポートはリージョン限定 — 本記事執筆時点では AWS::BedrockAgentCore::Evaluator は ap-northeast-1 では未サポートで、us-east-1 を使用した。利用可能なリージョンは今後拡大される見込みだ。

本シリーズでは、AgentCore CLI の4つの主要機能（Runtime、Memory、Gateway、Evaluations）を検証した。CLI は Preview 段階だが、agentcore.json を中心とした宣言的な設計と、create → add → deploy → invoke の統一されたワークフローにより、エージェントの開発から品質管理までを一貫して行える。次回のボーナス記事では、これら4つの機能を1つのプロジェクトに統合して実用的なエージェントを構築する。

クリーンアップ

Terminal
# プロジェクト内のリソース定義をすべて削除
agentcore remove all --force
 
# AWS リソースを削除
agentcore deploy -y
 
# CLI のアンインストール（不要な場合）
npm uninstall -g @aws/agentcore

共有する

田原 慎也

田原 慎也

ソリューションアーキテクト @ AWS

AWS ソリューションアーキテクトとして金融業界のお客様を中心に技術支援を行っています。クラウドアーキテクチャや AI/ML に関する学びをこのサイトで発信しています。このサイトの内容は個人の見解であり、所属企業の公式な意見や見解を代表するものではありません。

もっと見る →

関連記事

ブログ

AgentCore CLI 実践 — 主要機能を統合して技術トレンドアドバイザーを構築する

AgentCore CLI の Runtime・Memory・Gateway・Evaluations を1つのプロジェクトに統合し、ユーザーの専門分野を記憶して最新技術トレンドをパーソナライズ検索する技術トレンドアドバイザーを構築。シリーズの総集編として主要機能の統合手順と動作を検証する。

ai-agents
#bedrock#agentcore#agentcore-cli+5