評価を CI に組み込む手順
Promptfoo 0.124.1とGitHub Actionsで、AIエージェントの引き継ぎ処理を変更時に検査する例です。固定入力、採点、失敗時の記録、必須チェックまでを具体的な設定でつなぎます。
要点
- 評価をCIに組み込むには、固定した入力で変更対象の処理を呼び、期待した結果と実際の操作を採点します。
- Promptfooなら、試験ケースと判定をYAMLで管理し、終了コードをGitHub Actionsの成否へ接続できます。
- 必須ケースは全件実行・全件合格を条件にし、採点不能や実行失敗も取り込みを止める扱いにします。
- 固定した模擬入力の成功は、モデルの判断や本番システムまで確認したことにはなりません。
定義
- provider
- 評価ツールと試験対象をつなぐ部品です。
- Promptfoo
- 入力、実行先、採点条件を設定ファイルへまとめるOSSの評価ツールです。
CI(継続的インテグレーション、continuous integration)は、コードや設定の変更を取り込む前に、自動検査を繰り返す仕組みです。回帰評価は、以前できていた振る舞いが変更で壊れていないかを調べます。AIエージェントでは、返答の文章だけでなく、依頼した操作が実際に行われたかも対象になります。
例えば、問い合わせ対応エージェントが「担当者へ引き継ぎました」と返しても、担当窓口に受付記録がなければ仕事は完了していません。ここでは、この食い違いを検出する最小例を作ります。問い合わせ、受付先、IDはすべて架空です。実際に試す場合も、許可された試験環境を使います。
Promptfooを使う範囲
Promptfooは、入力、実行先、採点条件を設定ファイルへまとめるOSSの評価ツールです。独自のJavaScript処理を呼ぶproviderを作れるため、返答と操作記録を同時に採点できます。providerは、評価ツールと試験対象をつなぐ部品です(PromptfooのJavascript Provider)。
この例では、モデルが選んだ「引き継ぐ」「追加情報を求める」という判断を固定します。検査するのは、その判断を受けた後の処理です。モデルAPI、実際の問い合わせ窓口、LLMによる採点は呼びません。モデルを固定回答に置き換えているので、質問から正しい判断を選べる能力は評価していません。
道具は、すでにある試験の仕組みと、記録したい単位に合わせて選びます。
| 選択肢 | 合う条件 | この例との違い |
|---|---|---|
| Promptfoo | 同じケースを複数の実行先へ渡し、出力と採点結果を共通形式で残したい | YAMLのケースとproviderを分離できる |
| pytest | Pythonの関数や処理後の状態を、既存のテスト群で検査したい | Pythonのassertで直接判定する。Promptfooの追加が必須ではない |
pytestの公式入門も、関数の返り値をassertで検査し、期待との差を失敗として報告する例を示しています(pytest Get Started)。ここでPromptfooを選ぶ理由は、業務処理と後から追加するモデル評価を、同じケース形式で扱えるようにするためです。
固定入力で引き継ぎを検査する手順
以下は独自に作った教材用コードです。Promptfooの公式サンプルや、実サービスの実装を転載したものではありません。
- 空の試験用ディレクトリを用意し、Node.js 22.22.0を使います。Promptfoo 0.124.1のpackage.jsonはNode.js 22.22.0以上を要求します。
- 次のコマンドでPromptfooの版を固定します。生成したpackage.jsonとpackage-lock.jsonも、コードや試験ケースと一緒に管理します。
src/finish-request.mjs、eval/provider.mjs、promptfooconfig.yamlを作ります。
npm init -y
npm install --save-dev --save-exact promptfoo@0.124.1src/finish-request.mjsは変更対象となる処理です。引き継ぎの場合は、受付先が返したIDを結果に入れます。追加情報を求める場合は受付を作りません。
export async function finishRequest(decision, tools) {
if (decision.action === 'ask') {
return { status: 'needs_info', ticketId: null };
}
if (decision.action !== 'handoff') {
throw new Error('Unsupported action');
}
const ticket = await tools.createTicket({
queue: 'it-helpdesk',
caseId: decision.caseId,
});
return { status: 'handed_off', ticketId: ticket.id };
}eval/provider.mjsは、実際の受付サービスを配列で代用します。試行ごとに新しい配列を作るため、前の試行の受付記録は残りません。採点する記録は、返答に含まれる自己申告ではなく、模擬受付へ実際に渡された内容です。
import { finishRequest } from '../src/finish-request.mjs';
export default class HandoffProvider {
id() { return 'handoff-fixture'; }
async callApi(_prompt, context) {
const tickets = [];
const result = await finishRequest({
action: context.vars.action,
caseId: context.vars.caseId,
}, {
async createTicket(input) {
const ticket = { id: 'T1', ...input };
tickets.push(ticket);
return ticket;
},
});
return { output: JSON.stringify({ result, tickets }) };
}
}Promptfooのproviderはid()とcallApi()を持ち、評価対象の値をoutputで返します。以下のpromptsはこの検査を識別する固定文字列で、モデルへ送る指示ではありません。varsが各ケースの入力です。
promptfooconfig.yamlでは、結果の状態と受付の件数・宛先・対象IDを判定します。assertionは、出力に適用する合否条件です。JavaScriptの判定がtrueなら合格、falseなら不合格になります(PromptfooのJavascript assertions)。
prompts:
- handoff-contract
providers:
- id: file://./eval/provider.mjs
tests:
- description: 引き継ぎは受付を一件作る
vars:
action: handoff
caseId: case-001
assert:
- type: javascript
value: |
const x = JSON.parse(output);
return x.result.status === 'handed_off'
&& x.tickets.length === 1
&& x.tickets[0].queue === 'it-helpdesk'
&& x.tickets[0].caseId === 'case-001'
&& x.result.ticketId === x.tickets[0].id;
- description: 情報不足なら受付を作らない
vars:
action: ask
caseId: case-002
assert:
- type: javascript
value: |
const x = JSON.parse(output);
return x.result.status === 'needs_info'
&& x.result.ticketId === null
&& x.tickets.length === 0;合格条件は「この二ケースを実行し、どちらも合格」です。平均点で片方の不合格を埋めません。二件という数や全件合格という条件は、この必須動作を扱う教材として決めたものであり、モデル全体の品質基準ではありません。
GitHub Actionsへ合否を接続する設定
次の.github/workflows/agent-eval.ymlは、プルリクエストごとに固定版をインストールして評価する設定例です。評価の終了コードを維持し、さらに実行件数とエラーを確認します。CLIの--no-cacheは評価結果の再利用を避け、--no-shareは結果共有を無効にします(PromptfooのCLI)。
name: Agent regression
on: pull_request
permissions:
contents: read
jobs:
evaluate:
runs-on: ubuntu-24.04
timeout-minutes: 10
env:
PROMPTFOO_DISABLE_TELEMETRY: '1'
PROMPTFOO_DISABLE_UPDATE: '1'
PROMPTFOO_PASS_RATE_THRESHOLD: '100'
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: '22.22.0'
package-manager-cache: false
- run: npm ci
- name: Evaluate required cases
run: >-
./node_modules/.bin/promptfoo eval
-c promptfooconfig.yaml --no-cache --no-share
-o eval-results.json
- name: Require two completed passes
run: |
node --input-type=module -e '
import { readFileSync } from "node:fs";
const { results } = JSON.parse(
readFileSync("eval-results.json", "utf8"));
const s = results.stats;
if (s.successes !== 2 || s.failures !== 0 ||
s.errors !== 0) process.exit(1);
'
- uses: actions/upload-artifact@v7
if: always()
with:
name: agent-eval-results
path: eval-results.json
if-no-files-found: error
eval-gate:
needs: evaluate
if: ${{ always() }}
runs-on: ubuntu-24.04
steps:
- env:
EVAL_RESULT: ${{ needs.evaluate.result }}
run: test "$EVAL_RESULT" = successこの例の10分はジョブを打ち切るための設定値です。ケースを増やす場合は、期待件数と必要時間も一緒に見直します。テレメトリーと更新確認の無効化はPromptfooの公式設定に従っています。依存パッケージの取得やGitHubへの結果保存は発生するため、通信を完全に遮断した構成ではありません。
eval-gateは、評価ジョブが成功した場合だけ成功します。always()は、依存先の失敗や省略でも判定ジョブへ進むために使います。GitHubの必須チェックはskippedやneutralも許容するため、評価ジョブを省略したまま合格扱いにしない構成が必要です(GitHubの依存ジョブ、必須チェック)。
設定ファイルを置くだけでは取り込みを禁止できません。対象ブランチの保護設定で、実行後に現れるeval-gateを必須チェックへ指定します。管理者の例外も含め、失敗・未実行・中断の状態を作ったときに、利用する取り込み経路が止まることを確認します。
評価の終了コードが非0の場合は、件数の確認へ進まず失敗になります。終了コードが0でも、成功2件・失敗0件・エラー0件を満たさなければ失敗です。always()により、失敗や省略の状態も判定ジョブへ届きます。判定ジョブはsuccessの場合だけ通過します。この判定で取り込みを止めるには、ブランチ保護でeval-gateを必須チェックに指定しておく必要があります(図 6.1.1 評価ジョブとeval-gateの合否判定)。
赤くなった結果の読み方
失敗経路を確かめるには、試験用の変更でfinishRequest内の受付呼び出しをconst ticket = { id: 'T1' };へ置き換えます。返り値が引き継ぎ済みを示していても、ticketsが空なので最初のケースは不合格になります。期待結果を変更して通すのではなく、受付を作らなくなった処理を直す場面です。
結果はeval-results.jsonへ保存します。集計だけでなく、そのケースの出力、採点理由、エラーを読みます。Promptfooの公式仕様では、評価不合格の終了コードは既定で100、その他のエラーは1です。どちらもCIでは非ゼロの失敗として扱い、コードだけで原因を決めずに記録を確認します。
| 結果 | この例で確認すること | 対応 |
|---|---|---|
| 引き継ぎケースの不合格 | 受付件数、宛先、返り値のID | 処理の抜けか採点条件の誤りかを切り分ける |
| 読み込みや実行のエラー | providerのパス、構文、例外 | 評価を実行できる状態へ直す |
| 二件未満しか成功していない | ケースの削除、省略、実行失敗 | 全件を実行するまで必須条件を満たしたとしない |
| 結果ファイルがない | セットアップや評価の中断 | 記録不足を成功へ置き換えない |
掲載したJavaScript部分は、Node.js 24.14.1を使い、正常な二ケースと受付を作らない変更の挙動を通信なしで確認しています。掲載CIのNode.js 22.22.0、Promptfoo CLI、GitHub Actionsでの一連の実行は未実施です。上の表は保存する情報の読み方であり、実CIの成功ログではありません。
赤い結果を PR に書き残す項目
以下は架空の記入例で、実 CI のログではありません。上の失敗経路を試した変更なら、PR のコメントか評価記録に次の項目を残します。
| 項目 | 記入例(架空) |
|---|---|
| 対象 commit | 変更後の commit の短縮ハッシュ |
| 失敗したケース | 引き継ぎは受付を一件作る |
| 判定に使った値 | result.status は handed_off、tickets.length は 0 |
| 分類 | 処理の抜け(採点条件は変えていない) |
| 対応 | finishRequest の createTicket 呼び出しを戻す。期待結果は変えない |
| 再実行 | 修正後の commit で、成功2件・失敗0件・エラー0件を確かめる |
ケースを3件に増やす PR では、promptfooconfig.yaml へのケースの追加と、件数を確認するステップの期待値・ステップ名の変更を、同じ PR に入れます。この判定は件数の厳密な一致を求めます。そのため片方だけ変えると、全件が合格しても件数の確認で失敗します。期待件数を減らす変更では、ケースを外した理由を PR の本文に書き、レビューで確かめます。
公開されているAWSの参照実装
AWS Solutions Libraryは、保険関連の問い合わせを分類する生成AI評価の参照実装を公開しています。2026年10月9日に確認したREADMEによると、CSVの分類ケースをPromptfooへ渡し、Claude 3.5 HaikuとAmazon Nova Microを比較する構成です。
READMEは、lambda/prompt.pyのプロンプトを評価し、開発者が変更提案を承認した後で、Amazon BedrockのプロンプトとLambdaへの反映を行う流れを説明しています。ここから読み取れる実装上の要点は、入力データ、期待する分類、実行先、評価と配布の段階を分けていることです。
これはAWSの公開参照実装です。顧客企業の本番導入実績や、品質改善を測定した研究結果ではありません。この資料の説明を使って特定のモデルの優位性や費用削減を主張することもできません。今回確認したのはREADMEの構成説明で、AWSへの配布や、そのリポジトリのワークフロー実行結果は確認していません。
モデルも含めて測る場合の境界
実際のエージェント全体を評価する際は、providerから固定判断の代わりに、変更対象のエージェントを呼びます。検索資料と初期状態を試験用に固定し、外部への操作先は模擬機能または許可した試験環境へ向けます。モデルの返答が「完了」と言っていることと、受付や予約が作られたことは別に採点します。
モデルの版、指示、検索対象、評価ケース、採点条件、試行数、キャッシュ条件を記録します。変更前後を比べる場合も、同じケースと基準で測ります。生成やLLM採点を使うと結果は揺れ得るため、反復回数と判定規則は実行前に決め、通った回だけを残しません。
この最小例が守るのは、指定した判断に対する引き継ぎ処理です。自然な質問の理解、検索の正確さ、案内文の妥当性、実サービスでの操作完了は別の評価範囲です。CIの緑色が何の成功を示すのかを、この境界とともに記録します。
自社での取り組みについて相談する
AI エージェントの評価方法や品質の確認について、株式会社UNIQUEX にご相談いただけます。
記事のタイトルと URL をお問い合わせフォームへ引き継ぎます。実現したいこと・困っていることをお書きください。
UNIQUEX に相談する