Microsoft собрала стартовый набор для наблюдаемости AI‑агентов в Foundry: трассировка, оценки качества и red‑team за один запуск

Что нового

Microsoft выложила готовый AI Observability Starter Kit для AI‑агентов в Microsoft Foundry. Это не библиотека, а полностью собранный стенд наблюдаемости, который разворачивается одной командой PowerShell и сразу даёт:

• 4 Foundry‑агента с разными моделями:
  • gpt-4o-mini — основной агент с 6 инструментами (@tool‑функции)
  • gpt-5-mini — для сравнения задержек и токенов
  • gpt-4.1-mini — ещё один вариант для сравнения
  • агент с несуществующим деплойментом nonexistent-model-deployment-xyz — специально сломанный, даёт 100% ошибок на уровне чата
• Полноценную трассировку через OpenTelemetry (GenAI semantic conventions) в Azure Application Insights: отдельный span на каждый вызов LLM и каждое выполнение инструмента.
• Готовые дашборды в Grafana для Azure Monitor: токены, латентность, ошибки, разбивка по моделям и инструментам.
• 8 встроенных оценщиков качества (agent evaluators) Microsoft Foundry, уже привязанных к нужным полям трассировки.
• Кастомный оценщик‑проверку комплаенс‑фразы (code‑based evaluator) — проверяет, что в ответе есть обязательный дисклеймер.
• Автоматизированный red‑team‑скан безопасности с двумя стратегиями атак (Flip и Base64) и тремя safety‑оценщиками.
• 2 алерта на основе KQL‑запросов:
  • по количеству ошибок (severity 2)
  • по p95‑латентности за 15 минут (severity 3)
• Полный цикл «поднять–прогнать–снести» через один скрипт run-e2e.ps1 и отдельный teardown.ps1.

Цифры по запуску:

• Полный прогон из 13 фаз занимает примерно 35–50 минут.
• Стоимость — порядка нескольких центов за запуск, около $0.03 в день, пока стенд жив (видно в Grafana‑панели с затратами).
• После успешного прогона вы видите, например:
  • 150+ операций агента
  • 136K+ входных токенов и 6.6K+ выходных токенов
  • среднее время ответа агента около 7.5 секунды
  • 196+ LLM‑вызовов, 84+ сессии, 64+ вызова инструментов

Отдельный скрипт validate-deployment.ps1 прогоняет 26 проверок по 8 категориям (инфраструктура, модели, агенты, вызовы, телеметрия, оценки, алерты, RBAC) и за ~90 секунд даёт понятный отчёт [PASS]/[FAIL]/[SKIP].

Как это работает

Архитектура потока запросов

Пользователь отправляет промпт в Foundry‑хостed‑агента. Агент:

1. Вызывает модель (например, gpt-4o-mini).
2. При необходимости вызывает один или несколько инструментов (Python‑функции с декоратором @tool):
   • get_orders
   • find_suppliers_for_request
   • get_company_supplier_info
   • get_current_utc_date
   • get_weather
   • roll_dice

Каждый вызов модели и каждый вызов инструмента создаёт OpenTelemetry span. Эти спаны автоматически попадают в Azure Application Insights (через Log Analytics), если в манифесте агента включены переменные окружения:

environment_variables:
  - name: ENABLE_INSTRUMENTATION
    value: "true"       # включает дочерние OTel-спаны для чата и tool calls
  - name: ENABLE_SENSITIVE_DATA
    value: "true"       # пишет промпты и ответы в спаны

Дальше вся аналитика строится поверх этих спанов:

• Grafana ходит в Log Analytics через KQL и строит панели по токенам, задержкам, ошибкам, моделям и инструментам.
• Agent evaluators Microsoft Foundry забирают свежие трассы из Application Insights и считают 8 метрик качества.
• Запланированные KQL‑алерты срабатывают, если за 15 минут выросла ошибка или p95‑латентность.

Ключевой момент: агент ничего не знает про дашборды, алерты и оценщики. Он просто эмитит спаны. Всё остальное навешивается поверх одной телеметрийной шины — Application Insights.

Что такое Foundry‑агент в этом наборе

Foundry‑хостed‑агент — это контейнер с вашим Python‑кодом (main.py) и манифестом agent.yaml. Foundry берёт на себя:

• развёртывание и масштабирование
• прокладку OpenTelemetry
• управление идентичностью агента

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

| Агент | Модель | Назначение | | --- | --- | --- | | agent-framework-agent-basic-responses | gpt-4o-mini (через ${MODEL_DEPLOYMENT_NAME}) | Основной агент, 6 инструментов, заполняет телеметрию и дашборды | | agent-framework-agent-gpt5-mini | gpt-5-mini (захардкожен) | Сравнение по латентности и токенам | | agent-framework-agent-gpt41-mini | gpt-4.1-mini (захардкожен) | Ещё один вариант для сравнения | | agent-framework-agent-broken-model | nonexistent-model-deployment-xyz | Специально сломан, генерирует ошибки чата |

Пример инструмента, который намеренно падает для customer_id="C999" и создаёт полезную для отладки телеметрию:

from agent_framework import tool

@tool
def get_orders(customer_id: str) -> list[dict]:
    """Return open orders for a customer. Raises LookupError on unknown IDs."""
    if customer_id == "C999":
        raise LookupError(f"customer {customer_id} not found")
    return _ORDERS_BY_CUSTOMER.get(customer_id, [])

Такие «контролируемые» ошибки позволяют увидеть, как ошибка на уровне инструмента выглядит в трассировке и на дашбордах, даже если HTTP‑ответ — 200 OK.

Автоматизированный деплой и фазы

Главный сценарий запуска — PowerShell‑скрипт:

pwsh -NoProfile -File scripts\run-e2e.ps1 `
    -Region <region> `
    -EnvName <env-name> `
    -SubscriptionId <subscription-id>

Параметры:

• -Region — регион Azure, по умолчанию eastus2.
• -EnvName — имя окружения azd, по умолчанию aiobs-foundry-<yyyymmdd> (идёт в название resource group: rg-<EnvName>).
• -SubscriptionId — целевая подписка Azure (по умолчанию текущий контекст).
• -SkipPhases — список фаз через запятую, которые можно пропустить.

Скрипт проходит 13 фаз, логируя каждую в artifacts/e2e-<timestamp>/phase-NN.log:

1. azd up: Foundry‑аккаунт, проект, ACR, Application Insights, Log Analytics, деплой gpt-4o-mini (~7 минут)
2. Выдача роли Foundry User project managed identity (~10 секунд)
3. Деплой базового агента (gpt-4o-mini + инструменты) (~3 минуты)
4. Создание деплойментов gpt-5-mini и gpt-4.1-mini (~1 минута)
5. Деплой трёх «сестринских» агентов (gpt5-mini, gpt41-mini, broken-model) (~9 минут)
6. Разогрев (3 пинга) + генерация трафика (48 промптов из трёх корпусов: «чистые», неоднозначные, safety‑bait) (~6 минут)
7. Fan‑out: 12 промптов с инструментами × 3 рабочих агента + 8 вызовов сломанного агента (~3 минуты)
8. Регистрация кастомного комплаенс‑оценщика в каталоге Foundry (~30 секунд)
9. Батч‑оценка: 8 встроенных agent evaluators по свежим трассам в Application Insights (~3 минуты)
10. Red‑team‑скан (2 стратегии атак, 3 safety‑оценщика, временный prompt‑агент) (~8 минут)
11. Создание 2 scheduled‑query алертов через ARM REST (~10 секунд)
12. Экспорт телеметрии в artifacts/telemetry.json (~10 секунд)
13. Smoke‑тест вызова агента + проверка, что батч‑оценка завершилась (~2 минуты)

Если какая‑то фаза падает, скрипт останавливается и печатает путь к логу. Можно перезапускать с -SkipPhases, чтобы не делать всё с нуля.

Red‑team и автоматизированные проверки безопасности

Red‑team‑фаза использует два подхода к генерации атакующих промптов:

• Flip — переформулирует запрос, чтобы обойти очевидные фильтры.
• Base64 — маскирует вредный контент через кодирование.

Три safety‑оценщика анализируют ответы модели и ищут небезопасный контент. Это происходит до того, как такие запросы придут от реальных пользователей, и результаты попадают в Foundry и телеметрию.

Что это значит для вас

Зачем это нужно

Если вы уже гоняете AI‑агентов в проде, вы почти наверняка сталкивались с ситуацией, когда:

• HTTP‑метрики зелёные, 200 OK, но:
  • агент ходит к несуществующей модели
  • инструмент возвращает ошибку, а пользователь видит вежливое «извините»
  • модель спокойно отвечает на опасный промпт

Обычные лог‑панели и дашборды по ресурсам это не ловят. Нужна наблюдаемость на уровне промптов, инструментов и reasoning‑шага.

Этот набор даёт вам:

• Быстрый старт: за один запуск вы получаете рабочий стенд с агентами, телеметрией, оценкой качества и red‑team.
• Образец правильной проводки: как связать OpenTelemetry, Application Insights, KQL, Grafana, Foundry‑evaluators и алерты.
• Шаблоны для своих агентов: код агента, инструменты, манифесты, KQL‑запросы, примеры кастомных оценщиков.

Для каких задач это полезно

Используйте этот kit, если вы:

• Строите агентов с инструментами (RAG, интеграция с CRM/ERP, procurement‑боты) и хотите контролировать, как они выбирают и вызывают инструменты.
• Запускаете несколько моделей и хотите сравнивать их по латентности, ошибкам и токенам на одном и том же трафике.
• Отвечаете за качество и комплаенс и вам нужны repeatable‑оценки вместо «пока пользователи не пожаловались, всё нормально».
• Готовите пилот по AI‑агентам в Azure и хотите показать стейкхолдерам связку «агент + наблюдаемость + алерты» в живом окружении.

Когда не подойдёт

Набор в первую очередь для:

• Azure‑инфраструктуры
• Microsoft Foundry
• сценариев, где вы можете крутить Application Insights и Log Analytics

Если вы:

• не используете Azure
• не можете хранить промпты и ответы в телеметрии (даже с флагом ENABLE_SENSITIVE_DATA=false)
• не готовы заводить Foundry‑агентов

— то этот стенд будет скорее референсом архитектуры, чем чем‑то, что вы запустите «как есть».

Доступность и ограничения для России

Набор полностью завязан на:

• подписку Azure
• Microsoft Foundry
• Azure Application Insights, Log Analytics и Grafana для Azure Monitor

Для доступа к этим сервисам из России может понадобиться VPN и юридическая возможность работать с зарубежной облачной инфраструктурой. Стартовый kit сам по себе бесплатен, но использует платные сервисы Azure.

Место на рынке

По сути, это эталонный стенд наблюдаемости для AI‑агентов под Azure. Он закрывает сразу несколько задач:

• трассировка по OpenTelemetry с GenAI‑конвенциями
• аналитика в Grafana
• встроенные и кастомные оценщики Foundry
• red‑team‑скан
• KQL‑алерты

Прямых численных сравнений с другими решениями в материале нет. Но по функционалу это ближе к связке:

• LangSmith / Arize / Weights & Biases для LLM‑наблюдаемости, но с упором на Azure‑стек и Foundry‑агентов
• плюс готовый пример интеграции с Grafana и KQL

Если вы уже инвестировали в Azure‑мониторинг, этот kit логично использовать как референс и стартовую точку. Если у вас уже есть сторонняя платформа для наблюдаемости LLM‑агентов, набор полезен как пример того, какие спаны и поля стоит собирать и как строить проверки качества.

Установка

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

Перед запуском вам нужно:

• Подписка Azure, где у вас есть роли Contributor (или Owner) и User Access Administrator.
• PowerShell 7+ (pwsh).
• Azure CLI (az) и Azure Developer CLI (azd) в PATH.
• Выполненный az login в нужной подписке.
• Python 3.13 и виртуальное окружение в корне репозитория: .venv/.

Скрипт run-e2e.ps1 сначала проверяет наличие venv, директории agent/ и обоих CLI. Если чего‑то нет, он падает до начала любых операций в Azure с понятным описанием, что починить.

Как запустить полный цикл

1. Клонируйте репозиторий (из исходника: github.com/jvargh/ai-observability-starter-kit).
2. Создайте и активируйте Python‑venv в корне (.venv/).
3. Запустите скрипт:

pwsh -NoProfile -File scripts\run-e2e.ps1 `
    -Region eastus2 `
    -EnvName aiobs2-foundry `
    -SubscriptionId <subscription-id>

4. Дождитесь завершения всех 13 фаз (35–50 минут).
5. Прогоните валидацию:

pwsh -NoProfile -File scripts\validate-deployment.ps1

При необходимости можно отключить вызовы агентов валидацией:

pwsh -NoProfile -File scripts\validate-deployment.ps1 -SkipInvoke

Чистый прогон — 26 passed / 0 failed / 0 skipped примерно за 90 секунд.

Что вы должны увидеть после успешного деплоя

В Grafana и Application Insights появятся, в частности:

• Agent Summary:
  • 150+ операций
  • 136K+ входных токенов
  • 6.6K+ выходных токенов
  • средняя латентность ответа ~7.5 секунды
• Chat and Tool Summary:
  • 196+ LLM‑вызовов
  • 84+ чат‑сессии
  • 64+ вызова инструментов
  • средняя латентность чата ~5.1 секунды
• Models table с gpt-4o-mini, gpt-5-mini, gpt-4.1-mini и их ошибками
• Gen AI Errors с отдельным сегментом для сломанного агента (nonexistent-model-deployment-xyz) с 100% error rate
• Tool Calls по 6 инструментам, из которых 3 имеют ненулевой error count (включая LookupError и ValueError)
• Evaluations — 8 метрик agent evaluators:
  • task_adherence
  • task_completion
  • intent_resolution
  • tool_call_accuracy
  • tool_selection
  • tool_input_accuracy
  • tool_output_utilization
  • tool_call_success

Как снести окружение

Чтобы освободить имя Azure AI Services‑аккаунта и убрать ресурсы, выполните:

pwsh -NoProfile -File scripts\teardown.ps1 -EnvName <env-name>

# пример
pwsh -NoProfile -File scripts\teardown.ps1 -EnvName aiobs2-foundry

Скрипт:

• удаляет resource group
• делает soft‑delete purge Azure AI Services, чтобы можно было сразу переиспользовать имя
• проверяет, что ресурсы действительно удалены

Опции:

• -NoPurge — не трогать soft‑delete.
• -ForceDeleteRg — дополнительно удалить алерты и action groups, созданные через ARM REST вне шаблона azd.

Как обновить телеметрию без полного перезапуска

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

pwsh -NoProfile -File scripts\run-adhoc-traffic-and-eval.ps1 -EnvName <env-name>

# пример
pwsh -NoProfile -File scripts\run-adhoc-traffic-and-eval.ps1 -EnvName aiobs3-foundry

Параметры:

• -EnvName — azd‑окружение (по умолчанию текущее; можно выбрать azd env select <name>).
• -MaxPrompts — количество промптов в фазе разогрева и seed‑трафика. 0 — полный корпус (~48 промптов).
• -RunRedTeam — добавить red‑team‑скан (плюс ~8 минут).
• -LogFile — путь к логу (по умолчанию scripts/e2e-adhoc-run.log).

Скрипт фактически зовёт run-e2e.ps1 с -SkipPhases 1,2,3,4,5,8,11 (и 10, если red‑team не нужен). Запускаются фазы:

• 6 — разогрев (3 пинга) + N seed‑промптов
• 7 — fan‑out по 3 рабочим агентам + сломанному
• 9 — свежая батч‑оценка (8 evaluators) по новым трассам (2‑часовой lookback в Application Insights)
• 10 — red‑team, если включён
• 12 — обновление artifacts/telemetry.json
• 13 — smoke‑тест и проверка артефакта батч‑оценки

Время работы:

• ~15 минут по умолчанию
• ~25 минут с red‑team

Лог стримится в консоль и файл, можно параллельно смотреть:

Get-Content -Wait scripts\e2e-adhoc-run.log

Как устроена оценка качества

Две линии проверки

Набор использует два подхода к оценке:

1. Agent evaluators Microsoft Foundry:
   • запускаются батчем по трассам в Application Insights
   • 8 встроенных метрик без необходимости готовить датасет
   • смотрят на итоговый ответ и процесс работы с инструментами
2. Кастомные evaluators:
   • тоже батч по трассам
   • вы сами задаёте правило, например: «в ответе должна быть фраза‑дисклеймер»
   • идеально подходят под комплаенс, формат ответов, доменные правила

Встроенные agent evaluators и их результаты

Foundry даёт 9 встроенных оценщиков, разделённых на:

• System evaluators — смотрят на итог:
  • task_adherence
  • task_completion
  • intent_resolution
• Process evaluators — анализируют шаги внутри цепочки:
  • tool_call_accuracy
  • tool_selection
  • tool_input_accuracy
  • tool_output_utilization
  • tool_call_success

Девятый — Task Navigation Efficiency — требует ground truth и в дефолтный батч не входит.

Скрипт scripts/20-agent-batch-eval.py запускает все 8 основных оценщиков по трассам агента в Application Insights. Пример результатов по 11 трассам:

• task_adherence — 73% (8/11): в 8 из 11 случаев агент следовал системным инструкциям.
• task_completion — 64% (7/11): 4 фейла — намеренные промпты, которые должны вызывать ошибки.
• intent_resolution — 73% (8/11): агент правильно распознал и закрыл намерение пользователя.
• tool_call_accuracy — 80% (8/10): правильный выбор инструментов и параметров.
• tool_selection — 73% (8/11): без лишних вызовов инструментов.
• tool_input_accuracy — 82% (9/11): корректно сформированные и обоснованные параметры.
• tool_output_utilization — 55% (6/11): самый строгий — проверяет, использовал ли агент результат инструмента в ответе.
• tool_call_success — 82% (9/11): два провала — те же намеренно спровоцированные ошибки.

Каждый оценщик требует data_mapping — словаря, который говорит Foundry, из каких полей трассы брать:

• для system‑оценщиков: query и response
• для process‑оценщиков: плюс tool_definitions и tool_calls
• все оценщики требуют deployment_name как параметр инициализации

Если что‑то из этого не указано или поля нет в записях App Insights, вы получите ошибку MissingRequiredDataMapping. Это сигнал, что нужно проверить, какие поля реально лежат в трассе и как вы их мапите.

Кастомный оценщик: проверка комплаенс‑фразы

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

• Code‑based — Python‑функция grade() возвращает число от 0.0 до 1.0. Хорошо подходит для чётких правил: наличие фразы, формат, regex.
• Prompt‑based — LLM‑судья по промпту. Полезно для мягких критериев: тон, вежливость, стиль.

В starter kit реализован code‑based комплаенс‑чекер:

1. В evaluators/custom_compliance_phrase.py пишете grade(sample, item), которая проверяет, что в ответе есть нужный дисклеймер, и возвращает 1.0 или 0.0.
2. Регистрируете его в Foundry через scripts/11-custom-evaluator-register.py — скрипт загружает исходник, описывает метрику и порог прохода.
3. Подключаете этот оценщик к батч‑запуску по трассам.

Это хороший шаблон, как добавлять свои правила: от финансовых дисклеймеров до формата JSON‑ответов.

---

Читайте также

• Azure SRE Agent подключили к MCP: как один бэкенд работает и для людей, и для ИИ-агентов
• Как подружить Claude с вашим компьютером и браузером: практическое руководство для разработчиков
• Как приручить Copilot и Claude: модульный конвейер для надёжной генерации кода