| 1 | # ADR 0087: Microsoft Agent Framework (MAF) — ориентир на слой оркестрации **встроенного** агентного контура |
| 2 | |
| 3 | **Статус:** Accepted · **следующий шаг: PoC** |
| 4 | **Дата:** 2026-04-22 |
| 5 | |
| 6 | ## Связанные ADR |
| 7 | |
| 8 | | ADR | Роль | |
| 9 | |-----|------| |
| 10 | | [0038](0038-agent-facade-ai-provider-and-tool-orchestration.md) | фасад LLM, автономный JSON-цикл, `McpClientService` | |
| 11 | | [0083](0083-ai-mode-and-nested-settings-toml.md) | `ai.mode`, в т.ч. `mcp_only` | |
| 12 | | [0008](0008-mcp-contracts-and-testable-infrastructure.md) | контракты MCP | |
| 13 | | [0048](0048-cursor-acp-chat-ide-parity-and-mcp-tool-surface.md) | ACP, MCP-инструменты в сессии | |
| 14 | | [0082](0082-acp-ide-mcp-loopback-single-process.md) | MCP loopback в одном процессе | |
| 15 | **Резюме:** ориентир **Agent-first** в продукте переносим на стек: **MAF** — целевой слой для будущей оркестрации встроенного агента; **следующий шаг** — **PoC** (отдельная ветка/проект), без обязательства немедленного мержа в основное приложение. |
| 16 | |
| 17 | --- |
| 18 | |
| 19 | <a id="adr0087-context"></a> |
| 20 | |
| 21 | ### Снимок реализации |
| 22 | |
| 23 | | Элемент | Значение | |
| 24 | |---------|----------| |
| 25 | | — | интеграция в `main` и обновление [0038](0038-agent-facade-ai-provider-and-tool-orchestration.md) — по итогам PoC | |
| 26 | |
| 27 | ## Резюме |
| 28 | |
| 29 | - **Microsoft Agent Framework** — ориентир оркестрации встроенного агента. |
| 30 | - Следующий шаг — PoC; связь с [0104](0104-cognitive-decomposition-loop-for-maf-prompt-orchestration.md). |
| 31 | |
| 32 | --- |
| 33 | ## Контекст |
| 34 | |
| 35 | 1. **Встроенный** «трек агента» (полноценная обвязка: устойчивый tool-calling, тесты, политика шагов) **по сути не развёрнут**: в коде есть задел (`AutonomousAgentService`, минимальный контракт `IAiChatProvider`, внешние MCP как клиент), но **нет** зрелой проверки сценариев в продукте. |
| 36 | 2. [0038](0038-agent-facade-ai-provider-and-tool-orchestration.md) в разделе «Направление» уже упоминает идею **единого оркестратора** вместо хрупкого «JSON в свободном тексте». |
| 37 | 3. [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) (MAF) — **открытый** (MIT) мульти-язычный стек с **первоклассной поддержкой .NET**; в репозитории есть сэмплы под Azure OpenAI, OpenAI, Foundry, **Ollama** и др. |
| 38 | |
| 39 | Пользовательский вопрос: **имеет ли смысл целенаправленно рассматривать MAF** при старте работ по агентной обвязке, и **затрагивает ли это MCP-режимы**. |
| 40 | |
| 41 | --- |
| 42 | |
| 43 | <a id="adr0087-pros-cons"></a> |
| 44 | |
| 45 | ## Pros / Cons (анализ до принятия решения) |
| 46 | |
| 47 | <a id="adr0087-pros"></a> |
| 48 | |
| 49 | ### Pros (за опору на MAF для будущего встроенного контура) |
| 50 | |
| 51 | | Плюс | Пояснение | |
| 52 | |------|-----------| |
| 53 | | **Меньше изобретать велосипед** | Готовые абстракции агента, провайдеров, сэмплы под .NET; меньше собственного кода на «цикл: модель → инструмент → наблюдение». | |
| 54 | | **Эволюция вместо JSON-hack** | Снижает приоритет [0038 «Направление» п.2](0038-agent-facade-ai-provider-and-tool-orchestration.md#adr0038-p2) (вытаскивать JSON из текста) — при условии что выбранный провайдер/клиент в MAF закрывает нужные вызовы. | |
| 55 | | **Мульти-провайдерность** | Один стек для Azure / OpenAI-совместимого / Ollama и т.д.; проще согласовать с **cloud / local** в [0083](0083-ai-mode-and-nested-settings-toml.md). | |
| 56 | | **Документация и экосистема** | Microsoft Learn, сэмплы, предсказуемое направление развития для .NET. | |
| 57 | | **Совпадение с «ранним» этапом** | Пока **нет** залитого в prod объёма собственного оркестратора, **стоимость смены подхода ниже**, чем после годов вложений в кастомный движок. | |
| 58 | |
| 59 | <a id="adr0087-cons"></a> |
| 60 | |
| 61 | ### Cons (риски и затраты) |
| 62 | |
| 63 | | Минус | Пояснение | |
| 64 | |------|-----------| |
| 65 | | **Интеграционный объём** | МАФ — не плагин к кнопке «Отправить»: нужны адаптеры к чату, автономному режиму, лимитам, трассам, L1–L3; регрессия **local / cloud / ollama**. | |
| 66 | | **Движущаяся мишень** | Относительно молодой стек; возможны **ломающие** обновления — нужен пинning версий и план миграций. | |
| 67 | | **Не решает «IDE-специфику»** | Привязка к `IIdeMcpActions`, каталогу `IdeCommands`, UI-политикам остаётся **нашей**; MAF — слой **модель ↔ generic tools**, а не замена кокпиту. | |
| 68 | | **Дублирование с SK (если появится)** | Если позже втянем Semantic Kernel, нужна **чёткая граница** (что в SK, что в MAF), иначе два «центра тяжести». | |
| 69 | | **Зависимость от стека Microsoft** | Юридически MIT и репо открыты; **продуктово** — привязка к приоритетам и абстракциям MS. | |
| 70 | |
| 71 | ### Сводка по выгоде |
| 72 | |
| 73 | - **Выгодно рассматривать MAF**, если цель — **сфокусировать** команду на CIDE-специфике (команды IDE, трассы, UX), а **не** писать с нуля устойчивый мульти-провайдерный agent-loop. |
| 74 | - **Менее выгодно** как «срочная замена», если ближайший релиз — только **mcp_only** / ACP без встроенного агента: интеграция MAF **не** разблокирует пользователя в этих режимах сильнее, чем уже есть (см. ниже). |
| 75 | |
| 76 | --- |
| 77 | |
| 78 | <a id="adr0087-decision"></a> |
| 79 | |
| 80 | ## Решение |
| 81 | |
| 82 | 1. **Принято:** **MAF** — целевой стек для реализации пункта «единый слой оркестрации» из [0038 «Направление» п.1](0038-agent-facade-ai-provider-and-tool-orchestration.md) для **встроенного** агентного контура; альтернатива «с нуля / только Semantic Kernel» для этой роли **не** приоритизируется, пока PoC не покажет обратное. |
| 83 | 2. **Сейчас в работе:** **PoC** в отдельной ветке или отдельном `samples`/консольном проекте внутри репо (минимум: один провайдер, например Ollama или OpenAI-совместимый; один инструмент-заглушка; вызов `RunAsync` / эквивалент) — **без** обязательства немедленного мержа в основной `CascadeIDE` UI. |
| 84 | 3. **Критерий перехода к интеграции в `main`:** выполненный PoC + **список адаптеров** к [0038](0038-agent-facade-ai-provider-and-tool-orchestration.md) (чат, автоном, политика L1–L3) + **оценка** рисков lock-in; затем **патч** [0038](0038-agent-facade-ai-provider-and-tool-orchestration.md) в духе «Решение» с привязкой: что остаётся в `AiProviderManager`, что у MAF; при необходимости — отдельный ADR миграции UI. |
| 85 | |
| 86 | <a id="adr0087-tfm-packages"></a> |
| 87 | |
| 88 | ### Совместимость TF: CIDE и пакеты MAF |
| 89 | |
| 90 | - **CIDE:** основной TFM — **`net10.0`** (`CascadeIDE.csproj`, `CascadeIDE.Tests` и т.д.); понижения ради MAF **не делаем**. |
| 91 | - **NuGet (проверено по метаданным пакета):** [Microsoft.Agents.AI](https://www.nuget.org/packages/Microsoft.Agents.AI/) в релизной линии (например **1.2.0**) явно включает целевые моникеры **net10.0**, **net9.0**, **net8.0** (а также .NET Standard 2.0 и .NET Framework 4.7.2 для иных сценариев). Следовательно **`net10.0` CIDE покрыт** основной библиотекой MAF; отдельного «обрезания» под 8/9 не требуется. |
| 92 | - **Репозиторий MAF:** примеры в `dotnet/samples` собирают и запускают сцены с `--framework net10.0`, в предпосылках сэмплов (например Ollama) указано **.NET 10 SDK or later** — в одном векторе с выбором CIDE. |
| 93 | - **Транзитивные пакеты** (`Microsoft.Agents.AI.OpenAI`, Foundry, и т.д.): при PoC и при мажорных апдейдах сверять вкладку **Frameworks / Dependencies** на NuGet **для той же версии**, что пинните: конфликтов с `net10.0` у ядра не ожидается, но отдельный провайдер теоретически может отставать (редко) — тогда **точечная** проверка `dotnet restore` / `dotnet build`. |
| 94 | |
| 95 | <a id="adr0087-legacy-autonomous-path"></a> |
| 96 | |
| 97 | ### Параллельный «старый» автономный путь (feature flag) |
| 98 | |
| 99 | **Решение:** отдельный флаг / долгий dual-path для текущей реализации `AutonomousAgentService` (JSON из текста) **не** закладывать. **Почему:** встроенный агентный трек **не** имеет внешнего legacy-набора пользователей и **не** доведён до зрелого контракта; «старый» путь — задел в коде, а не обязательство совместимости. При внедрении MAF (или иного оркестратора) достаточно **заменить реализацию** в ветке с регрессией по сценариям и тестам, без обязательной параллельной опции. |
| 100 | |
| 101 | **До согласованного итога PoC не делаем:** миграцию прод-кода в основном приложении, смену зависимостей в корневом `CascadeIDE.csproj` без отдельного согласования, изменение публичного API MCP. |
| 102 | |
| 103 | --- |
| 104 | |
| 105 | <a id="adr0087-mcp-compatibility"></a> |
| 106 | |
| 107 | ## Влияние на MCP (почему `mcp_only` и «IDE как сервер» не «ломаются») |
| 108 | |
| 109 | | Тема | Смысл | |
| 110 | |------|--------| |
| 111 | | **Протокол MCP, реестр `ide_*`, внешние stdio-серверы** | Остаются **инфраструктурой** IDE и контрактом для клиентов; MAF **не** заменяет MCP и **не** отменяет [0008](0008-mcp-contracts-and-testable-infrastructure.md). | |
| 112 | | **`ai.mode = mcp_only`** ([0083](0083-ai-mode-and-nested-settings-toml.md)) | Встроенный LLM **не вызывается** для текста ассистента; ответ идёт из контура **внешнего** MCP. Это **ортогонально** MAF: MAF касается **внутреннего** контура «модель в процессе IDE». Режим `mcp_only` **не требует** MAF и **не** становится «хуже» от отсутствия MAF. | |
| 113 | | **ACP / Cursor-агент** | Внешний агент по [0016](0016-agent-client-protocol-external-agent.md) **не** про MAF; подмешивание MCP в сессию ACP — как в [0048](0048-cursor-acp-chat-ide-parity-and-mcp-tool-surface.md). | |
| 114 | | **Автономный режим + `McpClientService`** | Сегодня: модель (через фасад) + JSON + вызов тулов. **Будущая** связка с MAF: логика «кто и как зовёт `CallToolAsync` / IDE-команды» может **переехать** в оркестратор MAF, но **протокол** вызова внешних MCP **остаётся** тем же слоем инфраструктуры. | |
| 115 | |
| 116 | **Кратко:** переход **встроенного** сценария на MAF **не** меняет семантику **MCP-only** и **не** убирает MCP из IDE; меняется (гипотетически) реализация **встроенного** цикла агента, когда к нему **придут** в разработке. |
| 117 | |
| 118 | --- |
| 119 | |
| 120 | <a id="adr0087-consequences"></a> |
| 121 | |
| 122 | ## Последствия (принятое направление) |
| 123 | |
| 124 | - В TECH-документации к оркестрации встроенного агента — **именованный** референс (**MAF**) вместо неопределённого «самописного оркестратора». |
| 125 | - После PoC: зависимости `Microsoft.Agents.*` (и транзитивно — провайдеры), политика обновлений, CI на совместимость. |
| 126 | - [0038](0038-agent-facade-ai-provider-and-tool-orchestration.md) — **патч** по итогам PoC: раздел «Решение / Направление» с привязкой, что остаётся `AiProviderManager`, что уходит в MAF. |
| 127 | |
| 128 | --- |
| 129 | |
| 130 | <a id="adr0087-open-questions"></a> |
| 131 | |
| 132 | ## Открытые вопросы (уточнить до / в ходе PoC) |
| 133 | |
| 134 | 1. Один **PoC-провайдер** (Ollama vs облако) и критерий «успех» для tool-calling. |
| 135 | 2. Связь с [Semantic Kernel](https://github.com/microsoft/semantic-kernel), если в репо появятся сценарии, пересекающиеся по зоне ответственности (избегать дублирования оркестрации). |
| 136 | |
| 137 | --- |
| 138 | |
| 139 | **Проверено:** 2026-04-22 (состояние [0038](0038-agent-facade-ai-provider-and-tool-orchestration.md), [0083](0083-ai-mode-and-nested-settings-toml.md); публичный репозиторий MAF, лицензия MIT в корне репо; **совместимость TF:** [Microsoft.Agents.AI 1.2.0 на NuGet](https://www.nuget.org/packages/Microsoft.Agents.AI/1.2.0#supportedframeworks-body-tab) — **net10.0** в списке included TFMs). **История:** 2026-04-22 — направление **принято**, зафиксирован **следующий шаг: PoC**. |
| 140 | |