Быстрый старт для Microsoft Foundry Agent Service написан на Python. Он скрывает внутреннюю сложность Azure за настолько плотными шаблонами, что вы можете завершить обучение, даже не зная, какие именно ресурсы были созданы. Если вы разрабатываете на .NET, вы оказываетесь в невыгодном положении: примеры указывают не в ту сторону, названия пакетов меняются без предупреждения, а недавний ребрендинг из Azure AI Foundry в Microsoft Foundry привел к тому, что в результатах поиска конкурируют два набора документации.
Недавно я создал своего первого агента на C#. Сервис работает хорошо, если отбросить лишний шум и отделить основные шаги от путаницы, вызванной превью-версиями. Вот карта, которая была бы мне полезна в первый же день.
Четыре ресурса, которые вам действительно нужны
Для запуска базового Prompt Agent вам не нужны десятки сервисов Azure. Вам нужны ровно четыре вещи, и CLI делает их видимыми так, как это не позволяют делать Python-ноутбуки.
Во-первых, ресурс Foundry с типом AIServices. Он служит базовой инфраструктурой для вызываемых вами моделей. Во-вторых, project внутри этого ресурса. Проект — это область видимости, где хранятся определения ваших агентов, потоки диалогов и настройки развертывания. В-третьих, deployed model (развернутая модель). Без активного развертывания у агента не будет эндпоинта для вызова. В-четвертых, role assignment (назначение роли) для вашей собственной учетной записи, чтобы SDK мог пройти аутентификацию в проекте.
Вот и всё. Никаких кластеров Kubernetes, никаких пользовательских вычислительных мощностей и никакого вручную управляемого кэша Redis для истории диалогов.
Prompt Agents против Hosted Agents
Foundry предлагает два способа запуска агентов. Не выбирайте по умолчанию более сложный вариант.
Prompt Agents — это более простой путь. Вы выбираете модель, пишете системные инструкции, и Foundry запускает агента за вас. Вам не нужно управлять вычислительными мощностями, контейнерами или логикой маршрутизации. Это подходит для внутренних инструментов, ботов службы поддержки и простых ответов на вопросы по документам.
Hosted Agents требуют написания кода приложения, его упаковки в контейнер и интеграции с Foundry. Этот путь стоит выбирать только тогда, когда вам нужна кастомная бизнес-логика, которую Foundry не может выразить через промпты и встроенные инструменты — например, вызов внутреннего API с нестандартной аутентификацией.
Данное руководство сосредоточено на Prompt Agents, так как это самый быстрый способ проверить правильность вашей настройки .NET, прежде чем инвестировать время в Docker-файлы и оркестрацию.
Настройка через командную строку
Использование CLI заставляет вас видеть каждый ресурс, что как раз и скрывается в Python-быстром старте. Создайте группу ресурсов в регионе East US 2. Выбор региона здесь имеет значение. Поддержка инструментов в Foundry внедряется неравномерно, и на данный момент East US 2 обладает самым широким набором возможностей. Если вы выберете регион, в котором отсутствуют инструменты code interpreter или поиска по файлам, ваш вызов создания агента завершится ошибкой с невнятным описанием неподдерживаемых возможностей.
Создайте ресурс Foundry с флагом --allow-project-management. Без этого флага ресурс останется отдельной конечной точкой cognitive services и не примет развертывания в рамках проекта, которые необходимы агентам. Затем создайте проект, разверните модель и назначьте себе роль Foundry User.
Используйте стабильный GUID роли вместо отображаемого имени:
53ca6127-db72-4b80-b1b0-d745d6d5456d
Имена ролей распространяются в Azure Active Directory с разной скоростью в зависимости от тенанта. Одна организация увидит Foundry User в портале уже сегодня, а другая — только через несколько дней. GUID указывает напрямую на определение и не вызовет сбоев во время развертывания. Эта маленькая деталь может сэкономить вам час отладки ошибок «permission denied», которые выглядят как проблемы с политиками, но на самом деле являются проблемами разрешения имен.
Избегайте неправильного NuGet-пакета
Вот где .NET-разработчики часто застревают. В старых фрагментах кода вы встретите ссылки на Azure.AI.Projects.OpenAI. Этот пакет предназначен только для превью-версии, и он пересекается с Azure.AI.Extensions.OpenAI. Оба определяют методы расширения и типы в похожих пространствах имен. Если вы установите их одновременно, сборка прервется с ошибками неоднозначности ссылок, которые