Как создавать пользовательские code-based evaluators в Amazon Bedrock AgentCore

Особая благодарность всем, кто участвовал в запуске: Stephanie Yuan, Lefan Zhang, Ritvika Pillai, Irene Wang, Carter Williams, T.J Ariyawansa, Gitika Jha, Shoaib Javed, а также руководству продукта во главе с Vivek Singh.

Переход прототипов агентов в продуктивную среду требует оценки качества по нескольким измерениям. Amazon Bedrock AgentCore Evaluations предоставляет проверки LLM-as-a-Judge и расширяемые code-based evaluators, которые помогают учитывать доменные требования при оценке вашего agentic-приложения.

В финансовых сервисах и специализированных доменах критические метрики качества часто выходят за рамки языка. Агент для рыночной аналитики должен цитировать цены акций в пределах настраиваемого живого диапазона, соблюдать обязательный workflow идентификации брокера перед доступом к финансовым профилям, возвращать tool outputs, соответствующие строгой JSON-схеме, и не раскрывать personally identifiable information (PII). Такие проверки требуют детерминированного кода, который дает одинаковый результат на идентичном входе. Кроме того, запуск LLM-as-a-Judge для объективной проверки может быть дорогим там, где проще и надежнее использовать код.

С помощью custom code-based evaluators вы можете использовать функцию AWS Lambda в качестве механизма оценки. Вы контролируете логику скоринга: regex- и структурную валидацию, внешние запросы к данным, вызовы других сервисов или бизнес-правила. Один и тот же evaluator можно использовать в нескольких сценариях без расхода foundation model (FM) tokens на каждый запрос. В on-demand оценках он работает как gate в рабочих процессах разработки и CI/CD. В online evaluation он может оценивать живой production-трафик. Полный контроль над логикой оценки через AWS Lambda позволяет настроить custom code-based evaluators под ваши задачи. Даже если traces приходят из разных agent framework, такой подход дает возможность последовательно оценивать качество агента по вашей собственной логике.

В этом посте вы реализуете четыре Lambda-based custom code evaluators для агента рыночной аналитики, зарегистрируете каждый из них в AgentCore и запустите их в on-demand и online режимах. Также вы увидите, как сочетать custom code-based evaluators со встроенными evaluators и как вызывать другие сервисы AWS для grounded fact-checking, обнаружения PII и оповещений в реальном времени.

Измерения качества, подходящие для code-based evaluation

Агенты зависят от структурированных tool outputs, например JSON из search, retrieval или бизнес-API. Изменение контракта, ошибка парсинга или сбой upstream-сервиса могут привести к появлению некорректных данных, которые агент встроит в неверный ответ. Валидация схемы tool response выявляет структурные проблемы на границе инструмента и хорошо подходит как code-based check, тогда как LLM-as-a-Judge дополняет ее, оценивая полезность и ясность.

Агенты цитируют цены, метрики, пороги и квоты, и даже отклонение в 0,1% может изменить решение о сделке. LLM склонны к арифметическим ошибкам, а code-based evaluator обращается к эталонной системе, вычисляет допуск и фиксирует каждое расхождение. Числовую точность относительно источника истины наиболее эффективно проверять детерминированно.

Агенты, работающие в условиях ограничений по порядку действий и политик, должны идентифицировать пользователя до чтения чувствительных данных, получать подтверждения перед выполнением действий и соблюдать определенную последовательность вызовов инструментов для сохранения целостности данных. Проверка соблюдения workflow contract требует анализа последовательности tool calls в рамках всей сессии. Code-based evaluator проверяет, что агент следовал процессу, а LLM-as-a-Judge оценивает, насколько хорошо он сообщил результат.

Агенты, работающие с профилями, документами или логами, должны скрывать имена, номера счетов, контактные данные и секреты. Ответ, раскрывающий эти данные, — это нарушение комплаенса или инцидент безопасности. Code-based evaluators вызывают сервисы обнаружения PII или сканирования секретов и жестко ограничивают содержимое ответа, дополняя оценки языкового качества и полезности.

В сочетании с evaluators типа LLM-as-a-Judge code-based checks подтверждают и то, как агент коммуницирует, и то, соблюдены ли контракты, числа, workflow и правила обращения с данными. Такое сочетание переводит надежность агента из режима «звучит правдоподобно» в режим contract-verified.

Жизненный цикл evaluator: от spans к результатам со скорингом

Code-based evaluator — это функция Lambda, зарегистрированная в control plane AgentCore. Когда выполняется оценка, AgentCore принимает роль AWS Identity and Access Management (IAM) в вашем аккаунте, вызывает Lambda с payload, содержащим spans OpenTelemetry (OTel) агента, и записывает ответ Lambda в Amazon CloudWatch Logs как результат оценки. Payload содержит версию схемы, ID evaluator, имя evaluator, уровень оценки и объект evaluation input, в котором находится массив OTel spans для сессии. Для evaluators уровня trace отдельное поле evaluation target указывает конкретный trace, который нужно оценить. Для evaluators уровня session AgentCore не передает target, и Lambda оценивает весь диалог.

Ответ Lambda следует фиксированному контракту. При успехе он возвращает словарь с label, например PASS или FAIL, необязательным числовым score в диапазоне 0.0–1.0 и необязательной строкой explanation. При ошибке он возвращает словарь с code ошибки и сообщением ошибки. В каждом успешном ответе нужно указывать label. Поля score и explanation необязательны, но напрямую попадают в CloudWatch metrics и в панель AgentCore Observability, что помогает отлаживать низкие оценки. Каждый evaluator работает на одном из трех уровней, заданных при регистрации: TRACE, TOOL_CALL или SESSION, как показано на следующем рисунке. Чтобы использовать одну и ту же Lambda на нескольких уровнях, зарегистрируйте ее отдельно на каждом уровне, указывая одну и ту же функцию.

Рисунок: Code-based evaluators регистрируются отдельно на каждом уровне: trace, tool call и session.

Режимы on-demand и online для custom code-based evaluators

AgentCore Evaluations поддерживает code-based evaluators как в on-demand, так и в online режиме. Один evaluator ID используется для разработки, тестирования, CI/CD-gate и непрерывного мониторинга production. Контракт Lambda, включая payload, формат ответа и конфигурацию IAM, в обоих режимах остается одинаковым. Следующий рисунок иллюстрирует поток для online evaluation; on-demand evaluation проходит тем же путем, но вместо шага плановой выборки используется вызов API Evaluate.

Рисунок 2: End-to-end flow для code-based evaluator в online evaluation.

On-demand evaluation для разработки и CI/CD

On-demand evaluation подходит для трех сценариев:

• Итерации разработки. Сохраните сессию, запустите набор evaluators, изучите оценки и пояснения для каждого evaluator и используйте обратную связь, чтобы скорректировать prompt, определения tools или workflow памяти.
• Регрессионное тестирование. Поддерживайте библиотеку репрезентативных сессий, включая те, которые ранее выявляли ошибки, и прогоняйте по ним набор evaluators в тестовом наборе. Evaluator, который набирает меньше порога, сигнализирует о регрессии.
• CI/CD deployment gate. Перед продвижением новой версии агента в production запустите набор evaluators на наборе smoke-test сессий и заблокируйте развертывание, если code-based evaluator не проходит проверку.

Один on-demand вызов может ссылаться максимум на 10 evaluators разных типов, включая code-based и встроенные. Для Market Trends Agent предрелизная проверка запускает встроенные evaluators Helpfulness и Correctness вместе с четырьмя code-based evaluators. Совокупный результат подтверждает качество языка, целостность tool contract, точность цен, порядок workflow и безопасность PII за один проход.

Online evaluation для непрерывного мониторинга production

Online evaluation непрерывно отбирает живой трафик агента и оценивает его по настроенным evaluators по повторяющемуся расписанию. Чтобы настроить online evaluation, один раз создайте конфигурацию в control plane AgentCore, указав:

• Evaluators: до 10 evaluator IDs, с возможностью смешивать code-based и встроенные типы
• Источник данных: CloudWatch log group и имя OTel service для spans агента
• Sampling: процент сессий для оценки (0.01–100 процентов)

Online evaluation привязывается к агенту либо напрямую через AgentCore Runtime, либо через CloudWatch log group, который использует агент. Затем AgentCore использует эти настройки источника данных, чтобы находить завершенные сессии, группируя spans, представляющие весь диалог этого агента, и запускать на них оценку.

Вы можете точно настроить объем оцениваемого трафика, задав sampling percentage в диапазоне 0.01–100 процентов. Также задается session timeout, который сообщает AgentCore, сколько ждать после последнего span, прежде чем считать сессию завершенной. Этот тайм-аут должен соответствовать типичной длительности сессии вашего агента, чтобы избежать оценки незавершенных сессий.

После включения конфигурации AgentCore берет на себя повторяющееся расписание. Для каждой выбранной сессии он читает spans из CloudWatch, вызывает каждый настроенный evaluator и записывает результаты оценки в отдельный CloudWatch log group evaluation-results. При этом AgentCore принимает evaluation execution IAM role, заданную в конфигурации, поэтому разрешения Lambda и CloudWatch привязываются к этой роли, а не к runtime role агента.

Оценка каждого evaluator также появляется как метрика CloudWatch в формате Embedded Metric Format в namespace Bedrock-AgentCore/Evaluations, с привязкой к имени evaluator и ID конфигурации. Это позволяет строить дашборды CloudWatch, которые показывают schema validity, workflow compliance и PII cleanliness вместе с Helpfulness и Correctness, формируя единое представление о языковом и структурном качестве. Дополнительно можно настроить CloudWatch Alarms на эти метрики, чтобы оповещать операторов, когда отдельное измерение качества опускается ниже важного порога.

Обзор решения

В этом решении мы используем Market Trends Agent в качестве примера. Market Trends Agent — это инвестиционно-аналитический помощник, построенный на LangGraph и развернутый в Amazon Bedrock AgentCore Runtime. Полный пример находится в 02-use-cases/market-trends-agent в репозитории AgentCore samples. Агент обслуживает финансовых брокеров, предоставляя данные по акциям, анализ новостей из нескольких источников и профили брокеров, хранящиеся в AgentCore Memory, и адаптирует аналитику под стратегию, интересы и tolerance к риску каждого брокера.

Агент предоставляет инструменты для получения цен акций, финансовых новостей, поиска, извлечения идентичности брокера, чтения и записи профилей и генерации market briefing. OTel-инструментация LangGraph публикует spans в Amazon CloudWatch через AgentCore Observability, превращая агента в тестовую среду для code-based и LLM-as-a-Judge evaluators. Мы используем этот агент, чтобы показать, как настраивать custom code-based evaluations в online и on-demand режимах.

Рисунок 3: Архитектура Market Trends Agent

Пример включает четыре evaluators, покрывающих валидацию схемы, числовую точность, соблюдение workflow и обнаружение PII.

• ToolResponseSchemaValidator (trace level) — этот evaluator фильтрует spans до целевого trace, определяет spans вызовов tools и проверяет ответ каждого tool на соответствие ожидаемому шаблону — тикер и цена для данных по акциям, длина и форматирование для новостных сводок.
• StockPriceDriftChecker (trace level) — проверяет цены, указанные в ответах агента, относительно внешнего источника истины в пределах настраиваемого допуска (по умолчанию 2 процента). Этот evaluator извлекает пары тикер+цена из текста ответа, получает эталонные цены из market data endpoint и вычисляет процент отклонения для каждой пары.
• WorkflowContractGSR (session level) — обеспечивает трехшаговый workflow contract в рамках всей сессии: идентифицировать брокера, затем работать с брокерским профилем, затем вызывать tools рыночных данных и новостей. Этот evaluator восстанавливает упорядоченный список tool calls из session spans и проверяет, что каждый шаг выполнен в правильном порядке.
• BrokerPIILeakChecker (session level) — сканирует каждый ответ агента в сессии на наличие PII с помощью Amazon Comprehend DetectPiiEntities API. Lambda классифицирует обнаруженные сущности на типы высокого риска (SSN, платежная карта, банковский счет, government ID, credential) и менее рискованные контактные данные (имя, email, телефон, адрес), применяя разные пороги к каждому типу. Высокорискованная PII возвращает FAIL; чрезмерное использование менее рискованной PII дает частичный score с подсчетом. Для сред, которые не могут опираться на Comprehend, включен вариант на основе regex.

Предварительные требования

Этот walkthrough занимает 45 минут практической работы и стоит менее $5 по AWS-расходам при стандартных уровнях sampling. Чтобы следовать дальше, вам потребуется:

• Аккаунт AWS и IAM role с доступом к Amazon Bedrock AgentCore Runtime, Memory и Evaluations, AWS Lambda и Amazon CloudWatch.
• Установленный и настроенный AWS Command Line Interface (AWS CLI) с правами на развертывание ресурсов AgentCore, функций Lambda, логов CloudWatch и, опционально, Amazon Comprehend.
• Включенные AgentCore Observability и CloudWatch Transaction Search, чтобы OTel spans попадали и в runtime log group, и в общий aws/spans log group. Transaction Search — одноразовое opt-in на уровне аккаунта. Без него AgentCore Evaluations не может собирать spans.
• Клонированный репозиторий agentcore-samples.

Шаги реализации

Полный пример, включая код агента, все четыре Lambda evaluator и скрипты развертывания, доступен в каталоге market trend agent. Следуйте README, чтобы выполнить эти шаги:

1. Разверните Market Trends Agent — одна команда uv run python deploy.py подготавливает AgentCore Runtime, Memory, IAM role и контейнер Amazon Elastic Container Registry (Amazon ECR).
2. Разверните evaluators — uv run python evaluators/scripts/deploy.py упаковывает четыре функции Lambda, создает IAM roles, регистрирует каждый evaluator в control plane AgentCore и создает online evaluation configuration с sampling 100 процентов.
3. Сгенерируйте тестовый трафик — uv run python evaluators/scripts/invoke.py запускает четыре встроенных сценария (успешный брокерский workflow, повторный визит брокера, PII bait с вымышленным SSN и анонимный chitchat), чтобы создать сессии с успешным, неуспешным и пограничным поведением.
4. Запустите on-demand evaluation — используйте AgentCore CLI или SDK, чтобы синхронно оценить конкретную сессию, изучить label и explanation для каждого evaluator и проверить поведение перед выводом в production.
5. Посмотрите результаты online evaluation — uv run python evaluators/scripts/results.py извлекает результаты из CloudWatch, сгруппированные по evaluator. Результаты также появляются как CloudWatch metrics в namespace Bedrock-AgentCore/Evaluations для дашбордов и alarms.

После выполнения инструкций в README вы можете начать отслеживать метрики оценки в консоли AgentCore Observability, как показано на следующих рисунках. Если конфигурация AgentCore Evaluation не дает результатов или вы видите ошибки либо пустые оценки, можно использовать AgentCore Evaluation Diagnostic Skill для поиска причины.

Очистка ресурсов

Чтобы избежать постоянных расходов, удалите все ресурсы, созданные в ходе этого walkthrough. Сначала удалите ресурсы evaluator (функции Lambda, IAM roles и online evaluation configuration), затем запустите скрипт очистки агента, чтобы удалить AgentCore Runtime, Memory, репозиторий ECR и остальную инфраструктуру. В README репозитория приведены точные команды для обоих шагов в разделах Cleanup Evaluators и Complete Resource Cleanup.

Рекомендации по использованию custom code-based evaluators

Когда вы начинаете оценивать агентов в production, быстро выясняется, что одни проблемы качества субъективны, а другие жестко определяются правилами. Custom code-based evaluators в AgentCore предназначены для второй категории, чтобы вы могли применять детерминированные проверки своей логикой. Процесс добавления таких evaluators всегда одинаков — независимо от того, создаете ли вы первый evaluator или масштабируете полноценный evaluation suite.

Определите, что проверять кодом

Сначала определите детерминированные измерения качества, где вы хотите исключить неоднозначность. Это те места, где человеческого суждения или одного лишь LLM reasoning недостаточно. Например, точные ограничения данных, такие как IDs или суммы, которые должны соответствовать конкретному формату или значению, структурные ограничения, например обязательные последовательности tool-call или шаги workflow, а также требования комплаенса, включая PII policies или регуляторные правила, которые нужно гарантированно применять.

Для субъективных измерений, таких как helpfulness, tone, coherence, reasoning capabilities и overall conversational quality, продолжайте использовать встроенные или собственные evaluators типа LLM-as-a-Judge. Code-based evaluators нужны для жестких, бинарных границ, где требуются детерминированные гарантии.

Чтобы сопоставить каждую задачу с нужным местом во взаимодействии, выберите уровень оценки:

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

Проверяйте реальные сценарии отказа в on-demand режиме

Обычно нужно получить подтверждение на реальном трафике до того, как новый evaluator начнет влиять на решения о развертывании или on-call alerts, и именно для этого естественно подходит on-demand evaluation. Вместо того чтобы сразу переходить к широкому внедрению, вы прогоняете evaluator на небольшой набор известных сессий и проверяете, что он надежно находит именно те проблемы, которые вам важны, а его пояснения четко указывают на span или tool call, вызвавший сбой. Если evaluator обращается к внешним системам, например детектору PII или policy engine, это также момент для проверки прав доступа, тайм-аутов и других деталей интеграции.

Затем тот же механизм можно включить в CI/CD pipeline как deployment gate. Когда вы будете уверены, как evaluator работает на отобранном тестовом наборе, вы вызываете on-demand evaluation API из pipeline и проваливаете сборку, если он выявляет критические проблемы. Это дает способ жестко обеспечивать schema validity, numerical correctness или PII hygiene еще до попадания изменений в production, оставляя online evaluation для отслеживания дрейфа и редких сбоев, а не очевидных регрессий.

Подключите это к непрерывному мониторингу

Вы переводите custom evaluator в online evaluation после того, как уверены, что он работает ожидаемым образом, позволяя ему оценивать живой трафик, а не только тестовые прогоны. На практике это означает создание online evaluation configuration, где evaluator ID размещается рядом со встроенными evaluators, на которые вы уже опираетесь, а источник данных подключается к CloudWatch log group и имени OTel service вашего агента. Sampling percentage становится главным регулятором баланса между покрытием и стоимостью: для малонагруженных агентов часто имеет смысл 100 процентов, чтобы проверять каждую сессию, а для высоконагруженных обычно выбирают диапазон 10–20 процентов, чтобы сохранить сигнал и не выйти за бюджет.

Заключение

Code-based evaluators расширяют покрытие AgentCore в тех измерениях качества, которые требуют детерминированной логики. В on-demand режиме они работают как проверки разработки и CI/CD deployment gates, возвращая синхронные оценки и пояснения на уровне spans. В online режиме тот же зарегистрированный evaluator оценивает живые production-сессии вместе со встроенными LLM-as-a-Judge evaluators и публикует результаты как CloudWatch metrics. В сочетании со встроенными evaluators custom code-based evaluators переводят надежность агента из режима «звучит правдоподобно» в режим contract-verified. Поскольку логика находится в вашей собственной Lambda, вы можете изменять проверки по мере изменения бизнес-правил. Одна регистрация evaluator подходит для локальной разработки, CI/CD-gate и непрерывного production-мониторинга, давая команде единый сигнал качества от прототипа до масштаба.

Чтобы начать, изучите документацию Amazon Bedrock AgentCore Evaluations, определите структурные и комплаенс-свойства вашего агента, которые требуют детерминированных проверок, и разверните sample evaluators из репозитория amazon-bedrock-agentcore-samples.

Материал — перевод статьи с английского.

Оригинал: Build custom code-based evaluators in Amazon Bedrock AgentCore