Управление средами и версиями для декларативных агентов с помощью набора инструментов агентов Microsoft 365

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

Набор инструментов агентов 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 двух файлов.

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