Чертеж агента настройки

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

Note

Для включения возможностей Register, Work IQ и AI команды требуется настройка плана агента. См. раздел «Начать с разработки Agent 365 », чтобы понять, какие возможности применимы к вашему агенту.

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

Необходимые условия

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

  1. Agent 365 CLI — см. установку CLI Agent 365.

  2. Необходимые разрешения:

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

    Tip

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

Создание чертежа агента

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

Запуск программы установки

Запустите команду setup:

a365 setup -h

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

Note

a365 setup all По умолчанию переходит в режим Blueprint Agent. Чтобы настроить агента с ИИ, пропустите --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 чертеж, необходимый для управления платформой

    Important

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

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

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

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

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

Note

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

Настройка с помощью Agent ID Developer

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

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

  • Azure infrastructure (resource group, App Service Plan, Web App)
  • Регистрация чертежа агента
  • Наследуемые права для экземпляров агентов

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

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

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

Step Кто Action
1 Разработчик Выполните команду a365 setup all. CLI выполняет все возможные шаги и печатает следующие шаги, включая согласие URL для открытия глобальным администратором.
2 Разработчик Передайте URL согласия из выхода CLI с вашим глобальным администратором.
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.

Поделитесь дальнейшими шагами, напечатанными CLI, с вашим глобальным администратором. Они могут открыть предоставленную ссылку или согласие 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"
}

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

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

    Note

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

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

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

    # 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 , содержащий все конфигурационные данные.

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

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

    Important

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

  5. В приложении Verify Web App включена управляемая идентификация:

    Используйте 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 Admin Center, портал проверяет права на 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 (AWS)

Облачная платформа Google (GCP)

Агент публикации в административный центр Microsoft

Troubleshooting

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

Tip

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

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

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

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

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

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

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

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

Note

Если у вас есть Agent ID Administrator или Agent ID Developer (не Global Administrator), a365 setup all то всё равно проходит успешно, но пропускает OAuth2 permission grants. После завершения настройки CLI печатает следующие шаги для глобального администратора, чтобы завершить оставшиеся гранты. Такой рабочий процесс ожидается для организаций, где разработчик агента и глобальный администратор — разные люди.

Missing Azure CLI authentication

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

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

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

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

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

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

  • Используйте существующие ресурсы

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

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

  • Удалить противоречивые ресурсы

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

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

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

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

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

    Warning

    Бег a365 cleanup — это разрушительно.

    a365 cleanup
a365 setup all

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

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

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

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

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

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

Solution:

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

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

Symptom: Команда setup успешно выполняется, но Azure ресурсов нет.

Solution:

  1. Проверьте созданные ресурсы, открыв a365.generated.config.json в вашем рабочем каталоге.
  2. Проверьте наличие Azure ресурсов, используя команду az resource list.
  3. Если ресурсы отсутствуют, проверьте на ошибки в выводе setup и перезапустите setup с помощью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

Symptom: Настройка завершена, но вы не можете найти Agent Blueprint в Центр администрирования Microsoft Entra.

Solution:

  1. Получите ID чертежа из 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 не предоставлены

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

Solution:

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

  2. Найдите регистрацию в приложении Agent Blueprint.

  3. Перейдите к разрешениям API.

  4. Согласие администратора гранта:

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

  5. Проверьте все разрешения, показывают зелёные галочки.

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

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

Solution:

  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 минут без завершения.

Solution:

  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 для удаления агента без конфигурационного файла. CLI считывает идентификаторы ресурсов из глобально сгенерированной конфигурации, записанной при загрузке загрузки.

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

Tip

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

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

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

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

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

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