Создайте размещённые агенты с помощью Microsoft Foundry Toolkit для Visual Studio Code

Используйте Microsoft Foundry Toolkit для Visual Studio Code, чтобы создать рабочий процесс на основе кода из примера Microsoft Agent Framework. Запустите его локально с помощью Agent Inspector, а затем разверните его исходный код в Foundry Agent Service в качестве размещённого агента. Вы поддерживаете код и его зависимости. Foundry управляет инфраструктурой размещения и масштабированием.

Хостинговые рабочие процессы координируют агентов в коде. Они отличаются от выводимого из эксплуатации сервиса Foundry для декларативных рабочих процессов. Сведения о других маршрутах создания см. в разделе "Создание агента".

Prerequisites

  • Установите Microsoft Foundry Toolkit для Visual Studio Code.

  • Выберите проект Foundry с развернутой моделью. Используйте поддерживаемый регион размещенного агента.

  • Разрешение на использование модели и развертывание размещенных агентов. Для развертывания исходного кода роль Foundry Project Manager на уровне проекта включает операции агента и разрешения на назначение ролей. См. права доступа для размещённого агента.

    Это важно

    Роли RBAC в Foundry были недавно переименованы. Foundry User, Foundry Owner, Foundry Account Owner и Foundry Project Manager ранее назывались пользователь Azure AI, владелец Azure AI, владелец учетной записи Azure AI и руководитель проекта Azure AI. Пока новое название внедряется, вы всё ещё можете видеть прежние названия в некоторых местах. Идентификаторы ролей и основные разрешения при переименовании не меняются.

  • Azure CLI для действий локальной проверки подлинности в этой статье.

  • Для развертывания контейнеров настройка Реестр контейнеров Azure требует доступа к реестру и образу. Эти требования к реестру не применяются к развертыванию исходного кода.

  • Python 3.13 для настроенной среды выполнения примера.
  • Расширение Python для Visual Studio Code.

Основной путь развертывания использует код с режимом удаленного пакета и не требует локальной сборки Docker. Локальное выполнение по-прежнему отправляет запросы модели в Foundry и может взимать плату. Ознакомьтесь с ограничениями служб и сведениями о доступности и с заметками о выпуске Toolkit для используемых вами функций.

Создание рабочей схемы для хостинг-агента

Выберите пример Agent Framework, использующий протокол Responses. Сначала вам не нужно создавать отдельный агент запроса. Чтобы сравнить примеры, построитель агентов и код с помощью Copilot, см. статью "Выбор маршрута создания".

Используйте мультиагентный рабочий процесс (Agent Framework), который связывает в цепочку автора, рецензента и форматировщик. Окончательный ответ поступает из модуля форматирования. Просмотрите пример рабочего процесса Python для полной реализации и ее руководства по модели.

Используйте рабочий процесс перевода, который объединяет три агента перевода: английский на французский, французский на испанский и испанский на английский. Просмотрите пример рабочего процесса C# для полной реализации.

  1. В представлении Foundry Toolkit выберите Инструменты разработчика>>Создать агента.

  2. В разделе "Код агента из примеров" выберите "Обзор всех примеров".

  3. В разделе «Создание размещённого агента из примера» отфильтруйте по языку, фреймворку = фреймворку агента и типу протокола = ответов. Найдите workflow.

    На следующем снимке экрана показана галерея, в которой в качестве примера выбран Basic Hosted Agent. В этом руководстве вместо этого выберите образец рабочего процесса для вашего языка.

    Снимок экрана галереи примеров размещённого агента с выбранным вариантом Basic Hosted Agent, примерами рабочих процессов и фильтрами по языку, фреймворку и протоколу.

  4. Выберите пример рабочего процесса для языка.

  5. Нажмите кнопку Далее.

  6. На странице Create выберите Папка рабочей области. Если папка уже содержит файлы, введите имя папки для новой дочерней папки.

  7. Если появится Настройка среды, выберите Настроить с помощью Microsoft Foundry, а затем выберите свою подписку и проект. Если проект по умолчанию уже выбран, форма использует этот проект.

  8. Выберите существующее совместимое развертывание модели.

    На следующем снимке экрана показаны примеры параметров проекта со скрытыми локальными путями. Используйте собственную конечную точку и развертывание модели, которые требуются для вашего примера.

    Снимок экрана вкладки «Создание» с папкой рабочей области, именем папки, развертыванием модели и элементами управления для создания, со скрытыми локальными путями.

  9. Просмотрите место назначения и нажмите кнопку "Создать".

  10. Откройте созданный проект в Visual Studio Code и прочитайте егоREADME.md.

Плитки Agent Framework, Copilot SDK и LangGraph на странице Create Agent открывают вкладку Create, где выбран стартовый шаблон hello-world. Используйте обзор всех примеров , чтобы выбрать рабочий процесс, а не один из этих начальных. Вы также можете открыть галерею в разделе My Resources>Agents>Hosted Agent>.

Названия и содержимое примеров могут отличаться в зависимости от каталога. Некоторые версии помечают эти примеры рабочих процессов. Используйте ссылку GitHub примера, чтобы убедиться, что выбран предполагаемый рабочий процесс.

Пропустить пока позволяет сгенерировать код без завершения настройки модели. Если выбрать его, настройте необходимые значения проекта и модели перед запуском примера. Развертывание и использование новой модели, когда она предлагается, подготавливает развертывание модели, а не размещенный агент. Создание локальных файлов проекта не развертывает агент.

Настройка локального проекта

Оставьте папку, содержащую azure.yaml, открытой в качестве корневой папки рабочей области. Проверьте в этом файле путь службы hosted-agent project, чтобы найти каталог её исходников.

Артефакт Purpose
azure.yaml Объявляет службу размещенного агента, исходный каталог, среду выполнения, протоколы и параметры развертывания.
main.py или Program.cs в исходном каталоге Реализует рабочий процесс и запускает сервер ответов.
requirements.txt или файл .csproj Объявляет зависимости для выбранного языка.
.env в исходном каталоге Содержит локальные значения проекта и модели. Инструментарий создает его из .env.example, если образец содержит этот файл.
.vscode/launch.json и .vscode/tasks.json. Настройте локальный сервер, подключение отладчика и Agent Inspector.

Примеры макетов могут изменяться. Используйте сгенерированные README.md и azure.yaml вместо того, чтобы считать, что файл кода и файл окружения находятся в корневом каталоге рабочей области.

Установка зависимостей

Используйте файлы зависимостей созданного примера. Поддерживайте соответствие выбранного интерпретатора или SDK конфигурации среды выполнения.

  1. Запустите Python: создайте среду из палитры команд, чтобы создать виртуальную среду или Python: выберите интерпретатор, чтобы выбрать существующую среду Python 3.13. Сведения о настройке и выборе среды см. в статье Среды Python в Visual Studio Code.

  2. Откройте терминал, в котором активирована эта среда. Перейдите в исходный каталог, содержащий main.py и requirements.txt.

  3. Установите пакеты этого примера:

    python -m pip install -r requirements.txt

    Требования включают debugpy, который используется в созданной конфигурации F5. Справка: зависимости рабочего процесса Python.

  1. Запустите C#: проверьте требования к рабочей области из палитры команд.

  2. В терминале перейдите в исходный каталог, содержащий .csproj файл, и восстановите его пакеты:

    dotnet restore

    Справочник: dotnet restore.

Сведения об элементах управления и настройке отладчика см. Отладка C# в Visual Studio Code.

Настройка проекта и модели

Просмотрите .env файл в исходном каталоге. Если он не существует, создайте его со значениями, необходимыми для примера.

Variable Ценность
FOUNDRY_PROJECT_ENDPOINT Конечная точка проекта в форме https://<resource-name>.services.ai.azure.com/api/projects/<project-name>.
AZURE_AI_MODEL_DEPLOYMENT_NAME Имя развертывания модели в этом проекте, а не просто имя модели в каталоге.

Оба примера рабочего процесса загружают .env во время запуска. Конечная точка проекта не является конечной точкой учетной записи Azure OpenAI. Храните файл вне системы контроля версий и не храните учетные данные в коде приложения.

Проверка подлинности локально

В примерах используется DefaultAzureCredential. При использовании учетных данных Azure CLI войдите с помощью учетной записи, имеющей доступ к модели проекта:

az login

Справочник. Вход с помощью Azure CLI.

При входе в Toolkit выбирается проект для операций расширения. Процессу локального агента также требуются поддерживаемые учетные данные. Сведения о других вариантах см. в статьях DefaultAzureCredential для Python и цепочки учетных данных для .NET.

Локальное выполнение размещенного рабочего процесса

Используйте созданную конфигурацию отладки, чтобы запустить HTTP-сервер и открыть инспектор агента. Само по себе открытие Agent Inspector не запускает сервер.

Используйте этот тестовый запрос: Create a slogan for a new electric SUV that is affordable and fun to drive. Рабочий процесс возвращает отформатированный слоган после завершения этапов написания, проверки и форматирования.

Используйте этот тестовый запрос: The quick brown fox jumps over the lazy dog. рабочий процесс запускает свою цепочку перевода и возвращает ответ.

  1. Вернитесь в созданную рабочую область проекта.
  2. Установите точку останова в коде рабочего процесса, если требуется проверить выполнение.
  3. Нажмите клавишу F5. Если появится запрос, выберите HTTP-сервер локального агента отладки.
  4. Дождитесь запуска сервера и открытия Agent Inspector.
  5. Отправьте тестовый запрос для вашего образца.
  6. Проверьте ответ и повторите запрос. Если вы задали точку останова, проверьте значения и продолжите выполнение.

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

На снимке экрана показан локальный агент с поддержкой инструмента, а не пример рабочего процесса. Инспектор агента отображает ответ и вызовы инструментов в виде каскадной диаграммы задержек и временной шкалы запуска. Доступные сведения о проверке зависят от запущенного агента и используемых им средств инструментирования.

Снимок экрана: инспектор агента, подключенный к localhost через порт 8088, с протоколом

Если вы используете GitHub Copilot, то можете выполнить /validate-microsoft-foundry-hosted-agent в Copilot Chat, чтобы проверить проект на соответствие рекомендациям Foundry. Эта команда чата открывает отчет; Это не команда терминала или замена для запуска рабочего процесса.

Созданные задачи используют порт 8088 для сервера агента. При отладке Python также используется порт 5679. Если при запуске сообщается о конфликте портов, остановите конфликтующий процесс, если он принадлежит вам, или соответствующим образом измените сгенерированную конфигурацию задачи.

Запуск без отладчика

Чтобы запустить вручную, откройте терминал в исходном каталоге примера со своими зависимостями, значениями среды и доступными учетными данными Azure.

python main.py

Справка: точка входа рабочего процесса Python.

Задайте HTTP-адрес для локального сервера, а затем запустите его:

$env:ASPNETCORE_URLS = "http://localhost:8088"
dotnet run

См. URL-адреса сервера ASP.NET Core и dotnet run.

Затем запустите набор средств Foundry: откройте инспектор агента из палитры команд и подключитесь к локальному серверу через порт 8088. Запуск примера с помощью python или dotnet run запускает локальный процесс, а не контейнер.

Визуализация выполнения процесса облачного агента

Используйте Agent Inspector, чтобы проверять события, ответы и вызовы инструментов, которые генерирует запущенный агент. Когда среда выполнения выдает события рабочего процесса, используйте визуализацию рабочего процесса для проверки последовательности шагов.

Доступные сведения зависят от того, какими средствами инструментирования оснащён образец. Следуйте инструкциям по настройке телеметрии в примере для требований, зависящих от среды выполнения.

В этих шагах используется протокол ответов. Другие примеры требуют клиентов, соответствующих их протоколу: представление HTTP Invocations не является клиентом WebSocket, а примеры Python Activity используют Microsoft 365 Agents Playground. Следуйте инструкциям локального тестирования выбранного примера. Изменение имени протокола в конфигурации не добавляет этот протокол на сервер. См. раздел Выбор протокола размещённого агента.

Разверните размещенного агента

После того как локальный рабочий процесс работает должным образом, разверните его из рабочей области проекта. Python и C# совместно используют процедуру развертывания. Начните с режима пакета Code и Remote, чтобы загрузить исходный код и позволить Foundry восстановить зависимости.

Подготовка конфигурации развертывания

Проверьте и сохраните службу размещённого агента в azure.yaml. Сохраните конфигурацию протокола в примере и укажите там развертывание модели и другие требуемые параметры среды выполнения.

При развертывании объявленные значения переменных среды определяются из файла .env в исходном каталоге или из переменных окружения процесса. Он не пересылает каждую локальную запись .env. Платформа предоставляет зарезервированные значения среды выполнения, например FOUNDRY_PROJECT_ENDPOINT, не переобъявляйте их в качестве параметров развертывания. См. переменные среды, задаваемые платформой.

Просмотрите правила игнорирования исходного каталога перед упаковкой. Сохраняйте .envучетные данные, виртуальные среды и кэши из пакета. Для ZIP-развертывания файл source-root .agentignore заменяет правила в .gitignore и .dockerignore, поэтому сохраните необходимые исключения, если добавляете этот файл.

Это важно

Не добавляйте секретные данные в коммит и пакет. Локальный вход в систему не передает разрешения вашего пользователя развернутому агенту. Настройте доступ к исполняемой идентичности агента и поддерживаемым подключениям. См. права доступа для размещённого агента.

Развертывание исходного кода в режиме удаленного пакета

Используйте созданный корневой каталог рабочей области, чтобы набор средств смог прочитать конфигурацию службы и найти его исходный каталог.

  1. Остановите локальный сеанс отладки.

  2. Выберите Средства разработчика>Сборка>. Вы также можете запустить Foundry Toolkit: Deploy Hosted Agent в палитре команд.

    Снимок экрана команды

  3. Если появится настройка проекта Foundry, выберите подписку и проект, а затем выберите Далее. В противном случае убедитесь, что проект по умолчанию является нужным местом назначения.

  4. В основах выберите "Код в качестве метода развертывания " и "Удаленный " в режиме пакета.

  5. Выберите Новый агент и введите Имя размещенного агента. Чтобы обновить развернутый агент, выберите Существующий агент и вместо этого укажите этого агента.

    Снимок экрана: основные сведения о развертывании кода, режиме удаленного пакета и выбранном новом агенте с скрытым именем агента.

  6. Нажмите кнопку Далее.

  7. На этапе Проверка и развертывание сверьте Язык, Версию среды выполнения, Точку входа и Процессор и память с образцом. Убедитесь, что исходный каталог соответствует пути службы project .

    На следующем снимке экрана показан пример с Python 3.14 со скрытой точкой входа, а не настройки для этих образцов рабочих процессов. Для Python используйте Python 3.13 с python3 main.py. Для C# используйте .NET 10 и обнаруженную точку входа для созданного проекта.

    Снимок экрана раздела «Проверка и развертывание» с примером Python 3.14, скрытой точкой входа, параметрами процессора и памяти, а также элементами управления развертыванием.

  8. Выберите «Развернуть». Следуйте инструкциям в уведомлениях и выходных данных.

  9. Продолжайте тестировать развернутый рабочий процесс.

Сопоставляйте среду выполнения с примером конфигурации и локальной средой. Не выбирайте другую среду выполнения только потому, что она выбрана в мастере по умолчанию.

Инструментарий сохраняет параметры развертывания при отправке формы. Эти локальные параметры не доказывают успешность облачного развертывания. Обновление существующего агента создает новую версию, а не изменяет предыдущую версию.

Выбор другого режима пакета ZIP

Набор средств предлагает следующие варианты упаковки исходного кода:

Режим пакета Что происходит Что нужно подготовить
Удаленно Исходный код пакетов Toolkit. Foundry восстанавливает требования Python или проект .NET во время подготовки. Исходный код, объявления зависимостей и совместимая точка входа.
Упаковано Набор средств подготавливает исходный код и локально выполняет команду Package перед созданием ZIP-архива. Foundry запускает подготовленный пакет. Совместимые зависимости Linux и локальные средства, необходимые команде. Команда Python по умолчанию устанавливает совместимые зависимости в packages/; команда .NET создает выходные данные для публикации.

Для выбора доступны следующие ZIP-среды выполнения: Python 3.13, Python 3.14 и .NET 10. Подберите среду выполнения в соответствии с вашим кодом и зависимостями. Сведения о макетах, ограничениях и требованиях к службе см. в разделе "Развертывание из исходного кода". Сведения о политике поддержки среды выполнения см. в разделе "Поддерживаемые среды выполнения размещенного агента".

Разверните образ контейнера

Выберите Контейнер на вкладке Основные, если вам нужен собственный образ среды выполнения или у вас уже есть совместимый образ.

Выбор реестра Поведение инструментария
ACR по умолчанию Создает или повторно использует реестр для выбранного проекта, а затем создает и отправляет образ через Реестр контейнеров Azure (ACR).
Настраиваемый ACR Использует существующий реестр, который вы выбираете, а затем создает и отправляет образ через ACR.
Настраиваемый образ ACR Использует предварительно созданную ссылку на образ ACR без создания или отправки источника.

Для параметров сборки просмотрите файл Dockerfile и контекст сборки перед развертыванием. Если вы создаете Dockerfile в мастере, просмотрите файл и выберите "Продолжить" и "Развернуть". Эти параметры используют удаленные сборки ACR, а не локальные сборки Docker.

Настраиваемые параметры реестра используют реестр в выбранной подписке. Для сценария сборки с использованием пользовательского реестра требуется доступ к публичной сети; для сценария с предварительно собранным образом действуют отдельные требования к приватной сети. Выбор образа не настраивает сетевое подключение.

Ознакомьтесь с требованиями к контейнерам и рекомендациями по частной сети перед использованием пользовательского реестра. Эти развертывания ориентированы на Foundry Agent Service, а не на выведенный из эксплуатации путь размещенного агента Контейнеры приложений Azure. Чтобы перенести устаревший агент, следуйте инструкциям Миграция из предварительной версии размещённого агента.

Тестирование развернутого рабочего процесса

Успешный запрос на создание не подтверждает готовность среды выполнения или доступ к ее модели и средствам. Проверьте точную развернутую версию.

  1. В разделе Мои ресурсы>>Размещенный агент выберите имя агента.
  2. Выберите только что развернутую нумерованную версию.
  3. На странице «Сведения» дождитесь, пока состояние развертывания не покажет, что агент запущен. При сбое проверьте выходные данные развертывания перед повтором.
  4. Откройте игровую площадку и отправьте тот же запрос, который вы тестировали локально.
  5. Просмотрите ответ. Если вы добавили средства, отправьте запрос, требующий этих средств, и проверьте вызовы.

Локальные и облачные запуски используют разные учетные данные, среды зависимостей и сетевые пути. Успешный локальный ответ не гарантирует успешного удаленного ответа.

Проверка и обновление развернутого агента

Используйте удаленную площадку для тестирования и проверки развернутого агента. В отличие от локального тестирования с помощью инспектора агента, запросы на этой игровой площадке выполняются с агентом, размещенным в Foundry.

  1. В Foundry Toolkit выберите Средства разработчика>Сборка>Песочница размещенного агента.

    Снимок экрана песочницы размещённого агента в подразделе «Сборка» раздела «Средства разработчика» Foundry Toolkit.

  2. В раскрывающемся списке Размещенный агент выберите развернутый агент и его версию для проверки. Откройте Playground, чтобы отправить запрос и просмотреть ответ и сведения о сеансе.

    На следующем снимке экрана показан иллюстрированный ответ развернутого агента, а не ожидаемый результат любого примера рабочего процесса. Идентификаторы агента и сеанса скрыты.

    Снимок экрана: игровая площадка удаленного размещенного агента с ответом, сведениями о сеансе и вкладками проверки с скрытыми идентификаторами агента и сеанса.

Используйте эти элементы управления для проверки и обновления агента. Доступные вкладки зависят от протокола и подключенных служб.

Task Действие
Просмотр сведений о развертывании Откройте сведения о состоянии, конфигурации и конечную точку, доступную для копирования.
Тестирование версии Выберите пронумерованную версию для запросов к песочнице. Автоматический использует версию, выбранную для конечной точки службы, и это не обязательно самая новая версия. Модуль выбора не изменяет маршрутизацию для других клиентов.
Просмотр журналов среды выполнения Откройте сеансы, выберите сеанс и просмотрите его журналы. Для журналов времени выполнения требуется сеанс; вывод сборки выполняется отдельно. Остановка потоковой передачи журнала или отмена запроса не останавливает размещённый агент.
Получить развернутый код Используйте ресурс загрузки кода для развертывания ZIP-файла. Развертывание образа показывает ссылку на образ вместо проекта с исходным кодом, доступного для скачивания.
Поведение при обновлении Измените и проверьте локальный код, а затем повторите процедуру развертывания с помощью существующего агента , чтобы создать новую версию.

Используйте Traces и Evaluation, если они доступны, для анализа и измерения качества, выходящих за рамки одного успешного ответа. Следуйте необходимым условиям для трассировки размещаемого агента и оценки размещаемого агента.

Развертывание предоставляет агенту конечную точку для программного использования. Для доступа к API не требуется отдельный шаг публикации. Публикация в Teams или Microsoft 365 является отдельной задачей. См. текущую конечную точку агента и модель публикации.

Troubleshooting

Используйте сообщаемую ошибку и образец конфигурации, чтобы определить сбой.

Симптом Действие
Локальный запуск завершается ошибкой, так как пакет отсутствует. Подтвердите выбранный интерпретатор или пакет SDK, а затем установите зависимости из исходного каталога примера.
Не удается найти конечную точку проекта или модель. Проверьте FOUNDRY_PROJECT_ENDPOINT и AZURE_AI_MODEL_DEPLOYMENT_NAME. Не заменяйте конечную точку учетной записи или имя каталога моделей.
Проверка подлинности или авторизация не выполняется. Проверьте локальные учетные данные и доступ к проекту. Просмотрите разрешения размещенного агента для требований к развертыванию и удостоверению среды выполнения.
Agent Inspector не удается подключиться. Убедитесь, что сервер запущен и порт 8088 доступен. Само по себе открытие инспектора не запускает сервер.
Развертывание завершается сбоем. Просмотрите ошибку развертывания и выходные данные сборки. Для кода проверьте среду выполнения, точку входа, режим пакета и игнорируйте правила. Для контейнера проверьте права доступа к образу и реестру.
Локальный ответ работает, но развернутая версия завершается ошибкой. Сравните развернутую среду и разрешения удостоверения с локальной конфигурацией. Повторно протестируйте именно развернутую версию.

Очистите ресурсы

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

При удалении агента удаляются его версии и завершаются активные сеансы. Он не удаляет каждый связанный ресурс Azure.

Удалите только облачные ресурсы, созданные для этого упражнения, которые не используют другие приложения. Не удаляйте проект Foundry с общим доступом, развертывание модели или реестр контейнеров.

Связанные материалы

Используйте следующие руководства для расширения рабочего процесса:

  • Last updated on