ADR 0087: Microsoft Agent Framework (MAF) — ориентир на слой оркестрации встроенного агентного контура¶
Статус: Accepted · следующий шаг: PoC
Дата: 2026-04-22
Связанные ADR¶
| ADR | Роль |
|---|---|
| 0038 | фасад LLM, автономный JSON-цикл, McpClientService |
| 0083 | ai.mode, в т.ч. mcp_only |
| 0008 | контракты MCP |
| 0048 | ACP, MCP-инструменты в сессии |
| 0082 | MCP loopback в одном процессе |
| Резюме: ориентир Agent-first в продукте переносим на стек: MAF — целевой слой для будущей оркестрации встроенного агента; следующий шаг — PoC (отдельная ветка/проект), без обязательства немедленного мержа в основное приложение. |
Снимок реализации¶
| Элемент | Значение |
|---|---|
| — | интеграция в main и обновление 0038 — по итогам PoC |
Резюме¶
- Microsoft Agent Framework — ориентир оркестрации встроенного агента.
- Следующий шаг — PoC; связь с 0104.
Контекст¶
- Встроенный «трек агента» (полноценная обвязка: устойчивый tool-calling, тесты, политика шагов) по сути не развёрнут: в коде есть задел (
AutonomousAgentService, минимальный контрактIAiChatProvider, внешние MCP как клиент), но нет зрелой проверки сценариев в продукте. - 0038 в разделе «Направление» уже упоминает идею единого оркестратора вместо хрупкого «JSON в свободном тексте».
- Microsoft Agent Framework (MAF) — открытый (MIT) мульти-язычный стек с первоклассной поддержкой .NET; в репозитории есть сэмплы под Azure OpenAI, OpenAI, Foundry, Ollama и др.
Пользовательский вопрос: имеет ли смысл целенаправленно рассматривать MAF при старте работ по агентной обвязке, и затрагивает ли это MCP-режимы.
Pros / Cons (анализ до принятия решения)¶
Pros (за опору на MAF для будущего встроенного контура)¶
| Плюс | Пояснение |
|---|---|
| Меньше изобретать велосипед | Готовые абстракции агента, провайдеров, сэмплы под .NET; меньше собственного кода на «цикл: модель → инструмент → наблюдение». |
| Эволюция вместо JSON-hack | Снижает приоритет 0038 «Направление» п.2 (вытаскивать JSON из текста) — при условии что выбранный провайдер/клиент в MAF закрывает нужные вызовы. |
| Мульти-провайдерность | Один стек для Azure / OpenAI-совместимого / Ollama и т.д.; проще согласовать с cloud / local в 0083. |
| Документация и экосистема | Microsoft Learn, сэмплы, предсказуемое направление развития для .NET. |
| Совпадение с «ранним» этапом | Пока нет залитого в prod объёма собственного оркестратора, стоимость смены подхода ниже, чем после годов вложений в кастомный движок. |
Cons (риски и затраты)¶
| Минус | Пояснение |
|---|---|
| Интеграционный объём | МАФ — не плагин к кнопке «Отправить»: нужны адаптеры к чату, автономному режиму, лимитам, трассам, L1–L3; регрессия local / cloud / ollama. |
| Движущаяся мишень | Относительно молодой стек; возможны ломающие обновления — нужен пинning версий и план миграций. |
| Не решает «IDE-специфику» | Привязка к IIdeMcpActions, каталогу IdeCommands, UI-политикам остаётся нашей; MAF — слой модель ↔ generic tools, а не замена кокпиту. |
| Дублирование с SK (если появится) | Если позже втянем Semantic Kernel, нужна чёткая граница (что в SK, что в MAF), иначе два «центра тяжести». |
| Зависимость от стека Microsoft | Юридически MIT и репо открыты; продуктово — привязка к приоритетам и абстракциям MS. |
Сводка по выгоде¶
- Выгодно рассматривать MAF, если цель — сфокусировать команду на CIDE-специфике (команды IDE, трассы, UX), а не писать с нуля устойчивый мульти-провайдерный agent-loop.
- Менее выгодно как «срочная замена», если ближайший релиз — только mcp_only / ACP без встроенного агента: интеграция MAF не разблокирует пользователя в этих режимах сильнее, чем уже есть (см. ниже).
Решение¶
- Принято: MAF — целевой стек для реализации пункта «единый слой оркестрации» из 0038 «Направление» п.1 для встроенного агентного контура; альтернатива «с нуля / только Semantic Kernel» для этой роли не приоритизируется, пока PoC не покажет обратное.
- Сейчас в работе: PoC в отдельной ветке или отдельном
samples/консольном проекте внутри репо (минимум: один провайдер, например Ollama или OpenAI-совместимый; один инструмент-заглушка; вызовRunAsync/ эквивалент) — без обязательства немедленного мержа в основнойCascadeIDEUI. - Критерий перехода к интеграции в
main: выполненный PoC + список адаптеров к 0038 (чат, автоном, политика L1–L3) + оценка рисков lock-in; затем патч 0038 в духе «Решение» с привязкой: что остаётся вAiProviderManager, что у MAF; при необходимости — отдельный ADR миграции UI.
Совместимость TF: CIDE и пакеты MAF¶
- CIDE: основной TFM —
net10.0(CascadeIDE.csproj,CascadeIDE.Testsи т.д.); понижения ради MAF не делаем. - NuGet (проверено по метаданным пакета): Microsoft.Agents.AI в релизной линии (например 1.2.0) явно включает целевые моникеры net10.0, net9.0, net8.0 (а также .NET Standard 2.0 и .NET Framework 4.7.2 для иных сценариев). Следовательно
net10.0CIDE покрыт основной библиотекой MAF; отдельного «обрезания» под 8/9 не требуется. - Репозиторий MAF: примеры в
dotnet/samplesсобирают и запускают сцены с--framework net10.0, в предпосылках сэмплов (например Ollama) указано .NET 10 SDK or later — в одном векторе с выбором CIDE. - Транзитивные пакеты (
Microsoft.Agents.AI.OpenAI, Foundry, и т.д.): при PoC и при мажорных апдейдах сверять вкладку Frameworks / Dependencies на NuGet для той же версии, что пинните: конфликтов сnet10.0у ядра не ожидается, но отдельный провайдер теоретически может отставать (редко) — тогда точечная проверкаdotnet restore/dotnet build.
Параллельный «старый» автономный путь (feature flag)¶
Решение: отдельный флаг / долгий dual-path для текущей реализации AutonomousAgentService (JSON из текста) не закладывать. Почему: встроенный агентный трек не имеет внешнего legacy-набора пользователей и не доведён до зрелого контракта; «старый» путь — задел в коде, а не обязательство совместимости. При внедрении MAF (или иного оркестратора) достаточно заменить реализацию в ветке с регрессией по сценариям и тестам, без обязательной параллельной опции.
До согласованного итога PoC не делаем: миграцию прод-кода в основном приложении, смену зависимостей в корневом CascadeIDE.csproj без отдельного согласования, изменение публичного API MCP.
Влияние на MCP (почему mcp_only и «IDE как сервер» не «ломаются»)¶
| Тема | Смысл |
|---|---|
Протокол MCP, реестр ide_*, внешние stdio-серверы |
Остаются инфраструктурой IDE и контрактом для клиентов; MAF не заменяет MCP и не отменяет 0008. |
ai.mode = mcp_only (0083) |
Встроенный LLM не вызывается для текста ассистента; ответ идёт из контура внешнего MCP. Это ортогонально MAF: MAF касается внутреннего контура «модель в процессе IDE». Режим mcp_only не требует MAF и не становится «хуже» от отсутствия MAF. |
| ACP / Cursor-агент | Внешний агент по 0016 не про MAF; подмешивание MCP в сессию ACP — как в 0048. |
Автономный режим + McpClientService |
Сегодня: модель (через фасад) + JSON + вызов тулов. Будущая связка с MAF: логика «кто и как зовёт CallToolAsync / IDE-команды» может переехать в оркестратор MAF, но протокол вызова внешних MCP остаётся тем же слоем инфраструктуры. |
Кратко: переход встроенного сценария на MAF не меняет семантику MCP-only и не убирает MCP из IDE; меняется (гипотетически) реализация встроенного цикла агента, когда к нему придут в разработке.
Последствия (принятое направление)¶
- В TECH-документации к оркестрации встроенного агента — именованный референс (MAF) вместо неопределённого «самописного оркестратора».
- После PoC: зависимости
Microsoft.Agents.*(и транзитивно — провайдеры), политика обновлений, CI на совместимость. - 0038 — патч по итогам PoC: раздел «Решение / Направление» с привязкой, что остаётся
AiProviderManager, что уходит в MAF.
Открытые вопросы (уточнить до / в ходе PoC)¶
- Один PoC-провайдер (Ollama vs облако) и критерий «успех» для tool-calling.
- Связь с Semantic Kernel, если в репо появятся сценарии, пересекающиеся по зоне ответственности (избегать дублирования оркестрации).
Проверено: 2026-04-22 (состояние 0038, 0083; публичный репозиторий MAF, лицензия MIT в корне репо; совместимость TF: Microsoft.Agents.AI 1.2.0 на NuGet — net10.0 в списке included TFMs). История: 2026-04-22 — направление принято, зафиксирован следующий шаг: PoC.