quick-eval

範囲を限定して評価を実行する

選択した評価のみを実行し、その証拠から何が裏付けられるかを説明してください。 音声の場合、成功とみなすには、実際の音声会話と録音内容の確認が必要です。 リソースが保存されていることや、実行ステータスが完了していることだけでは不十分です。

事前確認と予算

お客様のコンテキストから、対象の組織、ワークスペース、API 環境を確認してください。認証しただけでは組織を特定できません。お客様のエージェント、ペルソナ、テストセットを再利用してください。実行前に、正確なケースとメトリクスの定義を確認してください。coval --agent agent doctor、リソースの context、--help を使用してください。シークレットを表示したり、マシン全体のアカウント設定を変更したりしないでください。

起動 ID、ケース、メトリクステスト、使用予算を記録するローカルのセッション台帳を作成してください。予算が指定されていない場合は、まず接続確認の呼び出しを1回、続いてスターター評価として会話を合計3回まで、イテレーション1回、同時実行数1を提案してください。これらは提案するためのデフォルトであり、予算の使用許可ではありません。すでに許可された回数があれば、それを遵守してください。プランや監査の依頼は、有料の呼び出しを許可するものではありません。より大きな範囲には明示的な予算が必要です。結果が決め手に欠けた後で、ひそかに範囲を拡大してはいけません。

具体的な計画を提示してください。ID、名前付きケース、メトリクス、イテレーションと同時実行数、ベース版と変更版、最大呼び出し回数、設定済みの1回あたりの実行時間、経過時間による停止条件を含めてください。費用には Coval、接続先のプロバイダー、メトリクステストが含まれます。Coval は、要求した ID 以外にも必須メトリクスや依存メトリクスを追加する場合があります。実際の出力を確認し、計画上のメトリクス数は要求した作業量として扱い、請求総額の正確な数とはみなさないでください。現在の料金がわかっている場合に限り、金額を提示してください。そうでない場合は、回数と所要時間の上限を報告してください。

呼び出し回数 = 選択したケース数 × イテレーション数 ×（1 + 変更数）（ペルソナごとの実行）。すべての実行について合算してください。変更版を1つ実行する場合も、ベースのエージェントが実行されます。同時実行数によって速度は変わりますが、呼び出し総数は変わりません。既存の出力を再採点する場合、新たな音声呼び出しは不要ですが、メトリクスの作業が発生します。再実行の予算は明示的に確保し、再試行を無料とみなさないでください。キャンセルしても、キューに入ったすべての呼び出しが直ちに停止するとは限りません。

リクエストを正確に作成して確認する

選択したテストセットの options.test_case_ids を明示的に指定してください。省略によってテストセット全体を実行したり、対応比較の際にランダムなサブセットに置き換えたりしないでください。現在の runs schema を確認してください。

{
  "agent_id":"<selected-agent-id>",
  "persona_id":"<selected-persona-id>",
  "test_set_id":"<selected-set-id>",
  "metric_ids":["<selected-metric-id>"],
  "options":{"test_case_ids":["<selected-case-id>"],"iteration_count":1,"concurrency":1},
  "metadata":{"display_name":"First evaluation - connection check"},
  "config_overrides":{"simulation_timeout_seconds":120}
}

実行時間の上書きが、現在の API／エージェントの種類でサポートされていることを確認してください。サポートされていない場合は、検証済みの保存済み上限を使用するか、上限を確認して解決するまで停止してください。既存のエージェントを、その設定をついでに変更する目的で変更してはいけません。起動後に作成されたリソースと実行のメタデータを確認してください。ローカルのプランによって、サーバー側で支出上限が適用されるわけではありません。

このインストール済みスキルのディレクトリにある、任意のローカル専用プランナーを使用してください。

python3 scripts/plan.py --launch run.json --remaining-simulations 3 --max-concurrency 1

--remaining-simulations は、このセッションで許可済みの残り予算です。複数のペルソナ／実行がある場合は、すべての起動リクエスト本文を1つの JSON 配列にまとめ、バッチ全体を検証してください。ヘルパーは、すべての起動について同じ残り予算を減算します。明示的なサブセット、正の上限、ベース版と変更版の合計、呼び出し上限を確認します。認証、リソースの所有権の検証、予算の確保、サーバー側での上限適用、起動は行いません。所有権とケースへの所属を確認するには、それぞれのリソースを個別に読み取ってください。リクエストの正確なコピーを保持してください。

1 回だけ起動して、その実行を追跡する

coval --agent runs launch --input-json @run.json

ok と終了コードを確認し、返された実行 ID をすぐに保存します。タイムアウトした場合や応答が曖昧な場合は、別の起動を検討する前に、最近の該当する実行を調べます。POST をむやみに再試行しないでください。API エラーは空の結果ではありません。

妥当な間隔（たとえば 20～30 秒）で coval --agent runs get <run-id> をポーリングし、終端状態になるか、合意した実時間の期限に達するまで続けます。ステータスの表記にはスペースが含まれる場合があるため、現在の応答を確認してください。runs watch でいつまでも待たないでください。期限に達したら、保留中の実行を報告し、その ID を保持します。最初の実行が遅いからといって、2 回目の実行を開始しないでください。キャンセルは、依頼された場合、または合意した停止ポリシーの対象となっている場合に限り、キャンセル後は結果の状態を確認します。

実行ステータスだけでなく結果を監査する

小規模な実行では、すべての会話と選択したメトリクスを確認します。

coval --agent simulated-conversations list --run-id <run-id> --page-size 100
coval --agent simulated-conversations get <simulation-id>
coval --agent simulated-conversations metrics <simulation-id>
coval simulated-conversations audio <simulation-id> -o <local-recording.wav>

一部の CLI バージョンではページネーショントークンが省略されます。完全な証拠を得るには、任意の読み取り専用ヘルパーを使って、ページネーションと厳密な実行 ID の照合を行いながら公開 API を取得できます。

python3 scripts/fetch_run.py --run-id <run-id> --workspace-id <workspace-id> --out run-evidence.json

このヘルパーは環境変数から COVAL_API_KEY を読み取り、https://api.coval.dev/v1 を使用して、トランスクリプトを含む非公開のローカルファイルを書き出します。キーを貼り付けたりエクスポートしたり、ターミナル出力に読み込んだりしないでください。--max-conversations は読み取り件数の上限を設定します（デフォルトは 100）。上限を超えると、完全性を黙って主張するのではなく、エラーになります。このヘルパーは公開本番 API 向けです。明示的に選択した別の環境を使う場合は、その環境のドキュメントに記載された API を使用し、同じスコープ指定とページネーションの確認を行ってください。ヘルパーを動作させるために、環境を黙って切り替えないでください。

スナップショットには、後から再スコアリングしても過去の証拠が黙って置き換わらないよう、置き換え済みのメトリクス出力も保持されます。意図した出力 ID とバージョンを選択してください。同じメトリクスに対する複数の出力は、会話数の追加分ではありません。基準のサブ値が欠けている場合や切り詰められていると示されている場合は、メトリクスの詳細全体を確認してください。スナップショットには生のランタイムメタデータは含まれません。モデルの来歴が重要な場合は、該当する出力を別途取得してください。

確認事項：

• 予測された呼び出し数と観測された呼び出し数、選択されたケース ID、ベースケース数と変更ケース数。
• 個々のステータスと終了理由、両方の会話参加者、および呼び出し側が実際にケースを実行したかどうか。シミュレーターやテスト設計の不具合とエージェントの不具合を区別します。
• 音声録音の取得と関連する音声区間。has_audio は利用可能かどうかを示すメタデータであり、聴取した証拠ではありません。署名付き録音リンクの公開は避けてください。
• 選択したすべてのメトリクスのステータスとカバレッジ。FAILED、SKIPPED、CANCELLED、欠損値および null 値は、未評価であり、ゼロや合格を意味しません。
• 値、単位、極性、説明、および基準ごとの詳細。正しい回答が呼び出し側の発言にのみ引用されている場合、アシスタントが正しく回答した証拠にはなりません。
• 記録されたメトリクスのバージョン／モデルメタデータと、プロンプト／設定のスナップショット。過去のバージョンを示す証拠が得られない場合は、今日の定義で代用せず、その旨を伝えてください。

トランスクリプトまたはメトリクス結果の取得が遅れている場合は、同じ ID を対象に、読み取り専用のポーリングを上限付きで行います。自動的に再シミュレーションしないでください。レガシーの /eval/* フォールバックは使用しないでください。

報告して終了する

実際の実行 ID／リソース ID、依頼された数・観測された数・スコアリングされた数、実行上の失敗、品質に関する所見、不明点を、それぞれ分けて報告します。ユーザーの組織／ワークスペースのコンテキストで確認できたアプリ URL を使用してください。何を聴き、読み、測定したかを説明します。小規模な実行の成功はスモークテストであり、本番環境での発生率や統計的な信頼性を示すものではありません。生の証拠はローカルに保持し、共有時は機密情報をマスキングしてください。

結果に基づいて、次のステップを 1 つ提案します。自動的なヒルクライミング、エージェントのプロンプト変更、新しいケースの追加、メトリクスのデフォルト変更、スケジューリング、クリーンアップは行わないでください。