Написал(а) Перевод статьи: Build Your Own AI Agent Harness in CSharp, the MafClaw Live Series
📄 Файл перевода
# Создание собственного агентного каркаса ИИ в C#: серия MafClaw Live*16 сентября 2026 г. · 5 реакций*## Оглавление* Что мы строим за четыре сессии* Сначала: что такое агентный каркас?* Агент, который мы строим* Сессия 1: превращение модели в агента* Сессия 2: безопасная работа с пользовательскими данными* Вопрос из аудитории стал новым примером* Сессия 3: навыки, оболочка, CodeAct и фоновые агенты* Сессия 4: подготовка агента к производственной среде* Почему начать с каркаса?* Присоединяйтесь к серии* Узнать больше## Что мы строим за четыре сессии
Мы начинаем с этого:
```csharp
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
ChatOptions = new ChatOptions
{
Instructions = instructions,
Tools = tools
}
});Затем развиваем того же агента на четырёх этапах:
- Даём ему инструменты, веб-поиск и план.
- Позволяем работать с файлами, запросами на одобрение и постоянной памятью.
- Добавляем навыки, оболочку, CodeAct и фоновых агентов.
- Добавляем наблюдаемость, управление, оценки и размещённое развёртывание.
Это полный путь: от одного вызова вокруг IChatClient до способного агента, который мы можем инспектировать, оценивать, управлять и запускать в Microsoft Foundry.
Сначала: что такое агентный каркас?
Языковая модель может генерировать текст. Агенту нужно больше.
Ему нужен цикл, который может вызывать инструменты, проверять результаты, обновлять план, запоминать полезную информацию, запрашивать одобрение рискованных действий, управлять растущим контекстным окном и продолжать работу до завершения задачи.
Это окружающее время выполнения и есть каркас.
Откуда происходит термин
Команда Microsoft Agent Framework представила концепцию в отличной серии Build your own claw and agent harness with Microsoft Agent Framework. Их объяснение простое: «коготь» — это CLI-агент, построенный на основе каркаса. Вы приносите модель, инструкции и доменные инструменты. Каркас предоставляет агентовую механику вокруг них.
В .NET ключевая строка такова:
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions{ ChatOptions = new ChatOptions{ Instructions = "You are a personal finance education assistant.", Tools = [StockTools.GetStockPrice]}});Этот вызов даёт агенту полный пайплайн со следующими возможностями:
- Автоматический вызов функций
- Сохранение истории после вызовов модели
- Планирование с поставщиками todo и agent-mode
- Уплотнение контекста
- Файловая память
- Веб-поиск, когда служба модели его поддерживает
- Одобрение инструментов
- Навыки
- Инструментирование OpenTelemetry
Каждая возможность настраивается. Вы можете заменить её, отключить или добавить своего поставщика.
В этом преимущество начала с каркаса: вы тратите своё время на то, что делает агента полезным, вместо того чтобы заново строить один и тот же цикл оркестрации для каждого проекта.
Агент, который мы строим
За четыре сессии мы строим одного персонального финансового образовательного ассистента.
Почему финансы? Потому что они дают нам реалистичные границы для обсуждения:
- Поиск цены акции — это вызов инструмента только для чтения.
- Чтение портфеля означает доступ к пользовательским данным.
- Написание отчёта изменяет файл.
- Размещение смоделированной сделки — это побочный эффект и требует одобрения.
- Запоминание профиля риска требует постоянной, ограниченной пользователем памяти.
- Вычисление стоимости портфеля лучше выполняется кодом, чем арифметикой модели.
- Запуск команд оболочки требует ограничений и политики.
- Производственному финансовому агенту нужны трассировки, управление и оценки.
Это обучающий сценарий
Все цены и транзакции в примерах являются макетными и иллюстративными. Это не финансовая консультация. Это полезный сценарий для обучения тому, как агентные системы ведут себя, когда инструменты имеют разные уровни риска.
Полный код находится в репозитории примеров MafClaw.
Сессия 1: превращение модели в агента
В Meet Your Claw: A Harness in Three Lines of C# мы начали с самого маленького полезного агента.
Сначала создайте IChatClient, поддерживаемый моделью в Microsoft Foundry:
IChatClient chatClient =new AIProjectClient(new Uri(endpoint), new AzureCliCredential()).GetProjectOpenAIClient().GetResponsesClient().AsIChatClient(model);Затем оберните его каркасом и дайте ему один пользовательский инструмент:
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions{ ChatOptions = new ChatOptions{ Instructions = """
You are a personal finance education assistant. Use get_stock_price for stock prices. Use hosted web search for recent market news and cite sources. Use the todo list to track multi-step work.""", Tools = [StockTools.GetStockPrice]}});Пользовательский инструмент — это обычный C#. Agent Framework генерирует его схему из сигнатуры функции и описаний:
[Description("Gets the illustrative stock price for a ticker symbol.")]public static string GetStockPriceBySymbol([Description("Stock ticker symbol, e.g. MSFT")] string symbol){var upper = symbol.Trim().ToUpperInvariant();return upper switch{"MSFT" => "MSFT: 512.34 USD (mock)","NVDA" => "NVDA: 184.72 USD (mock)","AMZN" => "AMZN: 241.18 USD (mock)", _ => $"{upper}: not available"};}public static AIFunction GetStockPrice { get; } = AIFunctionFactory.Create( GetStockPriceBySymbol,"get_stock_price");Теперь разница между чат-приложением и агентом становится видимой.
Спросите:
What is the price of MSFT?Модель выбирает инструмент, каркас вызывает его, результат возвращается модели, и агент производит финальный ответ.
Спросите что-то большее:
Review my watchlist and suggest what I should research next.Каркас может создать план и поддерживать список todo, пока он работает. Мы не написали пользовательский движок планирования для демонстрации. Мы настроили поведение, которое делает этот финансовый агент нашим, и каркас предоставил время выполнения планирования.
Эта первая сессия уже доступна:
Сессия 2: безопасная работа с пользовательскими данными
Агент становится гораздо более полезным, когда он может работать с вашими данными.
Это также становится гораздо более опасным.
В Working With Your Data, Safely: Files, Approvals and Memory мы дали финансовому ассистенту доступ к портфелю CSV, но только внутри одобренной рабочей директории:
var workingDirectory = Path.Combine(AppContext.BaseDirectory, "working");AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions{ FileAccessStore =new FileSystemAgentFileStore(workingDirectory), ChatOptions = new ChatOptions{ Instructions = """
The user's portfolio is in portfolio.csv. Read it before answering portfolio questions. Write generated reports under the approved working folder.""",}});Модель не получает произвольного доступа к файловой системе. Приложение предоставляет файловое хранилище, укоренённое в одной папке, и каркас предоставляет файловые инструменты против этой границы.
Это означает, что happy path работает:
What is in my portfolio?И небезопасный путь заблокирован:
Read C:\some-other-folder\outside-portfolio.csvВторая граница — это человеческое одобрение.
Смоделированная сделка обёрнута в ApprovalRequiredAIFunction:
public static AIFunction RequestSimulatedTrade { get; } =new ApprovalRequiredAIFunction( AIFunctionFactory.Create( RequestSimulatedTradeOrder,"request_simulated_trade"));Модель может запросить действие, но не может выполнить его напрямую. Каркас сначала выдаёт запрос на одобрение. Хост-приложение может показать точно, какой инструмент и какие аргументы требуют одобрения, а затем вернуть человеческое решение той же сессии агента.
Мы также настроили путь с низким трением:
ToolApprovalAgentOptions = new ToolApprovalAgentOptions{ AutoApprovalRules =[FileAccessProvider.ReadOnlyToolsAutoApprovalRule],},Операции с файлами только для чтения могут выполняться автоматически. Записи, разрушительные операции и смоделированная сделка всё ещё пересекают границу одобрения.
Это различие важно. Если каждое безвредное чтение прерывает пользователя, одобрение становится шумом. Цель не в том, чтобы показывать больше диалогов подтверждения. Цель в том, чтобы сделать последствия видимыми.
Вопрос из аудитории стал новым примером
Во время живых вопросов и ответов кто-то спросил:
«А что, если пользователь не отвечает на запрос на одобрение?»
Отличный вопрос.
Молчание не является согласием
Поток одобрения, который ждёт вечно, не завершён. Поэтому после сессии я построил новый пример с ограниченной политикой одобрения: пятисекундный дедлайн на каждую попытку, максимум пять попыток, повторные попытки для отсутствующего или недопустимого ввода, немедленное одобрение для y, немедленный отказ для n, автоматический отказ после последней попытки, липкий отказ для остальной части пользовательского промпта и ограничение на повторные раунды одобрения от модели.
Политика начинается с небольшой конфигурации:
const int maxApprovalAttempts = 5;var approvalTimeout = TimeSpan.FromSeconds(5);var approvalPolicy = new TimedApprovalPolicy( maxApprovalAttempts, approvalTimeout);Полную реализацию можно найти в Sample 22: approval retries and timeouts.
Последняя часть Сессии 2 была памятью. Мы сравнили локальную, принадлежащую приложению JSON-память с управляемой Foundry Memory и обсудили, почему утверждение модели «Я сохранил это» не является доказательством того, что что-то было сохранено. Приложению нужен реальный результат хранения, область действия и способ выявления сбоев.
Сессия 2 также уже доступна:
Сессия 3: навыки, оболочка, CodeAct и фоновые агенты
Первые две сессии делают агента полезным и безопасным. Третья делает его более способным.
В Scaling the Claw: Skills, Shell, CodeAct and Background Agents мы охватываем четыре различных способа расширения агента, не превращая его системный промпт в 400-страничное руководство:
- Навыки пакуют доменные знания в обнаруживаемые файлы. Агент видит краткое описание и загружает полные инструкции только тогда, когда запрос их требует, вместо того чтобы запихивать все правила оценки и оценки риска в основной промпт.
- Оболочка доступ позволяет агенту выполнять задачи, которые естественно выражаются как команды, такие как организация файлов или инспекция директории, внутри ограниченной рабочей директории с политикой команд, тайм-аутами выполнения и явным одобрением.
- CodeAct позволяет агенту писать и запускать код в контролируемой среде выполнения, что более надёжно и аудируемо, чем просить модель выполнять арифметические операции прозой.
- Фоновые агенты позволяют главному агенту делегировать независимые исследовательские задачи, такие как параллельное изучение MSFT, NVDA и SPY, отдельным агентам, которые выполняются одновременно и отчитываются.
Ограничение, а не просто одобрение
Оболочка и выполнение кода — это мощные возможности. Ограничение, политика и одобрение улучшают опыт, но они не заменяют изоляцию. Эта граница всё ещё имеет значение.
Мы строим все четыре вживую, с финансовым ассистентом в качестве текущего примера.
Сессия 4: подготовка агента к производственной среде
На этом этапе коготь может планировать, использовать инструменты, работать с файлами, запрашивать одобрение, запоминать факты, загружать навыки, выполнять код и делегировать исследования.
Это тот момент, когда кто-то спрашивает:
«Хорошо, агент готов… теперь, как мне это развернуть?»
Да, мы возвращаемся к вопросу из моего предыдущего поста 😄.
В Production Ready: Observability, Governance and Deployment мы закрываем цикл:
- Наблюдаемость с трассировками OpenTelemetry, вызовами инструментов, вызовами модели и использованием токенов, чтобы вы могли видеть, что агент на самом деле сделал.
- Управление с интеграцией политики Microsoft Purview, так что организационная политика применяется к поведению агентов, а не только людей.
- Оценки для повторяемых проверок качества, чтобы «это казалось правильным в демо» стало измеримым сигналом.
- Развёртывание как Foundry Hosted Agent, разделяя одно определение агента между консольным приложением, размещённой конечной точкой и harness-ом оценки, каждый из которых включает только возможности, подходящие для этого хоста.
Производственное решение, а не ограничение фреймворка
Общий размещённый контейнер не должен наследовать произвольный локальный доступ к файловой системе или оболочке только потому, что эти возможности были полезны во время разработки. Каждая возможность, которую каркас даёт вам локально, имеет подходящий для производства эквивалент, и выбор между ними — это осознанное решение, а не то, что решает фреймворк за вас.
Точный подход к развёртыванию следует за настройкой хостинга контейнера из примера Agent Framework. Мой предыдущий пост в трёх строках C# остаётся полезным введением в модель хостинга, но у этого когтя есть дополнительные возможности и, следовательно, дополнительные производственные решения.
Мы строим наблюдаемость, управление, оценку и историю развёртывания вживую в этой финальной сессии.
Почему начать с каркаса?
Вы можете построить каждую из этих частей самостоятельно.
Вы можете написать цикл инструментов, сериализовать историю после каждого вызова службы, поддерживать план, уплотнять контекст, строить слой памяти, проектировать протокол одобрения, загружать навыки, управлять фоновыми работниками и инструментировать весь пайплайн.
Иногда вам нужен такой уровень контроля.
Но большинство команд хотят тратить своё время на доменное поведение, которое делает агента ценным:
- Какие инструменты у него должны быть?
- К каким данным он может получить доступ?
- Какие действия требуют одобрения?
- Что он должен запомнить?
- Какие навыки он должен загрузить?
- Какие задачи могут выполняться одновременно?
- Какие политики применяются?
- Как мы будем оценивать, работает ли он?
Каркас даёт этим решениям составляемое домой.
Вы всё ещё владеете границами. Вы всё ещё выбираете инструменты. Вы всё ещё решаете, что одобряется, запоминается, выполняется, трассируется и разворачивается.
Вы просто не должны перестраивать агентовое время выполнения, прежде чем ответить на любой из этих вопросов.
Присоединяйтесь к серии
Блог Microsoft Agent Framework содержит полную письменную, .NET и Python версию этого пути:
А в серии мы строим .NET версию вживую, одну возможность за раз, транслируя вживую одновременно на канале .NET YouTube и Microsoft Reactor, четыре последовательных четверга в сентябре, а затем оставаясь доступной по запросу на обеих платформах:
Приносите свои вопросы. Пример тайм-аута одобрения существует, потому что кто-то сделал именно это.
Узнать больше
- Введение в серию: From Model to Agent
- Страница серии Microsoft Reactor
- Канал .NET YouTube
- Сессия 1: Meet Your Claw: A Harness in Three Lines of C#
- Сессия 2: Working With Your Data, Safely: Files, Approvals and Memory
- Сессия 3: Scaling the Claw: Skills, Shell, CodeAct and Background Agents
- Сессия 4: Production Ready: Observability, Governance and Deployment
Счастливого кодинга!
Бруно
## 🎯 Краткое содержание статьи
Эта статья от Бруно Капуано (Cloud Advocate в Microsoft) описывает серию из четырёх живых сессий, посвящённых созданию полноценного AI-агента на C# с использованием Microsoft Agent Framework 【turn0fetch0】.
### Ключевые темы:
1. **Агентный каркас (Agent Harness)**: Концепция окружения, которое превращает языковую модель в полноценного агента, предоставляя цикл вызова инструментов, планирование, память и одобрение действий 【turn0fetch0】.
2. **Практический пример**: Создание финансового образовательного ассистента, который демонстрирует реальные сценарии с разными уровнями риска (от чтения файлов до выполнения сделок) 【turn0fetch0】.
3. **Прогресс от простого к сложному**: Серия начинается с трёх строк кода и постепенно добавляет возможности: инструменты, файлы, память, навыки, оболочку, CodeAct и фоновых агентов 【turn0fetch0】.
4. **Подготовка к производству**: Финальная сессия посвящена наблюдаемости, управлению через Microsoft Purview, оценкам качества и развёртыванию в Microsoft Foundry 【turn0fetch0】.
### Почему это важно:
Статья решает ключевую проблему: "Что должно быть внутри агента до его развёртывания?" Вместо написания собственной оркестрации с нуля, разработчики могут использовать готовый каркас, сосредоточившись на уникальной доменной логике своего агента 【turn0fetch0】.
## 💡 Как использовать этот перевод
1. **Скопируйте** содержимое блока кода выше.
2. **Вставьте** в любой текстовый редактор.
3. **Сохраните** файл с расширением `.md` (например, `maf-claw-series-ru.md`).
4. Для просмотра отрендеренного Markdown откройте файл в браузере или в редакторе с поддержкой Markdown.
> 📌 **Примечание**: В статье сохранены все ссылки на оригинальные ресурсы (репозиторий GitHub, видео на YouTube, блоги). Для удобства они кликабельны. Код в примерах оставлен на английском, как принято в технической документации, но ключевые комментарии переведены.
