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 바로 옆에서 실행하게 하는 것입니다. production에서 쓰는 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를 봅니다.

만능 점수 하나가 아니라 세 종류의 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