Розробка, заснована на оцінці, для штучних інтелектуальних агентів: контракти, трекування та оцінювачі
Ставіться до оцінок як до процесу CI/CD для агентів: версії запитів — як контракти, відстежуйте виконання за допомогою OpenTelemetry та Tempo, а потім тестуйте за допомогою детерміністичних перевірок та судді у вигляді ШІ.
Джерела: **Eval-Driven Development: A Software Engineering Approach to Production-Grade AI Agents**
Більшість команд, які розробляють агентський ШІ, рано потрапляють у пастку стандартизованих фреймворків. Пошук ідеального оркестратора здається очевидним першим кроком, але важкі, абстрактні фреймворки виявляються не рішенням проблеми, крім того, деякі з них швидко деградують між версіями. Автоматизація перевірки коду, створена без жодних фреймворків, показала, наскільки мало все це потрібно. Те, чого бракувало, — це елементів, запозичених зі звичайної інженерії програмного забезпечення: оцінювачів, які функціонують подібно до систем CI/CD для агентів.
Оцінювачі не є універсальними, і вони не обмежуються лише використанням великих мов мовлення як суддів. Правильна реалізація таких оцінювачів — це різниця між крихким „іграшковим“ рішенням та системою промислового рівня.
Цей стек навмисно є відкритим кодом та не прив’язаний до послуг, якими керує якийсь конкретний постачальник. Pydantic AI є фреймворком агентів — легкою бібліотекою, орієнтованою на схеми, яка не заважає роботі та розглядає оцінки як функцію першого класу. Grafana Tempo зі зберіганням у S3 зберігає трекери замість платформи для керованої спостережливості, а код, створений за допомогою ШІ, аналізує ці трекери та фільтрує їх за кожним типом оцінки.
Чому більшість агентів не виживають у продакшені
Найочевиднішою ознакою системи агентів, яка не протриває довго, є не модель, не фреймворк та не кмітливість запитів — це відсутність основних інженерних практик. Якщо у агента немає структурованого відстеження, оцінок, версіонування запитів та захисних механізмів, це лише концепт, який має високі шанси на провал.
Традиційне програмне забезпечення отримує постійну якість завдяки пайплайнам CI/CD, модульним тестам, тестам інтеграції та тестам регресії. У недетермінованому світі агентів типовою фатальною проблемою є відсутність автоматизованої системи оцінки та відсутність механізмів контролю їх роботи. Створення зрілих агентів означає повернення до основних принципів: відкритої інфраструктури та робочого процесу розробки, заснованого на оцінці (Eval-Driven Development, EDD), який може масштабуватися.
Продукційний пайплайн
1. Контракт: окремо версіонувати запити
Запити та пов’язані з ними елементи є найважливішою частиною системи агентів, тому їх не слід ховати всередині коду агента. Код — це лише „тіло“ системи, яке досить легко стабілізувати та версіонувати, тоді як запити постійно еволюціонують у міру вдосконалення моделей.
Пайплайн починається з версіонованого контракту, який визначає, що має працювати: агент, запит, модель та політика оцінки.
[
{
"agent_id": "financial_market_headlines",
"version": 1,
"agent_model": "openai:gpt-4",
"prompt": "What are today's major financial market headlines?",
"eval": {
"contains": ["market"],
"max_model_requests": 3,
"min_tool_calls": 1,
"max_tool_calls": 5,
"judge_rubric": "The answer should be a useful response to the user's financial markets question. It should summarize market-relevant information, avoid obviously unrelated content, avoid investment advice, and avoid claiming certainty beyond what the retrieved information supports."
}
}
]
Тут запит та критерії оцінки навмисно скорочені для демонстраційних цілей, адже у реальних ситуаціях запити зазвичай є довгими та деталізованими. Контракт пов’язує запит із запитом оцінки від LLM у ролі судді, а також із перевірками, які не залежать від LLM, такими як зіставлення ключових слів за допомогою оператора „contains“ та встановлення мінімальної чи максимальної кількості викликів інструментів.
2. Час виконання: двигун виконання
Час виконання агента забезпечує виконання контракту. Він викликає модель, за потреби використовує зовнішні інструменти через MCP та виконує фактичну роботу.
Вибір зупинився переважно між LangGraph та Pydantic AI. Python — не єдиний варіант, навіть у Rust є бібліотека Rig. Однак чиста швидкість мови майже не має значення порівняно з часом очікування на обробку даних LLM та мережевими викликами до інструментів MCP, тому перемагає велика та зріла екосистема AI для Python. Pydantic AI обрала через першокласну підтримку процедур оцінки.
У продакшені середовище виконання зазвичай базується на Kubernetes. Існує спокуса надмірно складної архітектури, коли кожен агент моделюється як власний ресурс, але цикли узгодження для швидко змінюваних запитів знизять вашу продуктивність. Тримайте середовище виконання простим.
3. Шар спостережуваності: без сліпих зон
Середовище виконання генерує треки, журнали, лічильники використання, виклики моделей та інструментів, показники затримки та помилки; усе це фіксується за допомогою OpenTelemetry та зберігається в системах на кшталт Tempo, Loki та Prometheus. Grafana потім відображає, що робить система у продакшені.
4. Шар оцінки: CI/CD для ШІ
Саме тут все поєднується. Треки виконання з шару спостережуваності потрапляють безпосередньо до процесу оцінки, де проти реальних треків виконуються два типи тестів: детерміністичні правила та недетерміністичні оцінки.
Цей цикл ніколи не зупиняється: визначити, виконати, спостерігати, оцінити, вдосконалити, повторити.
Нав’язування детермінізму недетерміністичній системі
Оцінки поділяються на дві групи. Детерміністичні можна точно перевірити за допомогою звичайного коду. Простим прикладом може бути запит до ШІ на додавання двох чисел та перевірка відповіді за допомогою тесту єдиниці.
У цьому випадку запит передбачає отримання новин фінансового ринку на сьогодні, що означає, що модель має принаймні один раз скористатися наданим інструментом пошуку в Інтернеті. Ця частина є детерміністичною та становить корисний тест. А якщо результат має містити певні рядки, можна перевірити це за допомогою функції „Містить“.
Рівень 1: живі детерміністичні тести
Цей набір виконує сучасного агента проти версіонованого контракту. Pydantic Evals постачається з параметром MaxToolCalls та функцією перевірки на наявність тексту Contains. Відсутні елементи, такі як MinToolCalls, додаються у вигляді простих обгорток.
uv run python tests/unittest_eval_agent.py
Оцінювачі формуються окремо для кожного випадку:
evaluators=[
*[Contains(value, case_sensitive=False) for value in case.eval.contains],
MaxModelRequests(case.eval.max_model_requests),
MinToolCalls(case.eval.min_tool_calls),
MaxToolCalls(case.eval.max_tool_calls),
]
Кожен екземпляр виконується кілька разів, оскільки моделі є недетерміністичними. Одна й та сама модель з ідентичним запитом та налаштуваннями може використати інструмент у одному виконанні та пропустити його в іншому. Це особливо помітно з дешевшими, менш потужними моделями, і якщо, скажімо, десять виконань проваляються, це є ознакою того, що запит потребує більшої деталізації. Виконання з трьома повтореннями виглядає так:
(financial-agent2) alex@pop-os:/ssd/ai_works/financial_agent2$ uv run python tests/unittest_eval_agent.py
Running each eval case 3 time(s)
Evaluating task ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
Evaluation Summary: task
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Case ID ┃ Metrics ┃ Assertions ┃ Duration ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ financial_market_headlines_v1 [1/3] │ tool_calls: 1 │ ✔✔✔✔ │ 18.8s │
│ │ requests: 2 │ │ │
│ │ input_tokens: 1,325 │ │ │
│ │ output_tokens: 278 │ │ │
│ │ cost: 0.0564 │ │ │
├─────────────────────────────────────┼───────────────────────┼────────────┼──────────┤
│ financial_market_headlines_v1 [2/3] │ tool_calls: 1 │ ✔✔✔✔ │ 8.8s │
│ │ requests: 2 │ │ │
│ │ input_tokens: 1,195 │ │ │
│ │ output_tokens: 82 │ │ │
│ │ cost: 0.0408 │ │ │
├─────────────────────────────────────┼───────────────────────┼────────────┼──────────┤
│ financial_market_headlines_v1 [3/3] │ tool_calls: 1 │ ✔✔✔✔ │ 13.5s │
│ │ requests: 2 │ │ │
│ │ input_tokens: 1,292 │ │ │
│ │ output_tokens: 388 │ │ │
│ │ cost: 0.0620 │ │ │
├─────────────────────────────────────┼───────────────────────┼────────────┼──────────┤
│ Averages │ requests: 2.00 │ 100.0% ✔ │ 13.7s │
│ │ output_tokens: 249.3 │ │ │
│ │ tool_calls: 1.00 │ │ │
│ │ cost: 0.0531 │ │ │
│ │ input_tokens: 1,270.7 │ │ │
└─────────────────────────────────────┴───────────────────────┴────────────┴──────────┘
Рівень 2: детерміністична регресія з слідів
Другий набір не запускає агента знову. Він читає завершені сліди з Tempo:
uv run python tests/regression_eval_traces.py
Він отримує кінцевий результат, підраховує кількість елементів моделі та інструментів, знаходить зазначений контракт та застосовує ті самі детерміністичні правила, що й раніше: наявність певних елементів та принаймні один виклик інструменту. Записаний результат виконання може містити наступну інформацію:
Trace: ff5a53e3392dc26cd0a2890782be70ec
Eval case: financial_market_headlines v1
Status: PASS
Model requests: 2
Tool calls: 1
contains('market'): PASS
MaxModelRequests: PASS
MaxToolCalls: PASS
Це дешево та можливо до повторення, оскільки воно знову аналізує вже зібрані докази.
Рівень 3: недетерміністичні тести з суддею у вигляді LLM
У контракті також є критерії для тестування запиту. Це знову той самий короткий контракт:
[
{
"agent_id": "financial_market_headlines",
"version": 1,
"agent_model": "openai:gpt-4",
"prompt": "What are today's major financial market headlines?",
"eval": {
"contains": ["market"],
"max_model_requests": 3,
"min_tool_calls": 1,
"max_tool_calls": 5,
"judge_rubric": "The answer should be a useful response to the user's financial markets question. It should summarize market-relevant information, avoid obviously unrelated content, avoid investment advice, and avoid claiming certainty beyond what the retrieved information supports."
}
}
]
Оскільки сам агент працює на базі GPT-4, судді потрібна потужніша модель, і саме GPT-5 виконує цю роль. Він вирішує, чи була відповідь корисною та релевантною, чи не перебільшувалась інформація, підтверджена отриманим матеріалом, та чи не містилась у ній інвестиційна порада.
Розділення критеріїв на кілька рівнів пропонує інший підхід. Прості перевірки типу NLP можуть виконуватися слабкішими моделями або навіть невеликими самостійно розміщеними моделями, і сукупність таких простих тестів може наблизитися до більш складних оцінок вищого рівня. Те, що краще, залежить від конкретного випадку використання та від того, як спроєктовані тести.
Для більш глибокого розуміння корисно ознайомитися з дослідницькою статтею „A Survey on LLM-as-a-Judge“ (arXiv 2411.15594). Залежно від ситуації, зрештою знадобляться системи, які будуть оцінювати самого суддю, використовуючи людські відгуки чи інші засоби.
Суїтка завантажує той самий збережений кінцевий результат та запускає Pydantic Evals LLMJudge згідно з критеріями контракту:
LLMJudge(
rubric=case.eval_case.eval.judge_rubric,
model=args.judge_model,
include_input=True,
score={"evaluation_name": "judge_score", "include_reason": True},
assertion={"evaluation_name": "judge_pass", "include_reason": True},
)
Ось класична помилка, виявлена суддею, спричинена коротким та нечітким запитом. Замість того, щоб викликати інструмент та узагальнити результати, модель відповіла повідомленням із проханням користувача перевірити фінансові новинні ресурси.
uv run python tests/regression_llm_judge_traces.py --sample-percent 50
Trace selection: fetched=1 sampled=1 judging=1 lookback_minutes=1440 sample_percent=50 max_traces=5
Trace case: trace_id=3891f0b8432c9bbcb00e5e8adce1600b agent_id=financial_market_headlines prompt_version=1 answer_chars=207
Judging 1 trace(s) with openai:gpt-5.4
Evaluating task ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
Evaluation Summary: task
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Case ID ┃ Inputs ┃ Outputs ┃ Scores ┃ Assertions ┃ Duration ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ financial_market_he… │ {'trace_id': │ Today's major │ judge_score: 0.000 │ judge_pass: ✗ │ 469µs │
│ │ '3891f0b8432c9bbcb00 │ financial market │ Reason: The │ Reason: The │ │
│ │ e5e8adce1600b', │ headlines can be │ response does not │ response does not │ │
│ │ 'agent_id': │ found on major │ summarize any actual │ summarize any │ │
│ │ 'financial_market_he │ business and finance │ market headlines or │ actual market │ │
│ │ adlines', │ news outlets │ provide │ headlines or │ │
│ │ 'prompt_version': 1, │ including CNBC, │ market-relevant │ provide │ │
│ │ 'agent_model': │ Yahoo Finance, │ information; it only │ market-relevant │ │
│ │ 'openai:gpt-4', │ Reuters, and │ redirects the user │ information; it │ │
│ │ 'judge_model': │ Bloomberg. For more │ to news websites. It │ only redirects the │ │
│ │ 'openai:gpt-5.4', │ specific stories, │ avoids investment │ user to news │ │
│ │ 'prompt': "What are │ please visit their │ advice, but it is │ websites. It avoids │ │
│ │ today's major │ websites. │ not a useful answer │ investment advice, │ │
│ │ financial market │ │ to the user's │ but it is not a │ │
│ │ headlines?"} │ │ question. │ useful answer to │ │
│ │ │ │ │ the user's │ │
│ │ │ │ │ question. │ │
│ │ │ │ │ │ │
│ │ │ │ │ │ │
├──────────────────────┼──────────────────────┼──────────────────────┼──────────────────────┼─────────────────────┼──────────┤
│ Averages │ │ │ judge_score: 0.000 │ 0.0% ✔ │ 469µs │
└──────────────────────┴──────────────────────┴──────────────────────┴──────────────────────┴─────────────────────┴──────────┘
Нижче наведений ще один випадок невдачі. У цьому випадку суддя міг прийняти неправильне рішення, або критерії оцінювання можуть бути занадто нечіткими, адже модель дійсно використала інструмент пошуку MCP та отримала прийнятні результати.
uv run python tests/regression_llm_judge_traces.py --sample-percent 10 --lookback-minutes 30
Trace selection: fetched=1 sampled=1 judging=1 lookback_minutes=30 sample_percent=10 max_traces=5
Trace case: trace_id=38fa3a54134d8818c7d7a5afbf50967e agent_id=financial_market_headlines prompt_version=1 answer_chars=654
Judging 1 trace(s) with openai:gpt-5.4
Evaluating task ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
Evaluation Summary: task
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Case ID ┃ Inputs ┃ Outputs ┃ Scores ┃ Assertions ┃ Duration ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ financial_market_… │ {'trace_id': │ Here are today's │ judge_score: 0.450 │ judge_pass: ✗ │ 441µs │
│ │ '38fa3a54134d8818c │ major financial │ Reason: The │ Reason: The │ │
│ │ 7d7a5afbf50967e', │ market headlines: │ response is │ response is │ │
│ │ 'agent_id': │ │ market-related and │ market-related │ │
│ │ 'financial_market_ │ 1. Wall Street's │ avoids investment │ and avoids │ │
│ │ headlines', │ riskiest trades │ advice, but it │ investment │ │
│ │ 'prompt_version': │ are suddenly back │ mostly lists │ advice, but it │ │
│ │ 1, 'agent_model': │ on top: Chart of │ article headlines │ mostly lists │ │
│ │ 'openai:gpt-4', │ the Day - Yahoo │ and links rather │ article headlines │ │
│ │ 'judge_model': │ Finance │ than providing a │ and links rather │ │
│ │ 'openai:gpt-5.4', │ [Link](https://fi │ useful summary of │ than providing a │ │
│ │ 'prompt': "What │ nance.yahoo.com/) │ the key financial │ useful summary of │ │
│ │ are today's major │ 2. S&P 500 │ market │ the key financial │ │
│ │ financial market │ notches │ developments. │ market │ │
│ │ headlines?"} │ record-high close │ │ developments. │ │
│ │ │ as rate-hike │ │ │ │
│ │ │ worries ease - │ │ │ │
│ │ │ Reuters │ │ │ │
│ │ │ [Link](https://ww │ │ │ │
│ │ │ w.reuters.com/mar │ │ │ │
│ │ │ kets/us/) │ │ │ │
│ │ │ 3. Treasury │ │ │ │
│ │ │ yields rise as │ │ │ │
│ │ │ U.S. threatens │ │ │ │
│ │ │ Iran with more │ │ │ │
│ │ │ economic │ │ │ │
│ │ │ sanctions - CNBC │ │ │ │
│ │ │ [Link](https://ww │ │ │ │
│ │ │ w.cnbc.com/) │ │ │ │
│ │ │ 4. Latest stock │ │ │ │
│ │ │ market, financial │ │ │ │
│ │ │ and business news │ │ │ │
│ │ │ - MarketWatch │ │ │ │
│ │ │ [Link](https://ww │ │ │ │
│ │ │ w.marketwatch.com │ │ │ │
│ │ │ /) │ │ │ │
│ │ │ 5. Latest finance │ │ │ │
│ │ │ and stock market │ │ │ │
│ │ │ news covering the │ │ │ │
│ │ │ Dow, S&P 500, │ │ │ │
│ │ │ banking, │ │ │ │
│ │ │ investing and │ │ │ │
│ │ │ regulation - WSJ │ │ │ │
│ │ │ [Link](https://ww │ │ │ │
│ │ │ w.wsj.com/finance │ │ │ │
│ │ │ ) │ │ │ │
├────────────────────┼────────────────────┼───────────────────┼────────────────────┼───────────────────┼──────────┤
│ Averages │ │ │ judge_score: 0.450 │ 0.0% ✔ │ 441µs │
└────────────────────┴────────────────────┴───────────────────┴────────────────────┴───────────────────┴──────────┘mar
Проведення таких тестів для кожної траси може стати занадто дорогим та повільним. Кращим варіантом є випадкова вибірка. Якщо продукт дозволяє збирати відгуки користувачів, ідентифікатор траси може безпосередньо вказати на компоненти в потоці, де виникла проблема, і тестуватимуться лише вони. Комерційні продукти на кшталт LangSmith та Arize Phoenix вже враховують це, але S3-бекенд у поєднанні з цією стеком також забезпечує таку можливість; існує також налаштування docker compose для цього.
Після початкових тестів одиниць коду стає зрозуміло, що як запит, так і критерії оцінювання потребують оновлення, і контракт переходить до версії 2:
{
"id": "financial_market_headlines",
"version": 2,
"agent": "websearch",
"prompt": "Use the web-search tool to find and verify today's major financial-market headlines. Report the 3 to 5 most consequential developments across equities, rates, currencies, commodities, or macroeconomic policy. For each item, state what happened, identify the affected market or region, explain briefly why it matters, and name the source with a link when available. Include the relevant date and units for numerical claims. Cross-check any surprising index level, percentage move, policy decision, or economic release against a second reliable source; if it cannot be verified, omit it or clearly label it as unconfirmed. State when the information was current, distinguish facts from developing reports or interpretation, and say when reliable current information is insufficient. Do not invent facts, present stale information as today's news, or give personalized investment advice.",
"contains": ["market"],
"max_model_requests": 4,
"min_tool_calls": 1,
"max_tool_calls": 7,
"judge_rubric": "The response should provide 3 to 5 current, consequential financial-market developments based on web research. Each item should identify what happened, the affected market or region, why it matters, and its source, preferably with a link. Numerical claims should include meaningful dates and units; surprising figures should be corroborated by a second reliable source or explicitly marked unconfirmed. The answer should state when the information was current, distinguish verified facts from developing reports or interpretation, and acknowledge insufficient evidence rather than inventing details. It must stay relevant, avoid stale news presented as current, avoid unsupported certainty, and avoid personalized investment advice. A polished but uncited answer containing an implausible or unverifiable market figure should fail."
},
Від шаблону до конвеєра випуску
Коли кожен слід веде до відповідного контракту, конвеєр випуску може збирати різні види доказів на кожному етапі, що дає більше інформації, ніж просто показник проходження тестів. Випуск слід оцінювати за кількома критеріями:
- чи було завдання виконано успішно
- наскільки якісним є результат з семантичної точки зору
- чи правильно використовувалися інструменти
- дотримання стандартів безпеки та правил
- витрати у вигляді запитів та токенів
- затримка та надійність
Додаткова література
У інженерному блозі Anthropic є стаття про те, як працюють оцінки для AI-агентів, за посиланням https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents, яка розглядає це питання більш детально.
Пов’язана література
- Розробка, заснована на специфікаціях, з використанням AI-агентів для кодування: практичний посібник — Як змусити AI-агентів для кодування дотримуватися специфікацій: чотириетапний процес роботи, файли AGENTS.md та SPEC.md, ролі багатьох агентів, рівні зрілості та відхилення намірів.
- Інженерія агентів у п’яти шарах: від специфікацій та паралельних агентів до правил та нагляду — Карпаті описав перехід від традиційного кодування. Детально розглядаються п’ять шарів інженерії агентів: специфікації, оркестрація, кодовані правила, людський огляд та можливість спостереження, а також план на тиждень.