Быстрый старт: Развертывание первого размещенного агента

• Интерфейс командной строки для разработчиков Azure версии 1.24.0 или более поздней

• Visual Studio Code
• Microsoft Foundry Инструментарий для расширения Visual Studio Code

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

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

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

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

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

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

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-promptazd 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 Agent Service

Так как вы уже подготовили инфраструктуру на шаге 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. На странице развертывания модели нажмите кнопку Развернуть для 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 для 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. Выберите агента, размещенного на сервере, из древовидного представления "Размещенные агенты (предварительная версия)".

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

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

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