Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
По мере развития декларативного агента необходимо подготовить его для нескольких сред — разработки, промежуточной и производственной — и в конечном итоге запустить параллельные версии, чтобы можно было опробовать новые возможности, не нарушая работу существующих пользователей. Ведение отдельного набора файлов манифеста для каждой комбинации среды и версии не масштабируется.
Набор инструментов агентов Microsoft 365 отвечает обоим требованиям: целевой среде и версии агента с одним и тем же механизмом: файлами среды. Определив один .env.* файл для каждого целевого объекта и используя ${{VAR_NAME}} заполнители во всем файле манифеста декларативного агента, вы можете подготовить любую среду или версию с помощью одной команды, m365agents.ymlatk provision --env <target>не дублируя один файл.
Совет
Рекомендуется: Начните с Work IQ Dev Tools для поддерживаемых сценариев декларативного агента и плагинов для кода. См. краткое руководство по WIQD. Инструкции на основе набора средств остаются доступными для существующих проектов и рабочих процессов, для которых они требуются. Перед выбором инструмента проверьте поддержку возможностей и целевого интерфейса : WIQD не нацелен на агентов пользовательской подсистемы.
Две оси, одна система
Управление средой для декларативных агентов имеет два измерения:
- Целевые среды: один и тот же агент подготовлен для разных клиентов или регистраций приложений: клиентов, разработчиков, промежуточных, производственных или клиентских.
- Версии агента: несколько вариантов одного и того же агента, работающих параллельно, например v1 стабильная, v2 preview или экспериментальная ветвь.
Оба измерения обрабатываются одинаково. Для каждого целевого объекта определяется файл среды, а также ${{VAR_NAME}} заполнители в файле декларативного агента манифеста и m365agents.yml разрешение во время подготовки.
Моделирование целевых сред
Большинство команд предоставляют как минимум две среды — среду разработки и рабочую — и многие добавляют промежуточную среду между ними. Создайте по одному файлу для каждой среды в папке env/ :
env/
├── .env.dev
├── .env.dev.user
├── .env.staging
├── .env.staging.user
├── .env.prod
└── .env.prod.user
В каждом файле определяются одинаковые имена переменных со значениями, зависящими от среды:
# env/.env.staging
TEAMS_APP_ID=33333333-3333-3333-3333-333333333333
AAD_CLIENT_ID=44444444-4444-4444-4444-444444444444
API_BASE_URL=https://api-staging.contoso.com
SHAREPOINT_SITE_URL=https://contoso.sharepoint.com/sites/hr-staging
AGENT_DISPLAY_NAME=HR Onboarding Buddy (Staging)
TEAMSFX_ENV=staging
Совет
Включайте имя среды в отображаемое имя агента для непроизводственных клиентов. Например, "HR Onboarding Buddy (Staging)" дает тестировщикам сразу понять, какую версию они используют, что помогает избежать путаницы при сообщении о проблемах.
Чтобы настроить таргетинг на другую среду, передайте --env флаг каждой команде Agents Toolkit:
atk provision --env staging
atk deploy --env staging
atk publish --env staging
Модель нескольких версий
Версии агентов следуют тому же шаблону, что и целевые среды. Каждая версия является целью развертывания со своим собственным файлом среды. Чтобы развернуть агент версии 2 (v2) вместе с агентом версии 1 (v1) в том же рабочем клиенте, добавьте prod-v2 среду:
env/
├── .env.dev
├── .env.staging
├── .env.prod # v1, the stable one
├── .env.prod-v2 # v2, running side by side
└── ...corresponding .user files
Предоставьте .env.prod-v2 уникальный идентификатор приложения Teams, чтобы оба агента могли сосуществовать в одном клиенте:
# env/.env.prod-v2
TEAMS_APP_ID=55555555-5555-5555-5555-555555555555
AAD_CLIENT_ID=22222222-2222-2222-2222-222222222222
API_BASE_URL=https://api.contoso.com
SHAREPOINT_SITE_URL=https://contoso.sharepoint.com/sites/hr
AGENT_DISPLAY_NAME=HR Onboarding Buddy (Preview)
AGENT_VERSION=2.0.0
TEAMSFX_ENV=prod-v2
Используйте переменные в манифесте для любого значения, которое отличается в зависимости от версии:
{
"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.24/MicrosoftTeams.schema.json",
"manifestVersion": "1.24",
"id": "${{TEAMS_APP_ID}}",
"version": "${{AGENT_VERSION}}",
"name": {
"short": "${{AGENT_DISPLAY_NAME}}",
"full": "${{AGENT_DISPLAY_NAME}} - Contoso"
},
"developer": {
"name": "Contoso",
"websiteUrl": "${{API_BASE_URL}}"
},
"copilotAgents": {
"declarativeAgents": [
{
"id": "declarativeAgent",
"file": "declarativeAgent.json"
}
]
}
}
В результате мы получим один файл манифеста, который создает два разных приложения в одном клиенте. Пользователи, которым предоставляется доступ к предварительной версии, используют версию 2; Все остальные пользователи продолжают использовать версию 1.
Примечание
Ключом к этому шаблону является идентификатор приложения Teams. Платформа рассматривает приложения с разными идентификаторами как отдельные приложения, независимо от того, сколько кода они используют. Это разделение также позволяет проводить A/B-тестирование персон агентов без какого-либо влияния на пользователей рабочей среды.
Разветвление самого определения агента
Когда различия версий выходят за рамки значений переменных (например, разные инструкции, новая возможность или другой набор плагинов), у вас есть два варианта ветвления самого определения агента.
Вариант A. Оставьте одинарный declarativeAgent.json параметр и используйте переменные для значений, которые различаются. Этот подход хорошо работает, когда различия незначительны, например разный абзац инструкций или другой URL-адрес сайта SharePoint.
Вариант B. Ведение отдельного файла декларативного агента для каждой версии и ссылка на него через переменную в манифесте приложения Teams:
{
"copilotAgents": {
"declarativeAgents": [
{
"id": "declarativeAgent",
"file": "declarativeAgent.${{AGENT_VARIANT}}.json"
}
]
}
}
В m365agents.yml, настройте шаг пакета, чтобы включить его ${{TEAMSFX_ENV}} в имя выходного артефакта, чтобы каждая среда создавала отдельный ZIP-файл:
provision:
- uses: teamsApp/zipAppPackage
with:
manifestPath: ./appPackage/manifest.json
outputZipPath: ./appPackage/build/appPackage.${{TEAMSFX_ENV}}.zip
outputFolder: ./appPackage/build
Когда AGENT_VARIANT=v1сборка разрешается в declarativeAgent.v1.json. Когда AGENT_VARIANT=v2, он разрешается в declarativeAgent.v2.json. Оба файла хранятся в репозитории и проверяются в запросах на вытягивание так же, как и любой другой исходный файл, без флагов функций.
Так как выходной ZIP-путь включает ${{TEAMSFX_ENV}}, каждая среда создает артефакт с уникальным именем. Например, appPackage.prod.zip пишутся appPackage.prod-v2.zip независимо друг от ./appPackage/build/ друга и никогда не перезаписывают друг друга.
Автоматизация развертывания с помощью CI/CD
Чтобы масштабировать этот шаблон во всех средах, используйте матрицу в GitHub Actions или Azure DevOps для подготовки каждой среды из одного рабочего процесса:
strategy:
matrix:
include:
- target: dev
secret_name: AAD_SECRET_DEV
- target: staging
secret_name: AAD_SECRET_STAGING
- target: prod
secret_name: AAD_SECRET_PROD
- target: prod-v2
secret_name: AAD_SECRET_PROD_V2
steps:
- uses: actions/checkout@v4
- run: npm install -g @microsoft/m365agentstoolkit-cli
- run: atk provision --env ${{ matrix.target }}
env:
SECRET_AAD_CLIENT_SECRET: ${{ secrets[matrix.secret_name] }}
- run: atk deploy --env ${{ matrix.target }}
Каждое задание матрицы загружает правильный .env.* файл и извлекает свой секрет из явно сопоставленного секрета GitHub. Явное сопоставление необходимо, так как секретные имена GitHub допускают только прописные буквы, цифры и символы подчеркивания (например, конечное имя, подобное prod-v2 , нельзя использовать непосредственно как секретное имя). При такой конфигурации подготовка изменения в рабочей среде после прохождения промежуточного этапа становится триггером рабочего процесса, а не ручным этапом.
Предупреждение
Не храните секреты производства в .env.prod. Используйте .env.prod.user для локальной разработки и секретное хранилище CI/CD для запуска конвейера. Убедитесь, что .user файлы исключены .gitignore и никогда не сохраняются. Конвейер CI/CD должен внедрять SECRET_* переменные во время выполнения.
Соглашение об именовании
Используйте следующее соглашение об именовании файлов среды.
| Шаблон | Описание |
|---|---|
.env.<target> |
Клиент или этап: разработка, промежуточный процесс, рабочая среда |
.env.<target>-<variant> |
Версия или ветвь в целевом объекте: prod-v2, prod-experimental |
.env.<target>.user |
Секреты для этой цели, никогда не фиксированные |
.env.local |
Конфигурация набора средств агентов в корне проекта (автоматически генерируется во время подготовки) |
Это соглашение делает env/ папку самодокументируемой. Любой участник команды может определить, какие среды существуют и для чего предназначена каждая из них.
Преимущества этого подхода
Переход от одного манифеста на среду к одному репозиторию с большим количеством файлов среды меняет способ работы команды:
- Параллельные версии без дублирования кода: подготовьте версии 1 и 2 в одном рабочем клиенте для пилотных проектов реальных пользователей без создания разветвления базы кода.
-
Продвижение по службе одной командой: Пас
--env prod- это полный шаг по повышению. Никаких действий по редактированию файлов или объединению вручную не требуется. - Согласованный CI/CD в разных средах: единый рабочий процесс обрабатывает каждую среду с одинаковыми этапами, устраняя смещение конфигурации между разработкой и производством.
-
Упрощенная адаптация. Новый участник команды может начать работу, заполнив .
.env.dev.userНикаких изменений манифеста не требуется. -
Отслеживаемые среды: каждая среда содержит один файл источника истины. Сравнение того, что изменилось между
prodиprod-v2является diff двух файлов.
При этом целевые среды и версии агентов рассматриваются как цели развертывания, при этом используются одни и те же инструменты и соглашения.