第 6 章 回帰試験と CI6.1

評価を CI に組み込む手順

Promptfoo 0.124.1とGitHub Actionsで、AIエージェントの引き継ぎ処理を変更時に検査する例です。固定入力、採点、失敗時の記録、必須チェックまでを具体的な設定でつなぎます。

要点

  1. 評価をCIに組み込むには、固定した入力で変更対象の処理を呼び、期待した結果と実際の操作を採点します。
  2. Promptfooなら、試験ケースと判定をYAMLで管理し、終了コードをGitHub Actionsの成否へ接続できます。
  3. 必須ケースは全件実行・全件合格を条件にし、採点不能や実行失敗も取り込みを止める扱いにします。
  4. 固定した模擬入力の成功は、モデルの判断や本番システムまで確認したことにはなりません。

定義

provider
評価ツールと試験対象をつなぐ部品です。
Promptfoo
入力、実行先、採点条件を設定ファイルへまとめるOSSの評価ツールです。

CI(継続的インテグレーション、continuous integration)は、コードや設定の変更を取り込む前に、自動検査を繰り返す仕組みです。回帰評価は、以前できていた振る舞いが変更で壊れていないかを調べます。AIエージェントでは、返答の文章だけでなく、依頼した操作が実際に行われたかも対象になります。

例えば、問い合わせ対応エージェントが「担当者へ引き継ぎました」と返しても、担当窓口に受付記録がなければ仕事は完了していません。ここでは、この食い違いを検出する最小例を作ります。問い合わせ、受付先、IDはすべて架空です。実際に試す場合も、許可された試験環境を使います。

Promptfooを使う範囲

Promptfooは、入力、実行先、採点条件を設定ファイルへまとめるOSSの評価ツールです。独自のJavaScript処理を呼ぶproviderを作れるため、返答と操作記録を同時に採点できます。providerは、評価ツールと試験対象をつなぐ部品です(PromptfooのJavascript Provider)。

この例では、モデルが選んだ「引き継ぐ」「追加情報を求める」という判断を固定します。検査するのは、その判断を受けた後の処理です。モデルAPI、実際の問い合わせ窓口、LLMによる採点は呼びません。モデルを固定回答に置き換えているので、質問から正しい判断を選べる能力は評価していません。

道具は、すでにある試験の仕組みと、記録したい単位に合わせて選びます。

選択肢合う条件この例との違い
Promptfoo同じケースを複数の実行先へ渡し、出力と採点結果を共通形式で残したいYAMLのケースとproviderを分離できる
pytestPythonの関数や処理後の状態を、既存のテスト群で検査したいPythonのassertで直接判定する。Promptfooの追加が必須ではない

pytestの公式入門も、関数の返り値をassertで検査し、期待との差を失敗として報告する例を示しています(pytest Get Started)。ここでPromptfooを選ぶ理由は、業務処理と後から追加するモデル評価を、同じケース形式で扱えるようにするためです。

固定入力で引き継ぎを検査する手順

以下は独自に作った教材用コードです。Promptfooの公式サンプルや、実サービスの実装を転載したものではありません。

  1. 空の試験用ディレクトリを用意し、Node.js 22.22.0を使います。Promptfoo 0.124.1のpackage.jsonはNode.js 22.22.0以上を要求します。
  2. 次のコマンドでPromptfooの版を固定します。生成したpackage.jsonとpackage-lock.jsonも、コードや試験ケースと一緒に管理します。
  3. src/finish-request.mjs、eval/provider.mjs、promptfooconfig.yamlを作ります。
npm init -y
npm install --save-dev --save-exact promptfoo@0.124.1

src/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の合否判定)。

評価ジョブとeval-gateの合否判定プルリクエストで評価を実行し、終了コードと件数・エラーの確認を通った場合だけ評価ジョブが成功する流れ。失敗や省略も判定ジョブへ進み、成功以外は取り込みを止める。終了0非0はいいいえalways実行成功それ以外プルリクエストpromptfooeval2件合格でエラー0?失敗・省略中断evaluate成功evaluateの結果は成功?必須チェック通過取り込み停止
図 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 に相談する

参考文献

  1. Promptfoo. Promptfoo 0.124.1 — Promptfoo、2026-10-08リリース、0.124.1タグとpackage.jsonのNode要件を2026-10-09確認(参照日 2026-10-09)
  2. Promptfoo. Javascript Provider — Promptfoo、2026-10-09公開Web本文確認。0.124.1タグのProvider Interface・Configurationと照合(参照日 2026-10-09)
  3. Promptfoo. Javascript assertions — Promptfoo、2026-10-09公開Web本文確認。0.124.1タグの真偽値・output・contextと照合(参照日 2026-10-09)
  4. Promptfoo. Command line — Promptfoo、0.124.1タグのevalオプション・終了コード・環境変数と2026-10-09の公開本文を照合(参照日 2026-10-09)
  5. Promptfoo. Output Formats — Promptfoo、0.124.1タグのJSON出力。集計フィールドは同タグsrc/models/eval.tsも確認(参照日 2026-10-09)
  6. Promptfoo. Telemetry Configuration — Promptfoo、2026-10-09公開本文、Telemetry・Updates(参照日 2026-10-09)
  7. GitHub. Workflow syntax for GitHub Actions — GitHub Docs、2026-10-09公開本文、needs・jobs.if・always・permissions(参照日 2026-10-09)
  8. GitHub. About protected branches — GitHub Docs、2026-10-09公開本文、必須チェックと管理者の例外(参照日 2026-10-09)
  9. GitHub. GitHub Actions checkout — GitHub、2026-10-09公式README、v7の使用例(参照日 2026-10-09)
  10. GitHub. GitHub Actions setup-node — GitHub、2026-10-09公式README、v7のnode-version・package-manager-cache(参照日 2026-10-09)
  11. GitHub. GitHub Actions upload-artifact — GitHub、2026-10-09公式README、v7のpath・if-no-files-found(参照日 2026-10-09)
  12. AWS Solutions Library. Guidance for Evaluating Generative AI Applications using OSS on AWS — AWS Solutions Library、2026-10-09確認時の公開main README。Overview・How It Works・Configuration Files・CI/CD Evaluation Workflow(参照日 2026-10-09)
  13. pytest developers. Get Started — pytest documentation、2026-10-09のstable文書、表示例9.1.1、Create your first test(参照日 2026-10-09)
  14. Anthropic. Demystifying evals for AI agents (2026) — Anthropic、元版の関連資料(資料 #16)。今回の最小例のAPI・実行結果の根拠ではない。旧版での確認範囲: 2026年1月9日公開、The structure of an evaluation、Capability vs. regression evals、How to think about non-determinism、Step 4〜6(参照日 2026-10-09)
  15. OpenAI. Evaluation best practices — OpenAI、元版の関連資料(資料 #18)。今回の最小例のAPI・実行結果の根拠ではない。旧版での確認範囲: 版・更新日の表示なし、2026年10月9日取得、Design your eval process(参照日 2026-10-09)
  16. Promptfoo. Testing Prompts with GitHub Actions — Promptfoo、元版の関連資料(資料 #31)。今回の最小例のAPI・実行結果の根拠ではない。旧版での確認範囲: 2026年10月8日更新、冒頭・Using the GitHub Action・Configuration・How It Works(参照日 2026-10-09)
  17. Confident AI. Unit Testing in CI/CD — DeepEval Documentation、元版の関連資料(資料 #32)。今回の最小例のAPI・実行結果の根拠ではない。旧版での確認範囲: ページ固有の版・更新日表示なし、2026年10月9日取得、How It Works・Handling Flaky Test Cases・YAML File For CI/CD Evals・FAQs(参照日 2026-10-09)

更新履歴

  • 初版。公式資料の確認済み箇所を根拠に編集。問い合わせと運用手順は架空の説明例。実CIでの実行は行っていない。
  • 評価結果を必須チェックと取り込み制限へ接続する説明を補足。実設定は未変更
  • Promptfooの固定版API、最小設定、失敗例とAWS公開参照実装を追加。JavaScript部分の通信なし確認と、未実行のCLI・GitHub Actionsを区別。
  • 用語集に定義を追加
  • 実行環境の説明を整理。
  • 日本語表現を校正し、助詞・語順・主語と述語の対応を改善
  • 主題の関係を説明する図を追加
  • 入力例、判定の分岐、結果として残す記録を具体化。
  • 本文と更新履歴の説明を簡潔化

Markdown 版