Краткое руководство: Развертывание первого размещенного агента

• Azure Developer CLI версия 1.24.0 или более поздняя

• Visual Studio Code
• Набор средств Microsoft Foundry для расширения Visual Studio Code

Требуемое разрешение

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

Если вы используете azd или расширение VS Code, средство обрабатывает большинство назначений RBAC автоматически, включая:

Убедитесь, что управляемое удостоверение Foundry Project имеет роль на извлечение ACR в используемом вами Реестр контейнеров Azure. Если у вас есть доступ "Владелец" или "Администратор доступа пользователей" и вы предпочитаете, то инструменты azd/vscode также могут сделать это назначение за вас. Пользователь Azure AI для удостоверения агента, созданного платформой (использования модели выполнения и доступа к инструментам)

Шаг 1. Настройка примера проекта

Установите расширение агента командной строки разработчика Azure и инициализируйте новый проект для размещенного агента.

1. Установите расширение ai agent для интерфейса командной строки разработчика Azure:

   azd ext install azure.ai.agents
   

   Чтобы проверить установку расширения, выполните следующую команду:

   azd ext list
   

2. Инициализация нового проекта агента на хостинге в пустом каталоге:

   azd ai agent init
   

   Интерактивная последовательность поможет вам настроить следующую конфигурацию:

   • Language — выберите язык программирования, для которого требуется пример кода для C# или Python.
   • Шаблон агента — выберите пример для начала.
   • Model Configuration — выберите, чтобы развернуть новую модель в Foundry или использовать существующую из существующего Project Foundry.
   • подписка Azure — выберите подписку, в которой нужно создать ресурсы Foundry.
   • Расположение — выберите регион для ресурсов.
   • Номер SKU модели — выберите номер SKU, доступный для вашего региона и подписки.
   • Имя развертывания — введите имя развертывания модели.
   • Размер контейнера — выберите выделение ЦП и памяти или примите значения по умолчанию.

   Важно

   Если вы выбрали пример с инструментами и не используете сервер MCP, закомментируйте или удалите следующие строки в agent.yaml файле:

   - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
     value: <CONNECTION_ID_PLACEHOLDER>
   

   Совет

   Если вы работаете в неинтерактивной среде, как, например, конвейере CI/CD или сеансе SSH, используйте флаг --no-prompt вместе с azd ai agent init. Кроме того, необходимо указать все необходимые значения как флаги командной строки, а не отвечать на интерактивные запросы.

3. Подготовьте необходимые ресурсы Azure:

   Примечание

   Вам нужен Contributor доступ к подписке Azure для подготовки ресурсов.

   azd provision
   

   Эта команда занимает несколько минут и создает следующие ресурсы:

   Ресурс	Цель	Стоимость
   Группа ресурсов	Упорядочивает все связанные ресурсы в одной области	Без затрат
   Развертывание модели	Модель, используемая агентом	См . цены на Foundry
   Проект Foundry	Хостинг агента и предоставление ИИ-решений	На основе потребления; см. цены на Foundry
   Реестр контейнеров Azure	Сохраняет образы контейнеров агента	Базовый уровень: см. цены на ACR
   Рабочая область Log Analytics	Управление всеми данными журнала в одном месте	Нет прямых затрат. См. Log Analytics затраты
   Application Insights	Отслеживает производительность и журналы агента	Оплата по мере использования; см. цены Azure Monitor
   Управляемая идентичность	Проверка подлинности агента в службах Azure	Без затрат

   Совет

   Выполните azd down , когда завершите работу с этим кратким руководством, чтобы удалить ресурсы и прекратить взимать плату.

Шаг 2. Тестирование агента локально

Перед развертыванием убедитесь, что агент работает локально.

1. Запустите агент локально:

   azd ai agent run
   

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

   Примечание

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

   Если агент не запускается, проверьте следующие распространенные неполадки:

   Ошибка	Решение
   AuthenticationError или DefaultAzureCredential сбой	Запустите azd auth logout, а затем azd auth login, чтобы обновить сеанс.
   ResourceNotFound	Убедитесь, что URL-адреса конечных точек соответствуют значениям на портале Foundry.
   DeploymentNotFound	Проверьте имя развертывания вБилд>Развертываниях.
   Connection refused	Убедитесь, что другой процесс не использует порт 8088.

2. В отдельном терминале отправьте тестовое сообщение локальному агенту.

   Для агентов, использующих API ответов, можно отправить строку в качестве полезной нагрузки.

   azd ai agent invoke --local "What is Microsoft Foundry?"
   

   Для агентов, использующих API вызовов, проверьте ожидаемые полезные данные в README.md. Примеры обычно требуют JSON-пейлоуд, но проверьте, что содержится в README.md для этого конкретного примера.

   Вы увидите ответ от агента.

Шаг 3. Развертывание в агентской службе Foundry

Так как вы уже подготовили инфраструктуру на шаге 1, разверните код агента в Azure:

azd deploy

Контейнер агента создается удаленно, поэтому Docker Desktop не требуется на компьютере.

По завершении выходные данные показывают ссылку на игровую площадку агента и конечную точку для вызова агента программным способом:

Deploying services (azd deploy)

  (✓) Done: Deploying service af-agent-with-foundry-tools
  - Agent playground (portal): https://ai.azure.com/nextgen/.../build/agents/af-agent-with-foundry-tools/build?version=1 
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/af-agent-with-foundry-tools/versions/1

Шаг 1. Создание проекта Foundry

Используйте расширение Microsoft Foundry Toolkit в VS Code для создания нового ресурса Microsoft Foundry Project.

1. Откройте палитру команд (Ctrl+SHIFT+P) и выберите Microsoft Foundry: Create Project.

2. Выберите подписку Azure.

3. Создайте новую группу ресурсов или выберите существующую.

4. Введите имя ресурса Foundry Project.

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

Шаг 2. Развертывание модели

Используйте расширение Microsoft Foundry Toolkit в VS Code для развертывания модели в Foundry.

1. Откройте палитру команд (Ctrl+SHIFT+P) и выберите Microsoft Foundry: Open Model Catalog.

2. Перейдите к каталогу моделей или найдите gpt-4.1 и нажмите кнопку "Развернуть ".

3. На странице развертывания модели нажмите кнопку Deploy to Microsoft Foundry.

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

Шаг 3. Создание проекта размещенного агента

Используйте расширение Microsoft Foundry Toolkit в VS Code, чтобы структурировать новый проект размещенного агента.

1. Откройте палитру команд (Ctrl+SHIFT+P) и выберите Microsoft Foundry: Create new Hosted Agent.

2. Выберите платформу, которую вы хотите использовать.

3. Выберите язык программирования, Python или C#.

4. Выберите API ответов или API вызова.

5. Выберите пример кода, который вы хотите использовать.

6. Выберите папку, в которой будут сохранены файлы проекта.

7. Введите имя размещенного агента.

Новое окно VS Code запустится с новой папкой проекта агента в качестве активной рабочей области.

Шаг 4. Установка зависимостей

Рекомендуется использовать виртуальную среду для изоляции зависимостей проекта:

macOS/Linux:

python -m venv .venv
source .venv/bin/activate

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

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

Установите необходимые зависимости Python с помощью pip:

pip install -r requirements.txt

Список обязательных пакетов см. в requirement.txt.

Шаг 5. Тестирование агента локально

Запустите и проверьте агент перед развертыванием.

Вариант 1. Нажмите клавишу F5 (рекомендуется)

Нажмите клавишу F5 в VS Code, чтобы начать отладку. Кроме того, можно использовать меню отладки VS Code:

1. Откройте представление "Запуск и отладка " (CTRL+SHIFT+D/ CMD+SHIFT+D)
2. Выберите "Отладка локального HTTP-сервера рабочего процесса" в раскрывающемся списке
3. Нажмите зеленую кнопку "Начать отладку " (или нажмите клавишу F5)

Это приведет к следующему:

1. Запуск HTTP-сервера с включенной отладкой
2. Откройте инспектор агента набора инструментов Foundry для интерактивного тестирования
3. Разрешить устанавливать точки останова и проверять рабочий процесс

Вариант 2. Запуск в терминале

Запуск от имени HTTP-сервера (по умолчанию):

python main.py

Это запустит размещенного агента локально на http://localhost:8088/.

PowerShell (Windows):

$body = @{
   input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under `$200 per night"
    stream = $false
} | ConvertTo-Json

Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"

Bash/curl (Linux/macOS):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
   -d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'

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

Шаг 6. Развертывание в службу агента Foundry

Разверните агент непосредственно из VS Code.

1. Откройте палитру команд (Ctrl+SHIFT+P) и выберите Microsoft Foundry: Deploy Hosted Agent.

2. Выберите "ACR по умолчанию"

3. Выберите конфигурацию ЦП и памяти для контейнера агента хостинга.

Перейдите в обозреватель наборов средств для Microsoft Foundry, выбрав значок слева. Агент отображается на боковой панели древовидного представления Размещенные агенты (предварительный просмотр) после завершения развертывания.

Проверка состояния агента

Проверьте статус агента, чтобы убедиться, что он работает.

1. Выберите размещенного агента из дерева "Размещенные агенты (Предварительная версия)".

2. Выберите агента, которого вы только что развернули

На странице сведений отображается состояние в разделе "Сведения о контейнере".

Тестирование на детской площадке с помощью VS Code

Microsoft Foundry Toolkit для VS Code включает интегрированную площадку для общения и взаимодействия с вашим агентом.

1. Выберите размещенного агента из дерева "Размещенные агенты (Предварительная версия)".

2. Выберите параметр "Детская площадка" и введите сообщение и отправьте его для тестирования агента.

Проверка состояния агента

Проверьте состояние развернутого агента:

azd ai agent show

Чтобы отобразить выходные данные в формате таблицы:

azd ai agent show --output table

Если у проекта несколько служб агента, укажите имя агента в качестве позиционного аргумента:

azd ai agent show <agent-name>

Тестирование развернутого агента

Отправьте тестовое сообщение в развернутый агент с помощью той же invoke команды, которая использовалась ранее, но без флага --local:

Для агентов, использующих API ответов, можно отправить строку в качестве полезной нагрузки.

azd ai agent invoke <payload>

Вы увидите ответ от агента через несколько секунд.

Просмотр журналов агента

Отслеживайте динамические журналы агента:

# Fetch recent container console logs
azd ai agent monitor

# Fetch the last N lines of console logs
azd ai agent monitor --tail 20

# Fetch system event logs (container start and stop events)
azd ai agent monitor --type system

# Stream session logs in real time
azd ai agent monitor --session <session-id> --follow

Если у проекта несколько служб агента, укажите имя агента в качестве позиционного аргумента:

azd ai agent monitor <agent-name> --follow

Чтобы просмотреть, что будет удалено, выполните down команду:

azd down

По завершении azd отобразит все ресурсы, которые будут удалены, и запросит подтвердить действие. Выберите yes , чтобы продолжить или no отменить.

Процесс очистки занимает около 2–5 минут.

Чтобы удалить ресурсы, откройте портал Azure, перейдите к группе ресурсов и удалите ее вместе со всеми содержащимися ресурсами.

Просмотреть журналы контейнеров вашего агента

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

1. Выберите размещенного агента из дерева "Размещенные агенты (Предварительная версия)".

2. Выберите вкладку "Детская площадка" размещенного агента

3. Выберите раздел "Журналы" в сведениях о сеансе.

Просмотр файлов сеанса агента

Вы можете просмотреть все файлы, хранящиеся в домашнем каталоге агента на основе ADC.

1. Выберите вашего размещенного агента в древовидном представлении Hosted Agents (Предварительная версия).

2. Выберите вкладку "Детская площадка" размещенного агента

3. Выберите раздел "Файлы" в сведениях о сеансе.

Вы можете скачать, загрузить и создать папки в текущей директории. Щелкнув на папку, вы войдёте в неё, а щелкая по верхней панели навигации, вы вернётесь в предыдущую папку.