adk-evals

ADK Evals スキル

Evals とは？

Evals は ADK エージェント用の自動会話テストです。各 eval ではシナリオ（ユーザーメッセージまたはイベントのシーケンス）を定義し、ボットが行うべきこと（発言内容、呼び出すツール、状態の変化、実行するワークフローなど）をアサートします。

Evals は稼働中の開発用ボット（adk dev）に対して実行されるため、モックではなく、スタック全体をテストできます。

このスキルを使うタイミング

開発者から次のような質問があった場合に、このスキルを使います。

• eval の作成 — ファイル形式、アサーション、ターンの種類、セットアップ
• eval の実行 — CLI コマンド、フィルタリング、出力の解釈
• 特定のプリミティブのテスト — アクション、ツール、ワークフロー、会話、状態のテスト方法
• テストの反復サイクル — 作成 → 実行 → トレースを確認 → 反復
• CI との連携 — 終了コード、--format json フラグ、タグ付けの方法
• eval の設定 — idleTimeout、judgePassThreshold、judgeModel

または、ADK ボットを開発していて、単体テスト／エンドツーエンドテストに相当するものを作成する必要がある場合にも使います。

質問の例：

• 「eval はどう書けばよいですか？」
• 「ワークフローをテストするにはどうすればよいですか？」
• 「特定のパラメーターでツールが呼び出されたことをどうアサートすればよいですか？」
• 「eval が失敗します。どうデバッグすればよいですか？」
• 「ボットが応答しないことをテストするにはどうすればよいですか？」
• 「CI で eval を実行するにはどうすればよいですか？」
• 「eval の前に状態をシードするにはどうすればよいですか？」
• 「eval でワークフローをトリガーするにはどうすればよいですか？」

利用可能なドキュメント

ファイル	内容
references/eval-format.md	ファイル形式の全容 — すべてのフィールド、ターンの種類、アサーションのカテゴリ、一致演算子、セットアップ、結果、オプション
references/testing-workflow.md	eval の実行、出力の解釈、トレースの使用、作成 → テスト → 反復のサイクル、CI との連携
references/test-patterns.md	アクション、ツール、ワークフロー、会話、状態それぞれのプリミティブ別パターン

回答方法

1. eval の作成 → 構造とアサーションについて eval-format.md を読みます
2. eval の実行 → CLI コマンドと出力について testing-workflow.md を読みます
3. 特定のプリミティブのテスト → 該当するセクションについて test-patterns.md を読みます
4. 失敗のデバッグ → testing-workflow.md（トレースの確認）と eval-format.md（アサーション構文の確認）を組み合わせます

---

クイックリファレンス

Eval ファイルの構造

import { Eval } from '@botpress/evals'

export default new Eval({
  name: 'greeting',
  type: 'regression',
  tags: ['basic'],

  setup: {
    state: { bot: { welcomeSent: false } },
    workflow: { trigger: 'onboarding', input: { userId: 'test-1' } },
  },

  conversation: [
    {
      user: 'Hi!',
      assert: {
        response: [{ not_contains: 'error' }, { llm_judge: 'Response is friendly and offers to help' }],
        tools: [{ not_called: 'createTicket' }],
        state: [{ path: 'conversation.greeted', equals: true }],
      },
    },
  ],

  outcome: {
    state: [{ path: 'conversation.greeted', equals: true }],
  },

  options: {
    idleTimeout: 60000,
    judgePassThreshold: 4,
  },
})

ターンの種類

ターン	使用する場面
user: 'message'	標準的なユーザーメッセージ
event: { payload }	カスタムイベントをプッシュする（chat:custom として到着）
expectSilence: true	ボットが応答しないことをアサートする

アサーションのカテゴリ

カテゴリ	確認する内容
response	ボットの応答テキスト（contains、not_contains、matches、llm_judge）
tools	ツール呼び出し（called、not_called、call_order、params）
state	ボット／ユーザー／会話の状態（equals、changed）
workflow	ワークフローの実行（entered、completed）
timing	応答時間（ミリ秒）（lte、gte）

CLI コマンド

adk evals                        # run all evals
adk evals <name>                 # run one eval
adk evals --tag <tag>            # filter by tag
adk evals --type regression      # filter by type
adk evals --verbose              # show all assertions
adk evals --format json          # JSON output for CI

adk evals runs                   # list recent runs
adk evals runs --latest          # most recent run
adk evals runs --latest -v       # with full details

---

重要なパターン

✅ すべてのターンには user または event が必要です

// CORRECT
{ user: 'hello', expectSilence: true }
{ event: { payload: { kind: 'payment.failed' } }, expectSilence: true }

❌ expectSilence だけでは有効なターンになりません

// WRONG — missing user or event
{
  expectSilence: true
}

---

✅ ツールパラメーターをアサートして、正しく抽出されたことを確認します

// CORRECT — verifies the LLM extracted the right values
{ called: 'createTicket', params: { priority: { equals: 'high' } } }

❌ ツールが呼び出されたことだけをアサートする

// INCOMPLETE — doesn't verify params were correct
{
  called: 'createTicket'
}

---

✅ 会話後の状態やワークフローのアサーションには outcome を使用します

// CORRECT — final state checked once after all turns
outcome: {
  state: [{ path: 'conversation.resolved', equals: true }],
  workflow: [{ name: 'ticketFlow', completed: true }],
}

---

✅ セットアップのターンを実行せずに条件付き動作をテストするには、状態をシードします

// CORRECT — start in a known state
setup: {
  state: {
    user: { plan: 'pro' },
    conversation: { phase: 'support' },
  },
}

❌ 会話のターンを使って状態をセットアップする（遅く、壊れやすい）

// WRONG — depends on the bot correctly processing setup turns
conversation: [
  { user: 'I am on the pro plan' }, // hoping bot sets user.plan
  { user: 'I need help with billing' }, // actual test turn
]

---

質問例

eval の作成：

• 「createTicket ツールが適切な優先度で呼び出されるかテストする eval を作成してください」
• 「内部イベントの後にボットが応答しないことを、どうアサートすればよいですか？」
• 「コンテキストが保持される複数ターンの会話を、どうテストすればよいですか？」

eval の実行：

• 「回帰 eval だけを実行するには、どうすればよいですか？」
• 「どのアサーションが失敗したのか、またその理由を確認するにはどうすればよいですか？」
• 「eval を GitHub Actions に統合するには、どうすればよいですか？」

デバッグ：

• 「eval ではツールが呼び出されていないと表示されますが、呼び出されたと思います。確認するにはどうすればよいですか？」
• 「eval 中にボットが実際に行ったことを確認するには、どうすればよいですか？」

プリミティブごと：

• 「step.sleep() を使うワークフローをテストするには、どうすればよいですか？」
• 「状態がシードした値から変化したことを、どうテストすればよいですか？」

---

回答形式

質問に合わせて詳しさを調整してください。

簡単な質問（「利用できるアサーションは何ですか？」「eval を実行するにはどうすればよいですか？」）

直接回答し、該当する表または CLI コマンドを示してください。情報を求める質問に対して、eval ファイル全体を生成しないでください。

eval を作成する場合

1. 現実的なフィールド値を使った new Eval({}) の呼び出し全体を示します
2. インポートを含めます（import { Eval } from '@botpress/evals'）
3. 直感的でないアサーションを簡潔に説明します。アサーションの意味が明白な場合は省略します
4. 実行する CLI コマンドを提案します：adk evals <name>

失敗した eval をデバッグする場合

1. 失敗したアサーションを尋ねるか、表示します（expected / actual の差分）
2. Dev Console でトレースを開き、ボットが行ったことを確認するよう提案します
3. 問題が eval のアサーションにあるのか、ボットの動作にあるのかを特定します