Настройка схемы агента

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

Примечание

Настройка схемы агента необходима для включения возможностей регистрации, Work IQ и ИИ-напарника. См. руководство Начало работы с Agent 365, чтобы понять, какие возможности применимы к вашему агенту.

Для получения дополнительной информации об идентификаторе Agent 365 см. раздел Идентификатор Agent 365.

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

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

  1. Интерфейс командной строки Agent 365 — см. Установка интерфейса командной строки Agent 365.

  2. Требуемые разрешения:

    • Действительный пользователь арендатора с одной из следующих ролей:
      • Глобальный администратор
      • Разработчик идентификатора агента
    • Доступ к подписке Azure с правами на создание ресурсов

    Совет

    Агентам (не ИИ-напарникам) не нужен конфигурационный файл. Используйте a365 setup all --agent-name <name>, и интерфейс командной строки автоматически определяет ваш арендатор и клиентское приложение. Настройка ИИ-напарника требует ручного создания a365.config.json.

Создание схемы агента

Используйте команду a365 setup для создания ресурсов Azure и регистрации схемы агента. Схема определяет идентичность вашего агента, его разрешения и требования к инфраструктуре. Этот этап закладывает основу для развертывания и запуска вашего агента в Azure.

Запуск настройки

Выполните команду настройки:

a365 setup -h

У команды есть различные параметры. Вы можете выполнить всю настройку одной командой с помощью a365 setup all или выбрать более подробные параметры.

Примечание

a365 setup all по умолчанию работает в режиме агента-схемы. Чтобы вместо этого настроить агент как ИИ-напарник, передайте --aiteammate. Для агентов M365 (Teams, Copilot) также передайте --m365, чтобы автоматически зарегистрировать конечную точку обмена сообщениями.

Настройка агента (по умолчанию):

# With a config file
a365 setup all

# Config-free — no a365.config.json needed
a365 setup all --agent-name <your-agent-name>

Настройка агента M365 (Teams/Copilot):

# Registers the messaging endpoint via MCP Platform
a365 setup all --m365

Настройка агента-напарника с ИИ:

a365 setup all --aiteammate

Весь процесс настройки выполняет следующие операции:

  1. Создает инфраструктуру Azure (если ее еще нет):

    • Группа ресурсов
    • План службы приложений с указанным SKU
    • Веб-приложение Azure с включенной управляемой идентичностью

  2. Регистрирует схему агента:

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

    Важно

    Схемы должны иметь установленный managerApplications, чтобы быть приняты платформой. Интерфейс командной строки устанавливает это автоматически. Если у вас уже есть схема, созданная до введения этого требования, удалите ее и запустите a365 setup all заново, либо вручную обновите ее через API Graph.

  3. Настраивает разрешения API:

    • Настраивает области доступа Microsoft API Graph
    • Настраивает разрешения API бота для обмена сообщениями
    • Применяет наследуемые разрешения для экземпляров агентов

  4. Обновляет файлы конфигурации:

    • Сохраняет сгенерированные идентификаторы и конечные точки в новом файле в вашем рабочем каталоге с именем a365.generated.config.json
    • Сохраняет информацию об управляемой идентичности и ресурсах

Примечание

Настройка обычно занимает 3–5 минут и автоматически сохраняет конфигурацию в a365.generated.config.json. Если вы запускаете интерфейс командной строки как глобальный администратор, может открыться окно браузера для подтверждения согласия администратора — завершите процесс согласия, чтобы продолжить. Если вы запускаете с ролью разработчика идентификатора агента, окно браузера не появляется; интерфейс командной строки генерирует URL-адреса для согласия, которые глобальный администратор может использовать позже.

Настройка с использованием разработчика идентификатора агента

Если вы работаете с ролью разработчика идентификатора агента (не глобального администратора), a365 setup all автоматически выполняет большинство шагов, но предоставление разрешений OAuth2 требует отдельного действия глобального администратора.

Какие шаги выполняются автоматически:

  • Инфраструктура Azure (группа ресурсов, план службы приложений, веб-приложение)
  • Регистрация схемы агента
  • Наследуемые разрешения для экземпляров агентов

Какие шаги требуют участия глобального администратора:

  • Делегированные разрешения OAuth2 (согласие AllPrincipals) для Microsoft Graph, инструментов Agent 365, API бота для обмена сообщениями, API наблюдаемости и Power Platform API

Как завершить настройку, используя учетную запись без прав администратора:

Шаг Кто Действие
1 Разработчик Запустите a365 setup all. Интерфейс командной строки выполняет все возможные шаги и выводит следующие шаги, включая URL-адрес для предоставления согласия, который должен открыть глобальный администратор.
2 Разработчик Отправьте ссылку для согласия, сгенерированную интерфейсом командной строки, вашему глобальному администратору.
3 Глобальный администратор Откройте URL-адрес согласия в браузере, войдя в систему как Глобальный администратор, и предоставьте запрошенные разрешения.

Запуск команд:

# Developer runs:
a365 setup all
# Setup completes all steps it can. The CLI prints the next steps
# for a Global Administrator directly in the output, including a
# direct link or consent URL they can open to complete the grants.

Передайте вашему глобальному администратору следующие шаги, выведенные интерфейсом командной строки. Глобальный администратор может открыть предоставленную ссылку или URL-адрес для согласия, чтобы завершить предоставление разрешений OAuth2.

Проверка настройки

Когда настройка завершится, вы увидите сводку всех выполненных шагов. Проверьте созданные ресурсы:

  1. Проверьте сгенерированную конфигурацию:

    Откройте a365.generated.config.json в вашем рабочем каталоге. Или используйте PowerShell:

    Get-Content a365.generated.config.json | ConvertFrom-Json

    Ожидаемый результат включает следующие критические значения:

    {
"managedIdentityPrincipalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintServicePrincipalObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintClientSecret": "xxx~xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"agentBlueprintClientSecretProtected": true,
"botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"botMsaAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"messagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
"resourceConsents": [],
"completed": true,
"completedAt": "xxxx-xx-xxTxx:xx:xxZ",
"cliVersion": "x.x.xx"
}

    Ключевые поля для проверки:

    Поле Назначение Что проверить
    managedIdentityPrincipalId Аутентификация с помощью управляемой идентификации Azure Должен быть допустимым GUID
    agentBlueprintId Уникальный идентификатор вашего агента Используется на портале разработчиков и в центре администрирования
    agentBlueprintObjectId Microsoft Entra ID схемы
    messagingEndpoint Маршрутизация сообщений Где Teams/Outlook отправляют сообщения агенту
    agentBlueprintClientSecret Секрет проверки подлинности Должно существовать (значение замаскировано)
    resourceConsents Разрешения API Должны содержаться такие ресурсы, как Microsoft Graph, инструменты Agent 365, API для ботов обмена сообщениями, API наблюдаемости
    completed Состояние настройки Должно быть true

    Примечание

    Если вы выполняли настройку как администратор идентификатора агента или разработчик идентификатора агента, resourceConsents может быть пустым, а completed может быть false до тех пор, пока глобальный администратор не завершит предоставление разрешений OAuth2, используя следующие шаги, выведенные интерфейсом командной строки.

  2. Проверьте ресурсы Azure на портале Azure:

    Или используйте команду PowerShell az resource list.

    # List all resources in your resource group
az resource list --resource-group <your-resource-group> --output table

    Проверьте, что созданы следующие ресурсы:

    • Группа ресурсов:

      • Откройте Группы ресурсов> выберите вашу группу ресурсов
      • Убедитесь, что в ней есть ваш план службы приложений и веб-приложение

    • План службы приложений:

      • Перейдите в Службы приложений>Планы служб приложений
      • Найдите свой план и убедитесь, что ценовой уровень соответствует вашему конфигурационному SKU

    • Веб-приложение:

      • Перейдите в Службы приложений>Веб-приложения
      • Найдите свое веб-приложение, затем перейдите в раздел Параметры>Идентификатор>Назначенный системой
      • Убедитесь, что статус — Включено
      • Обратите внимание, что идентификатор объекта (субъект) совпадает с managedIdentityPrincipalId

  3. Проверьте приложения Microsoft Entra на портале Azure:

    Перейдите в Azure Active Directory>Регистрации приложений>Все приложения:

    • Найдите схему вашего агента по agentBlueprintId

    • Откройте приложение и выберите разрешения API

    • Убедитесь, что разрешения предоставлены и отмечены зелеными галочками:

      • Microsoft Graph (делегированные разрешения и разрешения приложений)
      • Разрешения API для бота обмена сообщениями

    • Все разрешения показывают «Предоставлено для [вашего арендатора]»

  4. Проверьте, что создан сгенерированный конфигурационный файл:

    У вас должен быть файл с именем a365.generated.config.json, который содержит все конфигурационные данные.

    Используйте команду PowerShell Test-Path, чтобы убедиться, что файл существует.

    # Check file exists
Test-Path a365.generated.config.json
# Should return: True

    Важно

    Сохраните файлы a365.config.json и a365.generated.config.json. Эти значения нужны для развертывания и устранения неполадок.

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

    Используйте az webapp identity show команду, чтобы проверить, включена ли управляемая идентичность.

    az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

    Ожидается:

    {
"principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"type": "SystemAssigned"
}

  6. Проверьте, что схема агента зарегистрирован в Microsoft Entra:

    В Центре администрирования Microsoft Entra найдите ваш agentBlueprintId или выполните поиск по имени.

    Проверьте, что:

    ✅ Отображаются регистрация приложения и корпоративное приложение
    ✅ На вкладке Разрешения API в схеме регистрации приложения отображаются все разрешения
    ✅ Статус отображает «Предоставлено для [вашего арендатора]»

Дополнительную справку см. в следующих статьях:

Разрешения агента

Прежде чем приложения и агенты смогут читать или записывать данные Microsoft 365 (пользователи, почта, файлы, Teams, агенты и т. д.), вы должны явно предоставить им разрешения Microsoft Graph. Разрешения Microsoft Graph представляют собой модель авторизации, определяющую, к каким данным и действиям приложение или сервис может получить доступ через API Microsoft Graph в Microsoft 365 и Microsoft Entra ID.

Подробнее: Обзор разрешений Microsoft Graph

Чтобы использовать разрешения Graph для экземпляров агента Agent 365, разработчик должен указать их в схеме агента. Когда администратор активирует схему агента в Центр администрирования Microsoft 365, портал проверяет разрешения Microsoft Graph, указанные в схеме, и предлагает администратору дать согласие на них.

Чтобы понять и проверить, как разрешения Graph позволяют агенту работать, вы можете:

Применение разрешений к вашей схеме

Используйте a365 setup permissions custom для применения пользовательских разрешений API непосредственно в вашем схеме в Microsoft Entra.

a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

Подробнее о настройке и удалении пользовательских разрешений смотрите setup permissions custom.

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

Разверните код агента в облаке:

Azure

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

Публикация агента в Центре администрирования Microsoft

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

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

Совет

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

Эти проблемы иногда возникают во время регистрации:

Ошибка недостаточных разрешений

Симптом: ошибка недостаточных прав во время выполнения команды a365 setup.

Вам необходима одна из следующих ролей в вашем арендаторе Microsoft Entra:

  • Глобальный администратор
  • Разработчик идентификатора агента

И доступ с правами участника или владельца подписки Azure.

Решение: убедитесь, что у вас есть необходимые права в Microsoft Entra.

Примечание

Если у вас назначена роль администратора идентификатора агента или разработчика идентификатора агента (не глобального администратора), a365 setup all все равно успешно выполняется, но пропускает предоставление разрешений OAuth2. После завершения настройки интерфейс командной строки отображает следующие шаги для Глобального администратора по выдаче оставшихся разрешений. Такой рабочий процесс ожидается для организаций, где разработчик агента и глобальный администратор — разные люди.

Отсутствует аутентификация в интерфейсе командной строки Azure

Симптом: настройка прерывается из-за ошибок аутентификации.

Решение: убедитесь, что вы подключены к Azure, и проверьте свою учетную запись и подписку.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

Ресурс уже существует

Симптом: настройка прерывается с Resource already exists ошибкой для группы ресурсов, плана службы приложений или веб-приложения.

Решения: выберите одно из следующих решений.

  • Использование существующих ресурсов

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

    az resource list --resource-group <your-resource-group>

  • Удаление конфликтующих ресурсов

    Удалите группу ресурсов или переименуйте ваши ресурсы в a365.config.json, затем повторно запустите настройку.

    Используйте команду PowerShell az group delete, чтобы удалить группу ресурсов.

    # WARNING: This command deletes all resources in it
az group delete --name <your-resource-group>

  • Используйте команду очистки, чтобы начать с чистого листа

    Используйте команду cleanup для удаления всех ресурсов Agent 365, затем используйте команду a365 setup all для повторного запуска настройки.

    Предупреждение

    Запуск a365 cleanup является разрушительным.

    a365 cleanup
a365 setup all

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

Решение: выберите в зависимости от вашей роли:

  • Глобальный администратор: запустите a365 setup all снова. Интерфейс командной строки запрашивает согласие администратора. Завершите процедуру согласия в появившемся окне браузера.

  • Администратор идентификатора агента или разработчик: вы не можете самостоятельно завершить предоставление разрешений OAuth2. Запустите a365 setup all — сводка по настройке отображает следующие шаги для глобального администратора, включая прямую ссылку или URL-адрес для согласия для завершения предоставления разрешений. Поделитесь этими деталями с вашим глобальным администратором.

Файлы конфигурации отсутствуют или недействительны

Симптом: настройка завершается ошибкой «Конфигурация не найдена» или ошибками валидации.

Решение:

  1. Проверьте, существует ли файл a365.config.json.
  2. Если отсутствует или некорректен, создайте его вручную или используйте a365 setup all --agent-name <name> (только агенты).
# Verify a365.config.json exists
Test-Path a365.config.json

Настройка завершена, но ресурсы не созданы

Симптом: команда setup успешно выполняется, но ресурсы Azure не созданы.

Решение:

  1. Проверьте созданные ресурсы, открыв a365.generated.config.json в вашем рабочем каталоге.
  2. Проверьте наличие ресурсов Azure с помощью команды az resource list.
  3. Если ресурсы отсутствуют, проверьте наличие ошибок в выводе настройки и повторите настройку с помощью команды a365 setup all.
# Check created resources
Get-Content a365.generated.config.json | ConvertFrom-Json

# Verify Azure resources exist
az resource list --resource-group <your-resource-group> --output table

# If resources missing, check for errors in setup output and re-run
a365 setup all

Схема агента не зарегистрирована в Microsoft Entra

Симптом: настройка завершена, но вы не можете найти схему агента в центре администрирования Microsoft Entra.

Решение:

  1. Получите ИД схемы из a365.generated.config.json.

    Get-Content a365.generated.config.json | ConvertFrom-Json | Select-Object agentBlueprintId

  2. Найдите в центре администрирования Microsoft Entra:

    1. Перейдите в Центр администрирования Microsoft Entra.
    2. Выберите Регистрация приложений>Все приложения.
    3. Выполните поиск по своему agentBlueprintId.

  3. Если не найден, повторно выполните настройку, используя команду a365 setup all.

    a365 setup all

Разрешения API не предоставлены

Симптом: настройка завершается, но разрешения отображаются как «Не предоставлено» в Microsoft Entra.

Решение:

  1. Откройте центр администрирования Microsoft Entra.

  2. Найдите регистрацию приложения схемы агента.

  3. Перейти к пункту Разрешения API.

  4. Предоставьте согласие администратора:

    1. Выберите Предоставить согласие администратора для [ваш арендатор].
    2. Подтвердите действие.

  5. Убедитесь, что все разрешения отмечены зелеными галочками.

Управляемый идентификатор не включен

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

Решение:

  1. Проверьте статус управляемой идентичности с помощью команды az webapp identity show.
  2. Если не включено, включите его вручную, используя команду az webapp identity assign.
  3. Проверьте, что он включен, с помощью команды az webapp identity show.
# Check managed identity status
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

# If not enabled, enable it manually
az webapp identity assign --name <your-web-app> --resource-group <your-resource-group>

# Verify it's enabled
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

Настройка занимает слишком много времени или перестает реагировать

Симптом: команда настройки выполняется более 10 минут и не завершается.

Решение:

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

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

    # Check generated config
Get-Content a365.generated.config.json | ConvertFrom-Json

# Check Azure resources
az resource list --resource-group <your-resource-group>

  3. Очистите и попробуйте снова.

    a365 cleanup
a365 setup all

Очистка агента без конфигурации

Симптом: вы создали агента с помощью a365 setup all --agent-name <name>, а теперь хотите удалить его, но у вас нет конфигурационного файла a365.config.json.

Решение: используйте a365 cleanup --agent-name для удаления агента без конфигурационного файла. Интерфейс командной строки считывает идентификаторы ресурсов из глобальной сгенерированной конфигурации, записанной во время настройки Bootstrap.

a365 cleanup --agent-name <your-agent-name>

Совет

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

Если у вас больше нет глобальной сгенерированной конфигурации (например, после переустановки интерфейса командной строки), используйте a365 cleanup с вручную созданной минимальной конфигурацией a365.config.json, или удалите ресурсы напрямую через портал Azure и Центр администрирования Microsoft Entra.

Невозможно отправить первое сообщение в Teams

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

Решение: для создания нового объекта чата требуется разрешение [Chat.Create][perm-chatcreate]. Если индивидуальный чат уже существует, эта операция возвращает уже созданный чат и не создает новый чат.

  • Для реализации настройте наследуемые разрешения вашей схемы так, чтобы они включали область Chat.Create.
  • Настройте сообщение в чате Teams для автоматической отправки после создания экземпляра агента.
  • Создайте новый экземпляр агента из схемы и протестируйте отправку приветственного сообщения.
  • Last updated on