Схема наборов для оценки и правил проверки¶

Эта страница продолжает две соседние темы:

• Глава 13. Офлайн-оценки, онлайн-оценки и регрессионные шлюзы
• Схема трасс и каталог событий
• Сквозная цепочка доказательств: от запроса к решению о раскатке

И связывает их со справочным пакетом:

• Эталонный пакет

Если страница о схеме трасс отвечает на вопрос «как описывать то, что произошло внутри запуска», то эта страница отвечает на вопрос «как описывать то, чего мы ожидаем от системы на уровне оценочного артефакта».

Зачем нужна явная схема набора для оценки¶

Очень многие команды говорят, что у них «есть evals», но на практике под этим часто скрывается:

• таблица из нескольких ручных примеров;
• подборка несвязанных примеров для подсказок;
• JSON без устойчивой структуры;
• смесь эталонного ответа, ожиданий и комментариев в одном поле.

Это неудобно сразу по трем причинам:

• сравнения между версиями становятся мутными;
• регрессионные шлюзы трудно автоматизировать;
• проверка трасс и проверка набора живут как две разные вселенные.

Поэтому полезно мыслить набор для оценки как контракт.

Целостность оценки как контроль первого класса¶

Свежий разбор OpenAI по SWE-Bench Pro показывает, почему этого недостаточно: даже реалистичный benchmark может давать шумный сигнал, если сами задачи сломаны. OpenAI обнаружила, что автоматический конвейер пометил 200 из 731 задач публичного split как сломанные, а кампания с пятью опытными инженерами на задачу нашла 249 таких задач. В терминах книги это означает простую вещь: eval artifact сам должен проходить проверку качества, потому что он влияет на безопасность выпуска, приоритеты исследований и аргументы safety case.

Минимальная таксономия дефектов полезна уже на уровне схемы:

• overly_strict_tests: скрытые тесты требуют конкретную реализацию, которой не требует prompt;
• underspecified_prompt: prompt не содержит требований, которые потом принудительно проверяет oracle;
• low_coverage_tests: тесты пропускают неполное решение;
• misleading_prompt: prompt ведет к поведению, которое противоречит тестам или gold patch.

Значит, рядом с verifier_outputs нужен отдельный eval_audit_record. Он описывает не то, как агент прошел сценарий, а насколько надежен сам измеритель: source_task_id, oracle_type, defect_labels, agent_audit_refs, human_reviewer_count, human_agreement, reviewer_confidence и decision_impact.

Практический паттерн здесь не “пусть агент проверит eval”. Более надежная форма — agent-assisted eval audit + independent human adjudication: агент помогает масштабно искать несоответствия между prompt, tests, traces и patches, но итоговая метка, уверенность и влияние на решение о выпуске остаются отдельным человеческим артефактом.

Минимальная форма оценочного артефакта¶

Для агентных систем очень полезно, чтобы один элемент набора содержал хотя бы:

• scenario_id
• labels
• user_inputs
• expected_outcomes
• risk_class

Минимальный пример выглядит так:

{
  "scenario_id": "support_ticket",
  "labels": ["write_path", "approval_required", "ticketing"],
  "user_inputs": [
    "Please create a ticket for this onboarding issue."
  ],
  "expected_outcomes": {
    "latest_status": "success",
    "approval_wait_runs": 1,
    "required_output_substrings": [
      "waiting for human approval"
    ]
  },
  "risk_class": "high"
}

Это уже намного полезнее, чем просто «вот пример запроса».

Почему меток недостаточно без ожидаемых результатов¶

Метки помогают группировать сценарии:

• retrieval
• approval
• memory
• safety
• multi-turn

Но сами по себе метки ничего не говорят о том, что считается успешным поведением.

Поэтому набор для оценки почти всегда должен разделять:

• labels как описание класса сценария;
• expected_outcomes как описание ожидаемого результата;
• grading_rules как описание того, как именно это проверяется;
• verifier_outputs как структурированный результат проверки, включая идентификатор проверяющего и версию контракта.

Что такое правила проверки¶

Правила проверки нужны, чтобы убрать двусмысленность между «примером» и «критерием прохождения».

Практически это означает, что у сценария должно быть явно указано:

• какие поля мы вообще оцениваем;
• какой тип проверки применяется;
• что считается успехом или провалом;
• что можно считать предупреждением, а что блокирующим нарушением.

Хорошие правила проверки отвечают на вопрос:

«Если завтра этот же сценарий проверит другой человек или другой конвейер, он придет к той же оценке?»

Типы правил проверки¶

Для справочных оценок агентных систем полезно различать хотя бы такие правила:

• status_equals
• contains_substring
• max_tool_calls
• approval_required
• policy_violation_absent
• memory_write_absent
• process_score_present
• outcome_score_present
• failure_attribution_valid
• failed_run_traceable
• sandbox_profile_review
• stop_condition_verified
• delegation_budget_respected
• single_vs_multi_agent_regression

failed_run_traceable становится важным, как только проверка выпуска начинает требовать тренировки неудачных запусков. Оно проверяет, что деградировавший путь не просто завершился неуспешно, а сохранил проверяемый статус, конкретную причину сбоя, например в поле failure_reason, связь с трассой и управляемую идентичность выпуска.

sandbox_profile_review нужен для путей с опорой на песочницу: он проверяет, что подготовка рабочего пространства, права оболочки и файловой системы, позиция по сети и секретам и политика снимка/возобновления были явно представлены как проверяемые доказательства, а не остались неявными настройками среды выполнения.

stop_condition_verified нужен для путей запуска агента, где результат нельзя принимать по свободному тексту “готово”. Он проверяет, что у сценария есть явное условие завершения, механизм проверки, результат проверки, исполнитель проверки и ссылки на доказательства: вывод теста, трассу, снимок экрана, diff или другой артефакт.

delegation_budget_respected нужен для manager/subagent paths. Он проверяет, что fanout был разрешен явным gate, subagent_count не превысил лимит, context_handoff_size и token_budget остались в пределах сценария, а delegation_reason объясняет, почему single-agent path был недостаточен.

single_vs_multi_agent_regression нужен для сравнения режимов. Он проверяет, что multi-agent действительно выигрывает на read-heavy breadth-first сценарии и не проходит write-heavy shared-state сценарий, если растут конфликтующие действия, approvals, потеря контекста или merge_conflict_risk.

То есть правила проверки лучше строить не только вокруг текста ответа, но и вокруг поведения системы.

Как это связано с трассами¶

Полезная практическая модель такая:

• схема трасс описывает фактическое поведение запуска;
• схема набора для оценки описывает ожидаемое поведение;
• правила проверки сопоставляют одно с другим.

Именно в этой точке наблюдаемость становится не только способом смотреть назад, но и способом принимать решения о выпуске.

Что уже умеет эталонная среда исполнения¶

В agent_runtime_ref команда:

.venv/bin/python -m agent_runtime_ref export-eval-dataset --output artifacts/eval-dataset.json

уже дает небольшой структурированный артефакт с:

• несколькими сценариями сессий;
• labels;
• expected_outcomes;
• отдельным сценарием тренировки неудачного запуска, который сохраняет failed status и failure_reason в экспорте сессии и ожидаемых результатах оценки.

Контракт пакетного экспорта намеренно конкретен. Проверка конфигурации сессионных оценок также отделяет некорректно сформированные спецификации оценки от неуспешных результатов оценки через Session eval specs must be a mapping, Session eval spec must be a mapping, Session eval spec key must be a string, Session eval spec key must not be empty и Session eval spec keys must be unique.

Контракт экспорта намеренно конкретен: значение dataset_name по умолчанию — agent-runtime-ref-eval-seed; верхнеуровневая сводка (top-level) включает session_count, session_ids, run_count, failed_runs, traceable_failed_runs, trace_ids, failed_trace_ids, idempotency_keys, approval_ids, approval_capability_names, pending_approval_ids, pending_approval_capability_names, approval_status_counts и latest_failure_reason; сценарии с ожиданием подтверждения также несут approval_status_counts в expected_outcomes. Эти встроенные сценарии разделяют известный преддиспетчерский отказ и неопределённый внешний эффект: failed_run_timeout доказывает отказ до вызова инструмента и трассируемость, а unknown_effect_reconciliation создаёт side_effect_unknown, ожидает одну запись reconciliation_runs и содержит метку duplicate_ticket_eval_passed, ограничение max_ticket_side_effects: 1 и блокирующее правило duplicate_ticket_guard. profile_memory использует memory_read, profile_lookup и grounded_answer; mixed_session — multi_run, approval_then_memory, session_evals и required_run_count; support_ticket — sandbox_profile_review и sandbox_profile_reviewed.

Для будущего fanout-сценария тот же export должен сохранять per-run поля subagent_count, delegation_reason, context_handoff_size, token_budget и merge_conflict_risk, даже если маленький reference runtime пока заполняет их пустыми строками. Это важно: downstream eval tooling должно видеть, что отсутствие делегирования — тоже измеримое состояние, а не пропуск поля.

Для durable named-agent сценариев export должен так же сохранять agent_instance_id, durable_state_version, scheduled_wakeup_id и resumable_stream_id. Это позволяет eval сравнивать не только качество ответа, но и корректность resume/wakeup behavior: продолжился ли тот же actor instance, не была ли потеряна state version и не появился ли незаметный stateless replay вместо durable continuation.

Это еще не полноценный промышленный контур оценки, но уже нормальная заготовка для:

• регрессионной проверки;
• сравнения сценариев;
• проверки раскатки;
• ручного расширения набора.

Что стоит добавить в промышленную схему набора¶

Как только система становится серьезнее, полезно расширять схему полями карточки решения проверяющего (verifier verdict record):

• dataset_version
• scenario_owner
• source_trace_ids
• grader_type
• blocking
• notes_for_review
• verifier_outputs
• failure_attribution
• verdict_id
• verifier_id
• verifier_contract_version
• input_refs
• verifier_evidence_refs
• blocking_decision
• comparison_baseline
• reviewer_override
• sandbox_profile_contract
• workspace_manifest_ref
• snapshot_policy
• stop_condition
• verification_command
• verification_result
• verifier_actor
• evidence_refs
• subagent_count
• delegation_reason
• context_handoff_size
• token_budget
• merge_conflict_risk
• agent_instance_id
• durable_state_version
• scheduled_wakeup_id
• resumable_stream_id
• eval_audit_record
• oracle_type
• defect_labels
• agent_audit_refs
• human_reviewer_count
• human_agreement
• reviewer_confidence
• decision_impact

Тогда оценочный артефакт начинает жить не как временный JSON, а как часть дисциплины выпуска.

Критерии приемки вердикта проверяющего¶

Вердикт проверяющего можно считать контрактом, а не комментарием ревьюера, только если он проходит несколько проверок:

• у него есть стабильные verdict_id, verifier_id и verifier_contract_version;
• входы (input_refs) и доказательства (verifier_evidence_refs или evidence_refs) указывают на трассы, сценарии и версии политик;
• process_score, outcome_score и failure_attribution разделены и не схлопнуты в один ярлык;
• blocking_decision, comparison_baseline и reviewer_override объясняют, почему выпуск блокируется, предупреждается или пропускается;
• stop_condition, verification_command, verification_result и verifier_actor фиксируют, как именно проверено завершение запуска.

Пример правил проверки¶

Ниже рабочий пример для сценария тренировки неудачного запуска:

scenario_id: failed_run_timeout
labels:
  - failed_run
  - tool_timeout
  - failure_drill
grading_rules:
  - type: status_equals
    expected: failed
    blocking: true
  - type: contains_substring
    expected: tool_timeout
    blocking: true
  - type: failed_run_traceable
    expected: true
    blocking: true
  - type: sandbox_profile_review
    expected:
      sandbox_profile_contract: sandbox-profile-v1
      workspace_entries_reviewed: true
      permissions_profile: restricted-shell-network-denied
      network_secrets_posture: network:denied,secrets:none
      snapshot_policy: required_on_completion
    blocking: true
  - type: stop_condition_verified
    expected:
      stop_condition: no duplicate ticket side effect after timeout replay
      verification_command: .venv/bin/pytest tests/test_docs_surface.py
      verification_result: pass
      verifier_actor: deterministic_gate
      evidence_refs:
        - trace:trace_123
        - artifact:pytest-output
    blocking: true
verifier_outputs:
  verdict_id: verdict_failed_run_timeout_2026_05
  verifier_id: fara-process-review
  verifier_contract_version: verifier-v2
  input_refs:
    - scenario:failed_run_timeout
    - trace:trace_123
    - policy_bundle:policy-bundle-v3
  process_score: 0.92
  outcome_score: 0.35
  failure_attribution: uncontrollable_environment
  blocking_decision: warning_only
  comparison_baseline: release-2026-05-previous
  reviewer_override: none
  verifier_evidence_refs:
    - trace:trace_123
    - screenshot:step_7

Смысл здесь в том, что правила проверки оценивают не только финальный текст, но и правильную рабочую форму поведения, включая то, остается ли конкретное условие сбоя достаточно видимым для последующего разбора.

Это особенно важно для агентов с длинным горизонтом действий, где двоичная оценка успеха или провала часто скрывает разницу между корректным поведением с заблокированным итогом и небезопасным поведением, которое случайно закончилось номинальным успехом.

Почему особенно важны многошаговые сессии¶

Для агентных систем элемент набора довольно часто должен описывать не один запрос, а короткую серию связанных шагов.

Например:

1. пользователь просит создать ticket;
2. потом спрашивает, что агент помнит о его предпочтениях;
3. потом уточняет следующий шаг.

Если набор не умеет описывать такую серию, ты неплохо проверяешь одиночный запрос, но слабо проверяешь поведение на уровне сессии.

Именно поэтому экспорт сессий и экспорт наборов для оценки полезно проектировать совместно.

Чего не стоит делать¶

Есть несколько типичных ошибок:

• смешивать metadata сценария и логику проверки в одном текстовом поле;
• хранить только happy path;
• не фиксировать ожидаемые результаты явно;
• оценивать только финальный ответ и игнорировать поведение политики и инструментов;
• не версионировать набор;
• не проверять качество самих задач, oracle и hidden tests;
• не связывать элементы набора с данными трасс или историей инцидентов;
• схлопывать verifier output в один слабый verdict без process/outcome split и failure attribution;
• требовать sandbox_profile_review в rollout, но не иметь grading rule, который проверяет workspace, permissions и snapshot/resume evidence;
• позволять агенту завершать задачу без stop_condition_verified и без доказательства, которое можно проверить после сессии.

Все это делает культуру оценки хрупкой.

Что сделать сразу¶

Сначала пройди по короткому списку и отдельно отметь все ответы «нет»:

• У каждого сценария есть стабильный scenario_id?
• Метки отделены от ожидаемых результатов?
• Есть ли правила проверки, а не только описания от руки?
• Можно ли оценивать не только текст, но и поведение?
• Есть ли eval_audit_record, который фиксирует defect labels, oracle type, уверенность ревьюера и влияние дефекта на решение?
• Умеет ли verifier выдавать отдельно process_score, outcome_score и failure_attribution?
• Можно ли понять, какой идентификатор проверяющего и версия контракта породили эту итоговую оценку?
• Есть ли отдельное правило для путей с опорой на песочницу, которое проверяет контракт профиля песочницы, элементы рабочего пространства, права доступа и доказательства по снимку/возобновлению?
• Есть ли правило, которое проверяет stop condition, verification command/result, verifier actor и evidence refs для завершения запуска?
• Поддерживаются ли многошаговые сессии?
• Есть ли версионирование набора и владелец?

Если несколько ответов подряд «нет», значит у тебя пока есть набор примеров, но еще нет полноценной схемы для оценки.

Что делать дальше¶

• Схема трасс и каталог событий
• Схема набора политик и контракта подтверждения
• Схема артефактов жизненного цикла
• Эталонный пакет
• Глава 13. Офлайн-оценки, онлайн-оценки и регрессионные шлюзы