Установите и используйте Agent 365 CLI

CLI Agent 365 — это кроссплатформенный инструмент командной строки для развертывания и управления приложениями Agent 365 на Azure. В этом справочнике объясняется, как устанавливать, обновлять, удалять и использовать CLI для автоматизации и устранения неполадок.

Вам не нужно устанавливать CLI вручную.Agent 365 Skills проверяет наличие CLI, устанавливает или обновляет его автоматически и выполняет все необходимые команды от вашего имени. Эта статья служит справочником для разработчиков, которым необходимо напрямую установить или использовать CLI — например, при создании автоматизации CI/CD, устранении определённых этапов или работе без AI-агента кодирования.

Note

Полный рабочий процесс для разработчиков — включая настройку с помощью ИИ, рекомендации по ролям и шаги после развертывания — описан в разделе Начало разработки с Agent 365. Эта статья — справочник CLI: установка, обновление, удаление, доступные команды и устранение неполадок.

Альтернатива массового подключения

Когда нужно одновременно внедрять множество агентов, используйте скрипты PowerShell для массового онбординга Agent 365 как альтернативу отдельному a365 процессу онбординга CLI для каждого агента. Скрипты предоставляют чертежи, идентификаторы агентов, пользователей агентов и регистрацию агентов из CSV-файла. Они отделены от CLI, а не CLI-команды.

Полный рабочий процесс см. Bulk Agent 365 onboarding. Это руководство охватывает предварительные требования, установку автоматизационных приложений, поддерживаемые поля CSV и правила валидации, выполнение, результаты и устранение неполадок.

Prerequisites

Для CLI требуется .NET 8.0 или выше. Для всех остальных требований, включая подписку на Azure и обязательные роли Entra, см. Быстрый старт: Подключить существующего агента к агенту 365.

аутентификация Microsoft Entra

По умолчанию настройка Agent 365 использует корпоративное приложение Agent 365 CLI, управляемое Microsoft, когда оно доступно в вашем арендаторе.

Property Value
Показать имя Agent 365 CLI
Идентификатор приложения (клиента) f54280f4-395e-4ea8-9e48-bf2d4952aa14

Чтобы проверить приложение, перейдите в Центр администрирования Microsoft Entra, выберите Enterprise>applications All apps и найдите идентификатор приложения. Объектный идентификатор принципала сервиса уникален для вашего арендатора. Не используйте идентификатор объекта, где CLI или документация запрашивают идентификатор приложения (клиента).

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

Если корпоративное приложение, управляемое Microsoft, недоступно, настройка без конфигурации ищет приложение арендатора под названием Agent 365 CLI. Существующие конфигурации, указывающие пользовательское clientAppId задание, остаются поддерживаемыми. Для инструкций см. раздел Регистрация пользовательского клиентского приложения для Agent 365 CLI.

Приложение, управляемое Microsoft, использует следующие интерактивные методы аутентификации:

Окружающая среда Метод аутентификации
Родные Windows Менеджер веб-учетных записей (WAM)
подсистема Windows для Linux (WSL), macOS и Linux Код устройства

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

Установка интерфейса командной строки агента 365

Чтобы установить агент 365 CLI глобально в операционной системе, выполните следующие действия.

Prerequisites

Необходимо установить .NET. (Рекомендуется использовать .NET 8.0.)

Используйте dotnet tool install

Установите Agent 365 CLI с помощью следующей команды:

dotnet tool install --global Microsoft.Agents.A365.DevTools.Cli

Для получения последних инструкций и доступных версий посетите официальную страницу NuGet: Microsoft.Agents.A365.DevTools.Cli на NuGet.org

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

После установки Agent 365 CLI проверьте правильность установки, выполнив команду --help.

a365 -h

Эта команда отображает сведения справки и подтверждает, что интерфейс командной строки готов к использованию.

Обновить CLI Agent 365

Обновите Agent 365 CLI с помощью команды dotnet tool update

dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli

Note

Для обновления Agent 365 CLI вам потребуется подключение к Интернету для доступа к самой новой версии NuGet-пакета: Microsoft.Agents.A365.DevTools.Cli.

Удалить CLI Agent 365

Удалите Agent 365 CLI с помощью команды dotnet tool uninstall:

dotnet tool uninstall --global Microsoft.Agents.A365.DevTools.Cli

Расположения файлов CLI агента 365

Расположение по умолчанию для исполняемого файла средства зависит от операционной системы:

OS Путь
Linux или macOS $HOME/.dotnet/tools
Windows %USERPROFILE%\.dotnet\tools

SDK добавляет этот путь в системную переменную PATH при первом запуске. Вы можете вызвать глобальные инструменты из любого каталога, не указывая местоположение инструмента.

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

Облака для государственных организаций США

По умолчанию CLI Agent 365 ориентирован на коммерческое облако Microsoft. Он аутентифицируется с помощью https://login.microsoftonline.com, вызывает Microsoft Graph по https://graph.microsoft.comадресу , а сервисы Agent 365 — по https://agent365.svc.cloud.microsoftадресу . Чтобы запустить CLI в облаке правительства Microsoft 365 США, установите среду на gcc, gcc-highили dod, и настройте конечные точки для этого облака.

Имя окружения выбирает облачные настройки, но не меняет конечную точку самостоятельно. Для GCC установите конечную точку обнаружения Agent 365 Tools. Для GCC High и DoD также установите авторитетный хост и базовый URL Microsoft Graph.

Укажите окружение, авторитетный хост и базовый URL графа в a365.config.json (environment, authorityHost, и graphBaseUrl) или используйте переменные среды, указанные в следующей таблице. Переменные, ориентированные на окружение, заканчиваются нормированным суффиксом имени облака (<ENV>), таким как GCC или GCC_HIGH, и имеют приоритет над соответствующими a365.config.json полями.

Variable Description
A365_ENVIRONMENT Имя облачной среды. CLI использует это значение, когда a365.config.json не устанавливает environment, и для команд, которые не читают a365.config.json. Значение по умолчанию — prod.
A365_AUTHORITY_HOST_<ENV> Ведущий OAuth Authority. Это значение имеет приоритет над authorityHost .a365.config.json
A365_GRAPH_BASE_URL_<ENV> Базовый URL Microsoft Graph. Это значение имеет приоритет над graphBaseUrl .a365.config.json
A365_DISCOVER_ENDPOINT_<ENV> Конечная точка обнаружения Agent 365 Tools. CLI также использует свой источник для связанных сервисных вызовов Agent 365.
A365_CREATE_ENDPOINT_<ENV> URL регистрации конечной точки сообщений.
A365_DELETE_ENDPOINT_<ENV> URL удаления конечных точек сообщений.
A365_MCP_APP_ID_<ENV> Идентификатор ресурса Agent 365 Tools, который CLI использует для получения токенов для серверов инструментов. Большинству разработчиков не нужно устанавливать эту переменную.

Для значений облачных конечных точек, <ENV> правил нормализации суффиксов и полных примеров см. раздел Configure the Agent 365 CLI для облаков правительства США.

Команды CLI агента 365

Для получения полного списка доступных команд используйте команду --help или см. Справочник по Agent 365 CLI.

Tip

Нет необходимости вручную выполнять команды CLI. Навыки агента 365 автоматизируют весь рабочий процесс — установку, конфигурацию CLI, установку чертежей, развертывание и публикацию — с помощью агента кодирования на базе ИИ. Используйте справочник по CLI здесь, если вы создаете автоматизацию CI/CD, устраняете неполадки на определенном этапе или работаете без агента кодирования на базе ИИ.

Полные инструкции по настройке агента Agent 365 с помощью CLI см. в разделе Начало разработки с Agent 365.

Troubleshooting

В этом разделе представлена информация о том, как устранять ошибки, связанные с Agent 365 CLI.

Tip

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

Связанные с CLI проблемы, рассматриваемые в этом разделе:

Приложение CLI, управляемое Microsoft Agent 365, недоступно

Обновите CLI и запустите a365 setup requirements снова. Чтобы проверить, дошло ли поэтапное развертывание до вашего арендатора, выполните поиск «Корпоративные приложения» в Microsoft Entra по идентификатору f54280f4-395e-4ea8-9e48-bf2d4952aa14приложений.

Если принципал сервиса отсутствует, настройка возвращается к приложению, принадлежащему арендатору, под названием Agent 365 CLI. Если у вас ещё нет этого приложения, следите за регистрацией пользовательского клиента для Agent 365 CLI.

Аутентификация кода устройства блокируется

Приложение, управляемое Microsoft, использует аутентификацию кода устройства на WSL, macOS и Linux. Стандартные настройки безопасности или политика условного доступа могут блокировать этот поток и возвращать AADSTS530035.

Не отключайте политику безопасности вашей организации, чтобы обойти эту ошибку. Запустите CLI на нативной Windows для WAM или работайте с администратором идентичности, чтобы использовать пользовательское приложение, принадлежащее арендатору, и поток аутентификации, который позволяет ваша политика.

Аутентификация не проходит с AADSTS70007

Старые версии CLI могут использовать неподдерживаемый режим ответа браузера с приложением, управляемым Microsoft, и возвращать AADSTS70007. Обновите до последней версии CLI и попробуйте снова:

dotnet tool update --global Microsoft.Agents.A365.DevTools.Cli

Требуемые делегированные области отсутствуют

CLI подтверждает эффективные делегированные разрешения приложения под управлением Microsoft на основе требования токена scp доступа. Обновите CLI и запустите a365 setup requirementsповторно.

Не добавляйте URI перенаправления, необязательные претензии, разрешения API или разрешения арендатора в приложение, управляемое Microsoft. Если проверка всё ещё показывает отсутствующие диапазоны, зафиксируйте трассировка и корреляционные идентификаторы из ошибки и свяжитесь с поддержкой Microsoft. Если вы используете приложение, принадлежащее арендатору, следуйте шагам проверки в разделе Регистрация пользовательского клиента для Agent 365 CLI.

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

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

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

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

  • Последнее обновление: