Evals（評価）

評価（Evals）は、エージェントの動作が時間の経過とともにどのように変化するかを追跡するのに役立ちます。会話を「Eval」として保存すると、後でそれを再生して、エージェントの応答に変化があるかを確認できます。Evalsは正確性ではなく「一貫性」を測定します。つまり、動作が正しいか間違っているかではなく、動作が「変化したかどうか」を教えてくれます。

Evalsとは何か

Evalとは、再生可能な「保存された会話」のことです。Evalsを実行すると、cagentはユーザーメッセージを再生し、新しい応答を最初に保存された元の会話と比較します。スコアが高いほどエージェントが以前と同様に動作したことを意味し、スコアが低いほど動作が変化したことを意味します。

その情報をどう活用するかは、なぜその会話を保存したかによって異なります。回帰を検知するために成功した会話を保存することもあれば、既知の問題を記録し、それが改善されたかどうかを追跡するために失敗例を保存することもあります。

一般的なワークフロー

Evalsの使い方は、何を達成しようとしているかによって異なります。

回帰テスト（Regression testing）: エージェントがうまく機能した会話を保存します。後で変更（モデルのアップグレード、プロンプトの更新、コードのリファクタリングなど）を行った際に、Evalsを実行します。スコアが高い場合は動作に一貫性が保たれていることを意味し、通常はこれが望ましい状態です。スコアが低い場合は何かが変化したことを意味するため、新しい動作を調べて、それが依然として正しいかどうかを確認します。

改善の追跡（Tracking improvements）: エージェントが苦戦したり失敗したりした会話を保存します。改善を加えるたびにこれらのEvalsを実行し、動作がどのように進化するかを確認します。スコアが低い場合はエージェントの動作が変化したことを示しており、問題が修正された可能性があります。新しい動作が実際に良くなっているかどうかは、手動で確認する必要があります。

エッジケースの記録（Documenting edge cases）: 品質の良し悪しに関わらず、興味深い会話や珍しい会話を保存します。これらを使用して、エージェントがエッジケースをどのように処理するか、またその動作が時間の経過とともに変化するかどうかを理解します。

Evalsは「動作が変化したかどうか」を測定します。その変化が良いか悪いかを判断するのはあなたです。

Evalの作成

対話型セッションから会話を保存します。

$ cagent run ./agent.yaml

エージェントと会話を行い、それをEvalとして保存します。

> /eval test-case-name
Eval saved to evals/test-case-name.json

会話は現在の作業ディレクトリ内の evals/ ディレクトリに保存されます。必要に応じて、Evalファイルをサブディレクトリに整理することも可能です。

Evalsの実行

デフォルトディレクトリ内のすべてのEvalsを実行します。

$ cagent eval ./agent.yaml

カスタムEvalディレクトリを使用する場合：

$ cagent eval ./agent.yaml ./my-evals

レジストリ内のエージェントに対してEvalsを実行する場合：

$ cagent eval agentcatalog/myagent

出力例：

$ cagent eval ./agent.yaml
--- 0
First message: tell me something interesting about kil
Eval file: c7e556c5-dae5-4898-a38c-73cc8e0e6abe
Tool trajectory score: 1.000000
Rouge-1 score: 0.447368
Cost: 0.00
Output tokens: 177

結果の理解

各Evalについて、cagentは以下の項目を表示します。

• First message - 保存された会話の最初のユーザーメッセージ

• Eval file - 実行されているEvalファイルのUUID

• Tool trajectory score（ツール実行履歴スコア） - エージェントがどれほど同様にツールを使用したか（0〜1のスケール、高いほど良い）

• ROUGE-1  score - 応答テキストの類似度（0〜1のスケール、高いほど良い）

• Cost - このEval実行にかかったコスト

• Output tokens - 生成されたトークン数

スコアが高いほど、エージェントが記録された元の会話に近い動作をしたことを意味します。スコアが1.0の場合は、全く同一の動作であることを示します。

スコアの意味

Tool trajectory score は、エージェントが元の会話と同じツールを同じ順序で呼び出したかどうかを測定します。スコアが低い場合は、エージェントが問題を解決するために異なるアプローチを見つけた可能性を示唆しています。これは必ずしも間違いではありませんが、調査する価値があります。

Rouge-1 score は、応答テキストがオリジナルとどれほど似ているかを測定します。これはヒューリスティックな指標です。言い回しが異なっていても正解である場合があるため、絶対的な真理ではなく、一つのシグナルとして捉えてください。

結果の解釈

1.0に近いスコアは、変更を加えても一貫した動作が維持されていることを意味します。エージェントは同じアプローチをとり、同様の応答を生成しています。これは一般的に良い状態であり、変更によって既存の機能が壊れていないことを示します。

低いスコアは、保存された会話と比較して動作が変化したことを意味します。これは、エージェントのパフォーマンスが低下した「回帰（regression）」である可能性もあれば、より良いアプローチを見つけた「改善」である可能性もあります。

スコアが低下した場合は、実際の動作を調べて、それが以前より良くなったのか悪くなったのかを判断してください。Evalファイルは evals ディレクトリにJSONとして保存されています。ファイルを開いて元の会話を確認してください。次に、変更後のエージェントで同じ入力をテストし、応答を比較します。新しい応答の方が優れている場合は、新しい会話を保存してEvalを置き換えてください。悪くなっている場合は、回帰が見つかったことになります。

スコアは「何が変わったか」をガイドしてくれます。その変化が良いか悪いかを決定するのは、あなたの判断です。

Evalsを使用すべきとき

Evalsは、時間の経過に伴う動作の変化を追跡するのに役立ちます。モデルや依存関係をアップグレードした際の回帰の検知、修正したい既知の失敗例の記録、反復作業に伴うエッジケースの変化の把握などに有用です。

Evalsは、どのエージェント構成が最適かを判断するためのものではありません。Evalsは保存された会話に対する「類似性」を測定するものであり、「正確性」を測定するものではないからです。異なる構成を評価し、どちらがより優れているかを決定するには、手動テストを行ってください。

追跡する価値のある会話を保存しましょう。重要なワークフロー、興味深いエッジケース、既知の問題のコレクションを構築してください。変更を加えた際にEvalsを実行し、何がシフトしたかを確認してください。

次のステップ

• cagent eval のすべてのオプションについては、CLIリファレンスを確認してください

• 効果的なエージェントを構築するための ベストプラクティス を学ぶ

• さまざまなエージェントタイプの 設定例  を確認する