mcpField
C
cxas-sim-eval

cxas-sim-eval

github.com/googlecloudplatformテスト・品質11370 回インストール今日更新
リポジトリ

cxas-sim-eval について

cxas-sim-evalは、CXASのターン単位のゴールデン評価を、SCRAPI SimulationEvals向けの目標指向テストケースに変換します。エージェント評価を行う開発者向けで、ツール設定とスキーマから期待値を推定し、評価の実行やHTMLレポート生成も行えます。

主な機能

  1. 01評価とエージェントのツール設定を取得
  2. 02利用可能なツールの全スキーマを取得
  3. 03評価をシミュレーションテストに変換
  4. 04評価を実行してHTMLレポートを生成
  5. 05推論診断を分析して改善案を提示

活用シーン

  1. 01CXASゴールデン評価をシミュレーションテストに変換
  2. 02エージェントのテストにツール呼び出しの期待値を追加
  3. 03評価を実行して失敗原因を確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/googlecloudplatform/cxas-scrapi --skill cxas-sim-eval

インストール後、Claude Code で/cxas-sim-evalを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

scripts/
convert_eval.py
fetch_app_data.py
fetch_tool_schemas.py
run_evals.py

詳細

CXAS 評価からシミュレーションへの変換ツール

このスキルは、ターンごとの CXAS のゴールデン評価を、SCRAPI の SimulationEvals フレームワーク向けの高レベルで目標指向のテストケースに変換するのに役立ちます。エージェントのツールを分析し、具体的なツール呼び出しを用いて期待値を充実させます。

手順

1. 環境を確認する

cxas_scrapi が Python パッケージとしてインストールされていることを確認します。次のコマンドを実行して確認できます。

python -c "import cxas_scrapi"

gcloud が適切に認証されていることを確認します。

gcloud auth list

必要に応じて、次のコマンドでログインします。

gcloud auth login
2. アプリ名と出力ディレクトリを取得する

重要

実行手順に進む前に、アプリ／エージェントの完全なリソース名（例：projects/.../locations/.../apps/...）とベース出力ディレクトリを必ずユーザーに尋ねてください。

ユーザーにこれらの値を尋ねます。

3. 評価を取得する

CES API を使用して評価の一覧を取得します。各評価を、表示名をファイル名として [output_dir]/golden_evals/ に JSON ファイルで保存します。

4. ツールスキーマを取得する

アプリで利用可能なすべてのツールの完全なスキーマを取得し、[output_dir]/tools/ に保存します。

5. エージェントのツール設定を取得する

エージェントが使用するツールとツールセットの一覧を取得し、設定を保存します（例：[output_dir]/agent_tools.json）。

6. 評価を変換する

変換スクリプト（convert_eval.py）を実行して、取得した評価を処理し、変換後のテストケースを [output_dir]/sim_evals/ に保存します。

自動化スクリプト

このプロセスを自動化するために、3 つのスクリプトを利用できます。

1. 評価とエージェント設定を取得する

scripts/fetch_app_data.py

CES API から評価とエージェントが使用するツールの一覧を取得します。

使用方法：

python .agents/skills/cxas-sim-eval/scripts/fetch_app_data.py \
  --app-name "projects/.../locations/.../apps/..." \
  --output-dir /path/to/output_directory
2. ツールスキーマを取得する

scripts/fetch_tool_schemas.py

アプリで利用可能なすべてのツールの完全なスキーマを取得します。

使用方法：

python .agents/skills/cxas-sim-eval/scripts/fetch_tool_schemas.py \
  --app-name "projects/.../locations/.../apps/..." \
  --output-dir /path/to/output_directory
3. 評価を変換する

scripts/convert_eval.py

取得したツールスキーマを使用して期待値を推定し、取得した評価をシミュレーションのテストケースに変換します。

使用方法：

python .agents/skills/cxas-sim-eval/scripts/convert_eval.py \
  --output-dir /path/to/output_directory \
  --parallelism 5
4. 評価を実行する

scripts/run_evals.py

シミュレーション評価を実行し、生の結果をログに記録して、統合 HTML レポートを生成します。

認知診断分析： intercept_and_score_reasoning ツールがエージェントで有効になっている場合、このスクリプトは失敗した評価について、エージェントの内部独白を自動的に抽出して分析します。考えすぎ、ためらい、後戻りなどの問題を検出します。さらに、これらの診断結果をエージェントの指示と照合し、HTML レポート内に改善のための実行可能な提案を直接生成します。

使用方法：

python .agents/skills/cxas-sim-eval/scripts/run_evals.py \
  --app-name "projects/.../locations/.../apps/..." \
  --output-dir /path/to/output_directory \
  --parallelism 5 \
  --start-index 0 \
  --end-index 10

認知診断の解釈

intercept_and_score_reasoning ツールを有効にして評価を実行すると、システムは診断情報を抽出し、エージェントの推論における問題の特定を支援します。

主なシグナル

  1. 考えすぎ（冗長さ）

    • 症状：内部独白が 350 文字または 600 文字を超えます。
    • 意味：エージェントが複雑な指示や循環的な指示の処理に苦労しています。
    • 対処法：指示を簡潔にします。複雑なタスクを、小さく直線的な手順に分割します。

  2. 曖昧な表現

    • 症状：「might be」、「guess」、「unsure」、「assume」などの語句を使用します。
    • 意味：多くの場合、エッジケースへの対応が不足しているため、エージェントは次の行動に確信を持てていません。
    • 対処法：エージェントが判断に迷うシナリオについて、明示的な指示を追加します。

  3. 後戻り

    • 症状：「wait」、「actually」、「on second thought」などの語句を使用します。
    • 意味：エージェントがターンの途中で計画を放棄したり、自己修正したりしています。これは、トリガーが不明確であることを示しています。
    • 対処法：指示内のトリガーと状態遷移を明確にします。

コメント

Markdown 対応