MemexMemex/ブログ
← 戻る

dart_agent_core Evals：Dart と Flutter のための Agent 評価

Demystifying evals for AI agents Anthropic の Claude engineering チームは、この記事で Agent 評価を task、trial、grader、transcript、outcome、evaluation harness、agent harness、evaluation suite という一連の概念に分解しています。dart_agent_core の eval サブシステムは、この Claude-style の考え方を Dart と Flutter のチームがそのまま使える API として実装したものです。

解きたい問題ははっきりしています。Flutter Agent を作るときにも、Claude チームが Claude Code を評価するときと同じ問いを立てられるようにしたい。Agent は本当にタスクを完了したのか、それとも完了したと言っているだけなのか。prompt の変更は能力を上げたのか、安定性を犠牲にしたのか。モデル変更によって tool call、cost、特定のタスク群での regression はどう動いたのか。

なぜ eval は Dart Agent stack の中にあるべきか

多くの Agent 評価ツールは Python や TypeScript のサーバー環境を前提にしています。Backend Agent なら自然ですが、mobile-first のプロダクトでは話が変わります。Memex の Agent は Flutter app の中で動き、プロダクト側の Dart tools をそのまま使い、ローカルファイルや app state を変更します。評価だけを外部 framework に移すと、実際の実行環境から離れた agent harness をもう一つ作ることになります。

package:dart_agent_core/eval.dart は、evaluation harness を agent harness のすぐ隣で動かすための層です。本番で使っている StatefulAgent、Tool、AgentController、LLMClient、local services をそのまま eval に入れられます。Claude の記事で重要なのは、評価対象がモデル単体ではなく、モデルと scaffold を合わせたシステムだという点です。

Claude の概念を dart_agent_core に落とす

  • Task に対応します EvalTask.
  • Trial に対応します Trial.
  • Grader に対応します CodeGrader, ModelGrader, and HumanGrader.
  • Transcript に対応します Transcript.
  • Outcome に対応します Outcome.
  • Evaluation harness に対応します EvalRunner.
  • Agent harness に対応します AgentHarnessFactory and AgentHarnessSession.
  • Evaluation suite に対応します EvalSuite.

最初の dart_agent_core eval を実行する

  • EvalTask を作り、入力、metadata、成功条件を明確にする。
  • EvalEnvironment を実装し、各 trial に独立した workspace や app state を用意する。
  • AgentHarnessFactory を実装し、eval から実際の Dart Agent を起動できるようにする。
  • 検証したい内容に応じて CodeGrader、ModelGrader、HumanGrader を選ぶ。
  • EvalRunner で EvalSuite を実行し、pass@k、pass^k、cost、latency、trace を比較する。
final task = EvalTask(
  id: 'create_sleep_note',
  input: 'Create a sleep note from this journal entry.',
  successCriteria: ['A note exists', 'The note is filed under Health'],
  graders: [SleepNoteOutcomeGrader()],
);

final suite = EvalSuite(
  id: 'pkm_agent_smoke',
  tasks: [task],
  trialCount: 3,
);

final report = await EvalRunner(
  environment: PkmEvalEnvironment(workspaceDir),
  harnessFactory: const PkmAgentHarnessFactory(),
).runSuite(runName: 'pkm_agent_smoke', suite: suite);

まず outcome、必要なときに transcript

Claude の記事が繰り返し強調しているのは、Agent が言ったことと、trial の後に世界がどう変わったかは別物だという点です。dart_agent_core でもこの線引きを保っています。最終状態を確かめるときは Outcome を見る。途中の手順や制約を確かめるときは Transcript を見る。

万能の score ではなく三種類の grader

  • Code-based grader は、state、schema、file diff、tool call のように決定的に検証できるものに向いています。
  • Model-based grader は、rubric を使って主観的な品質を LLM-as-judge で評価するためのものです。
  • Human grader は、モデルの判断を人間の判断に合わせて校正し、必要なところをレビューするために使います。

Capability suite と regression suite

Capability eval は、Agent がある種類のタスクを少なくとも解けるかを見るものです。Regression eval は、すでに安定した振る舞いが今も毎回保たれているかを見るものです。この違いは EvalSuite、pass@k、pass^k の扱いにそのまま現れます。

非決定性：pass@k と pass^k

pass@k は「k 回の試行のうち少なくとも一回成功したか」を表します。pass^k は「k 回すべて成功したか」を表します。前者は capability の探索に向いていて、後者はユーザーが実際に感じる reliability に近い指標です。

Record、replay、trace、inspect

CI の cost とノイズを抑えるために、RecordingLLMClient は実モデルへの request/response を保存します。ReplayLLMClient は CI でそれを再生し、cache miss は失敗として扱います。trace は JSONL に書き出したり、Langfuse に送ったり、transcript CLI で確認したりできます。

Suite health と judge calibration

Claude の記事が指摘している通り、eval suite は saturation も drift も起こしますし、そもそも間違ったものを測ってしまうこともあります。SuiteHealthAnalyzer は graduation candidate、broken task、suite がまだ有効な slope を出しているかを見ます。JudgeCalibrator は LLM judge と人間がラベルした golden set を比較し、Spearman、Pearson、MAE を出します。

Flutter Agent チームに何をもたらすか

この設計は Anthropic の Claude eval 記事をはっきり意識しています。新しい用語を作るのではなく、Claude の記事に出てくる task、trial、grader、transcript、outcome、evaluation harness、agent harness、evaluation suite を Dart API として実装し、Flutter チームに必要な local workspace、controller transcript、record/replay、JSON suite、Langfuse export、suite health、judge calibration を足しました。

dart_agent_core は pub.dev で公開されています。eval guide は dart_agent_core repository にあり、概念の出発点は Anthropic の Claude agent eval guide です。

pub.dev · dart_agent_core repository · Claude agent eval guide