Создание экземпляров агента

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

В этой статье процесс разбит на три основных шага:

1. Настройка агента на портале разработчика Teams
2. Создание экземпляра агента
3. Тестирование развернутого агента

Если вы столкнулись с трудностями, см. раздел Устранение неполадок.

Предварительные условия

• Схема агента правильно настроена, как описано на шаге Настройка схемы агента.
• Приложение агента правильно опубликовано, как описано в разделе Публикация агента в центре администрирования Microsoft.

1. Настройка агента на портале разработчиков Teams

После публикации настройте схему агента на портале разработчика Teams, чтобы подключить агент к инфраструктуре обмена сообщениями Microsoft 365. Без этой конфигурации ваш агент не будет получать сообщения из Teams, электронной почты или других служб Microsoft 365.

1. Получение ИД схемы

   Откройте a365.generated.config.json в рабочей папке и скопируйте значение agentBlueprintId.

2. Переход на портал разработчика

   Откройте браузер и перейдите на страницу конфигурации:

   https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration
   

   Замените <your-blueprint-id> на значение agentBlueprintId, которое вы скопировали.

   Примечание

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

3. Настройка агента

   На портале разработчика:

   1. Установите для параметра Тип агента значение На основе API.

   2. Установите для параметра URL-адрес для уведомлений конечную точку обмена сообщениями агента. Найдите значение messagingEndpoint в a365.generated.config.json.

   3. Выберите Сохранить.

   

Эта конфигурация необходима, прежде чем вы сможете создавать экземпляры агента в Teams.

Узнайте больше о схемах удостоверений агентов и конфигурации портала разработчика.

2. Создание экземпляра агента

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

Когда вы запрашиваете экземпляр агента, Teams отправляет запрос вашему администратору клиента для утверждения. Администраторы могут просматривать и утверждать запросы на странице Центр администрирования Microsoft — запрошенные агенты.

После того как администратор утвердит ваш запрос, Teams создаст экземпляр агента и сделает его доступным в Teams.

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

После создания экземпляра агента протестируйте его в Microsoft 365, чтобы убедиться, что он правильно работает в рабочей среде.

После развертывания и при включенных уведомлениях агента в пакете SDK Agent 365 ваш агент интегрируется со службами Microsoft 365. Он работает с Teams для чатов, каналов и встреч, с электронной почтой и календарем для отправки, получения и планирования, а также с SharePoint и OneDrive для доступа к документам и обмена файлами. Он также поддерживает функции совместной работы, такие как отображение присутствия в организации, задачи планировщика и комментарии к документам.

Важно

Так же, как и обычные пользователи, пользователи-агенты должны иметь соответствующие лицензии Microsoft 365 для доступа к службам. К распространенным лицензиям относятся Microsoft 365 E5, Teams Enterprise и Microsoft 365 Copilot.

Просмотр развернутого агента в центре администрирования

После публикации агент станет доступен для назначения в центре администрирования Microsoft. Распространение изменений может занять некоторое время.

Перейдите в центр администрирования Microsoft 365 — агенты для выполнения следующих действий:

• Просмотр опубликованного агента
• Управление параметрами агента
• Мониторинг использования агента
• Настройка разрешений

Тестирование агента в Teams

После развертывания, публикации и настройки схемы агента и создания пользователя агента протестируйте его непосредственно в Microsoft Teams:

Начало тестирования

1. Найдите нового пользователя агента в Teams.

   Примечание

   Процесс создания пользователя агента асинхронен. После создания пользователя агента может пройти от нескольких минут до нескольких часов, прежде чем он станет доступен для поиска.

2. Начните новый чат с вашим недавно созданным экземпляром агента.

3. Отправьте тестовые сообщения для проверки функциональности агента.

Пример тестового сообщения

Если вы настроили агент для работы с электронной почтой, отправьте это сообщение для проверки ее работы. Обновите значение электронной почты recipient@contoso.com получателя.

Send an email to <recipient@contoso.com> with subject "Hello from Teams" and message "This is a test message from my agent!"

Агент обрабатывает запрос и отправляет сообщение электронной почты без дополнительного подтверждения.

Проверочный контрольный список

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

✅ Конфигурация портала разработчиков сохранена
✅ Агент появляется в поиске приложений Teams
✅ Вы можете создать экземпляр агента в Teams
✅ Создан экземпляр агента
✅ Пользователь агента отображается в организации
✅ Агент отвечает на сообщения
✅ Агент может выполнять действия
✅ Журналы приложений не показывают ошибок
✅ Наблюдаемость работает в центре администрирования

Если ваш экземпляр агента работает не так, как ожидается, см. раздел Устранение неполадок для получения подробной информации о распространенных проблемах и их решениях.

Проверьте, что конфигурация портала разработчика сохранена

Перейдите по адресу: https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

✅ Тип агента показывает: На основе API✅URL-адрес для уведомлений совпадает с конечной точкой сообщений вашего агента ✅ Отображается сообщение Успешно сохранено

Убедитесь, что агент отображается в Teams

1. Откройте Teams >Приложения

2. Найдите имя агента

   ✅ Агент отображается в результатах поиска ✅ Отображаются значок и описание агента

Проверьте возможность создания экземпляра агента в Teams

Выберите агент в разделе "Приложения" Teams

✅ Кнопка "Запросить помощь/создать экземпляр" активна ✅ Можно запросить экземпляр без ошибок

Проверьте, что экземпляр агента создан

После нажатия Запросить экземпляр:

✅ Запрос успешно отправлен администратору

Убедитесь, что пользователь агента отображается в организации

В центре администрирования Microsoft 365:

1. Перейдите по адресу https://admin.cloud.microsoft/#/agents/all
2. Перейдите на вкладку "Все запросы" Агенты

✅ Запрос экземпляра агента отображается в состоянии "Ожидает рассмотрения" ✅ Администратор может утвердить экземпляр агента для использования ✅ Пользователь может создать экземпляр из Teams и дать ему имя.

Убедитесь, что агент отвечает на сообщения

В чате Teams с вашим агентом отправьте тестовое сообщение: Hello!

✅ Агент показывает индикатор ввода ✅ Агент отвечает в течение нескольких секунд ✅ Ответ связный и релевантный

Убедитесь, что агент может выполнять действия

Если вы настраиваете инструменты, проверьте их функциональность. Например, если вы добавите почтовый сервер MCP, отправьте себе тестовое сообщение электронной почты.

Агент должен:

✅ Подтвердить запрос ✅ Выполнить вызов инструмента ✅ Подтвердить успешное завершение

Убедитесь, что сообщение электронной почты доставлено в папку "Входящие".

Проверьте функциональность

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

Базовая функциональность:

✅ Агент отвечает на простые приветствия. ✅ Агент обрабатывает многоступенчатые разговоры. ✅ Агент предоставляет соответствующие ответы.

Функциональность инструментов:

Зависит от конфигурации сервера MCP

✅ Может отправлять сообщения электронной почты. ✅ Может получать доступ к календарю. ✅ Может искать документы. ✅ Может выполнять настроенные действия.

Обработка ошибок:

✅ Обрабатывает недопустимые запросы корректно. ✅ Предоставляет полезные сообщения об ошибках. ✅ Не дает сбой при непредвиденных входных данных.

Производительность:

✅ Отвечает в течение нескольких секунд. ✅ Нет ошибок тайм-аута. ✅ Стабильное время отклика.

Проверьте журналы приложений

Чтобы узнать, что делает ваш агент, проверьте журналы приложений, используя команду az webapp log tail.

# Real-time logs from Azure
az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

На что обращать внимание в журналах:

✅ Поступающие запросы из Teams ✅ Успешная проверка подлинности ✅ Выполнение вызовов инструментов ✅ Отправленные ответы ❌ Сообщения об ошибках или исключения

Проверьте наблюдаемость в центре администрирования

После того как агент начнет работать:

1. Перейдите к: https://admin.cloud.microsoft/#/agents/all.

2. Выберите агент и откройте вкладку Действие.

   Вы должны увидеть:

   ✅ Сеансы отображаются. ✅ В каждом сеансе отображаются триггеры и действия. ✅ Вызовы инструментов регистрируются с метками времени.

Следующие шаги

Ваш агент опубликован в облаке и готов работать вместе с вашей командой в Microsoft 365. То, что начиналось как локальный код, теперь стало зарегистрированным помощником корпоративного уровня, готовым к использованию во всей организации. Пользователи могут создавать экземпляры агента в пределах всей организации.

Жизненный цикл разработки агента завершен, но его влияние только начинается. Значительная часть компонентов, созданных в рамках жизненного цикла разработки Agent 365, имеет открытый исходный код и открыта для вклада сообщества. Сообщайте об ошибках, предлагайте новые функции и создавайте запросы на вытягивание:

• Примеры Agent 365: есть интересные и забавные примеры агентов? Поделитесь кодом агента с сообществом открытого кода здесь!
• Пакет SDK Node.js: пакет SDK Agent 365 на Node.js.
• Пакет SDK Python: пакет SDK Agent 365 на Python.
• Пакет SDK .NET: пакет SDK Agent 365 на C# (.NET).
• Интерфейс командной строки DevTools Agent 365: интерфейс командной строки, который поможет вам пройти весь жизненный цикл разработки Agent 365.

Устранение неполадок

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

Совет

Руководство по устранению неполадок Agent 365 содержит общие рекомендации по устранению неполадок, лучшие практики и ссылки на материалы по устранению неполадок для каждого этапа жизненного цикла разработки Agent 365.

Агент не отображается в Teams

Симптом: агент отображается в центре администрирования, но не отображается в приложениях Teams.

Первопричина: отсутствует конфигурация портала разработчика.

Решение:

1. Получите ИД схемы из a365.generated.config.json — найдите agentBlueprintId.

2. Выполните настройку на портале разработчика:

   1. Перейдите по адресу https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

   2. Установите для параметра Тип агента значение На основе API.

   3. Установите для параметра URL-адрес для уведомлений конечную точку обмена сообщениями агента. Найдите значение messagingEndpoint в a365.generated.config.json.

   4. Выберите Сохранить.

3. Подождите 5–10 минут для распространения изменений.

Проверка:

• Откройте Teams > Приложения > Поиск агента.
• Агент отображается и доступен для добавления.

Не удается создать экземпляр агента в Teams

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

Первопричина: Microsoft Agent 365 Frontier не включен для этого клиента.

Решение: обратитесь к администратору клиента, чтобы убедиться, что Microsoft Agent 365 Frontier включен для клиента.

Дополнительные сведения о Frontier.

Проверка:

После назначения соответствующей лицензии и настройки параметров администратором возможности Frontier становятся доступны в Microsoft 365 Copilot и приложениях Microsoft 365.

Агент не отвечает на сообщения

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

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

Базовое устранение неполадок

1. Проверьте, что веб-приложение запущено:

   az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
   # Should be: "Running"
   

2. Проверьте конечную точку обмена сообщениями:

   • Должно быть: https://<your-app-root-url>/api/messages
   • Проверьте в a365.config.json и a365.generated.config.json

3. Протестируйте конечную точку напрямую:

   curl https://<your-app-root-url>/api/messages
   # Should not return 404
   

4. Проверьте журналы приложений:

   az webapp log tail --name <your-app-name> --resource-group <your-resource-group>
   # Look for incoming requests and errors
   

Расширенная диагностика

1. Проверьте проверку подлинности:

   • Проверьте, истек ли срок действия токенов. Продлите их, если необходимо.
   • Проверьте учетные данные в конфигурации веб-приложения.

2. Проверьте конфигурацию инструмента/MCP:

   • Проверьте, настроены ли серверы MCP.
   • Убедитесь, что разрешения предоставлены.

3. Выполните локальное тестирование:

   • Запустите агент локально с той же конфигурацией.
   • Протестируйте на тестовой площадке агентов.
   • Если работает локально, но не в облаке, > проблема с развертыванием

Распространенные решения

• Конечная точка обмена сообщениями указана неверно: обновите на портале Azure и портале разработчика.
• Веб-приложение остановлено: запустите его через портал Azure или интерфейс командной строки.
• Срок действия токена истек: обновите токены в переменных среды веб-приложения.
• Отсутствующие переменные среды: проверьте параметры приложения на портале Azure.
• Проблемы с сервером MCP: проверьте субъект-службу и разрешения.
• Ошибки в коде: проверьте журналы приложений на наличие исключений.

Проверка

Отправьте сообщение своему агенту в Teams и проверьте журналы приложений на входящие запросы.

Вы также можете попробовать:

• Устранение неполадок при развертывании агента в Amazon Web Services.
• Устранение неполадок при развертывании агента в Google Cloud Platform.

Сбой вызовов инструментов

Симптом: агент отвечает на сообщения, но вызовы инструментов завершаются ошибкой. Вы видите ошибки отказа в доступе или тайм-ауты.

Первопричина: отсутствуют разрешения сервера MCP, субъект-служба не настроена, проблемы с сетевым подключением или неправильная конфигурация инструмента.

Решения

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

• Проверьте разрешения в центре администрирования

  Проверьте и утвердите необходимые разрешения сервера MCP:

  • Перейдите по адресу https://admin.cloud.microsoft/#/agents/all
  • Выберите агент > "Разрешения"
  • Убедитесь, что в списке указаны и утверждены все необходимые серверы MCP

• Проверьте субъект-службу

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

  # Download and run:
  # https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1
  

• Проверьте конфигурацию конечной точки MCP

  Убедитесь, что используется рабочая конечная точка MCP:

  # Should be production endpoint, not mock
  MCP_PLATFORM_ENDPOINT=https://agent365.svc.cloud.microsoft
  

• Проверьте управляемое удостоверение

  Проверьте, что управляемое удостоверение включено в вашем веб-приложении:

  # Verify managed identity is enabled
  az webapp identity show --name <your-app-name> --resource-group <your-resource-group>
  

Проверка

Протестируйте вызовы инструментов через Teams и проверьте журналы на успешное выполнение.

Вам также стоит попробовать следующие шаги:

• Средства устранения неполадок
• Устранение неполадок сервера имитации инструментов

Сбой при назначении лицензии

Симптом: вы не можете назначить лицензию пользователю агента. В центре администрирования отображаются лицензионные ошибки.

Первопричина: недостаточное количество лицензий, неправильный тип лицензии или проблема с разрешениями.

Решения

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

1. Проверьте наличие лицензий:

   • Проверьте центр администрирования Microsoft 365 >Выставление счетов>Лицензии.
   • Убедитесь, что Microsoft Agent 365 Frontier включен для клиента.

2. Назначение лицензии вручную:

   • Перейдите в центр администрирования Microsoft 365 >Пользователи.
   • Найдите пользователя агента.
   • Назначьте соответствующую лицензию.

3. Необходимые лицензии для полной функциональности:

   • Microsoft 365 E5 (или эквивалент).
   • Teams корпоративный.
   • Microsoft 365 Copilot (для функций Copilot).

Проверка

Проверьте, отображаются ли назначенные лицензии в профиле пользователя в центре администрирования.