선언적 에이전트가 발전함에 따라 개발, 준비, 프로덕션 등 여러 환경에 프로비전하고 궁극적으로 병렬 버전을 실행하여 기존 사용자를 방해하지 않고 새로운 기능을 시험할 수 있어야 합니다. 모든 환경 및 버전 조합에 대해 별도의 매니페스트 파일 집합을 유지 관리하는 것은 크기 조정되지 않습니다.
Microsoft 365 에이전트 도구 키트는 동일한 메커니즘인 환경 파일을 사용하여 요구 사항, 대상 환경 및 에이전트 버전을 모두 해결합니다. 대상당 하나의 .env.* 파일을 정의하고 매니페스트, 선언적 에이전트 파일 전체m365agents.yml에서 자리 표시자를 사용하면 ${{VAR_NAME}} 단일 파일을 복제하지 않고 단일 명령atk provision --env <target>으로 모든 환경 또는 버전을 프로비전할 수 있습니다.
팁
권장: 지원되는 프로 코드 선언적 에이전트 및 플러그인 시나리오에 대한 Work IQ Dev 도구 로 시작하십시오. WIQD 빠른 시작을 참조하세요. 도구 키트 기반 지침은 이를 필요로 하는 기존 프로젝트 및 워크플로에 계속 사용할 수 있습니다. 도구를 선택하기 전에 기능 및 대상 환경 지원을 확인하세요. WIQD는 사용자 지정 엔진 에이전트를 대상으로 하지 않습니다.
두 개의 축, 하나의 시스템
선언적 에이전트에 대한 환경 관리에는 두 가지 차원이 있습니다.
- 대상 환경: 동일한 에이전트가 다른 테넌트 또는 앱 등록(개발, 준비, 프로덕션 또는 고객별 테넌트)에 프로비저닝됩니다.
- 에이전트 버전: 병렬로 실행되는 동일한 에이전트의 여러 변형(예: v1 안정, v2 미리 보기 또는 실험적 분기).
두 차원 모두 동일한 방식으로 처리됩니다. 각 대상에 대한 환경 파일과 ${{VAR_NAME}} 매니페스트, 선언적 에이전트 파일 및 m365agents.yml 프로비저닝 시 resolve의 자리 표시자를 정의합니다.
대상 환경 모델링
대부분의 팀은 개발 및 프로덕션 등 두 개 이상의 환경에 프로비전하며, 많은 팀이 이 환경 사이에 준비 환경을 추가합니다. 폴더의 환경당 파일 하나를 만듭니다.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 온보딩 버디(스테이징)"를 사용하면 테스터가 사용 중인 버전을 즉시 명확히 알 수 있으므로 문제를 보고할 때 혼동을 방지할 수 있습니다.
다른 환경을 대상으로 지정하려면 다음 각 에이전트 도구 키트 명령에 플래그를 --env 전달합니다.
atk provision --env staging
atk deploy --env staging
atk publish --env staging
여러 버전 모델링
에이전트 버전은 대상 환경과 동일한 패턴을 따릅니다. 각 버전은 자체 환경 파일이 있는 배포 대상입니다. 동일한 프로덕션 테넌트에 버전 1(v1) 에이전트와 함께 버전 2(v2) 에이전트를 배포하려면 환경을 추가합니다 prod-v2 .
env/
├── .env.dev
├── .env.staging
├── .env.prod # v1, the stable one
├── .env.prod-v2 # v2, running side by side
└── ...corresponding .user files
두 에이전트가 동일한 테넌트에 공존할 수 있도록 고유한 Teams 앱 ID를 제공합니다 .env.prod-v2 .
# 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"
}
]
}
}
그 결과 동일한 테넌트에서 두 개의 고유한 앱을 생성하는 하나의 매니페스트 파일이 생성됩니다. 미리 보기에 대한 액세스 권한이 부여된 사용자는 v2; 다른 모든 사용자는 계속해서 v1을 사용합니다.
참고
Teams 앱 ID는 이 패턴의 핵심입니다. 플랫폼은 ID가 다른 앱을 공유하는 코드의 양에 관계없이 별도의 앱으로 취급합니다. 또한 이러한 분리를 통해 프로덕션 사용자에게 영향을 주지 않고 에이전트 가상 사용자의 A/B 테스트가 가능합니다.
에이전트 정의 자체 분기
버전 차이가 가변 값(예: 다른 명령, 새로운 기능 또는 다른 플러그인 세트)을 넘어 확장되는 경우 에이전트 정의 자체를 분기하는 두 가지 옵션이 있습니다.
옵션 A: 단일을 declarativeAgent.json 유지하고 다른 값에 변수를 사용합니다. 이 접근 방식은 다른 지침 단락 또는 다른 SharePoint 사이트 URL과 같이 차이점이 사소한 경우에 효과적입니다.
옵션 B: 버전별로 별도의 선언적 에이전트 파일을 유지 관리하고 Teams 앱 매니페스트의 변수를 통해 참조합니다.
{
"copilotAgents": {
"declarativeAgents": [
{
"id": "declarativeAgent",
"file": "declarativeAgent.${{AGENT_VARIANT}}.json"
}
]
}
}
에서 m365agents.yml각 환경에서 고유한 zip 파일을 생성하도록 출력 아티팩트 이름에 포함 ${{TEAMSFX_ENV}} 하도록 패키지 단계를 구성합니다.
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. 로컬 개발에 사용하고 파이프라인 실행을 위해 CI/CD 비밀 저장소에 사용합니다 .env.prod.user . 파일이 제외 .gitignore 되고 커밋되지 않았는지 확인합니다.user. CI/CD 파이프라인은 런타임에 변수를 삽입 SECRET_* 해야 합니다.
명명 규칙
환경 파일에 대해 다음 명명 규칙을 사용합니다.
| 패턴 | 설명 |
|---|---|
.env.<target> |
테넌트 또는 스테이지: dev, staging, prod |
.env.<target>-<variant> |
대상 내의 버전 또는 분기: prod-v2, prod-experimental |
.env.<target>.user |
해당 대상에 대한 비밀, 커밋되지 않음 |
.env.local |
프로젝트 루트의 에이전트 도구 키트 구성(프로비전 중 자동 생성됨) |
이 규칙은 폴더를 env/ 자체 문서화합니다. 모든 팀 구성원은 현재 어떤 환경이 존재하는지, 각 환경이 무엇을 대상으로 하는지 결정할 수 있습니다.
이 방법의 이점
환경당 하나의 매니페스트에서 많은 환경 파일이 있는 하나의 리포지토리로 이동하면 팀 운영 방식이 변경됩니다.
- 코드 중복이 없는 병렬 버전: 코드베이스를 포크하지 않고 실제 사용자 파일럿을 위해 v1 및 v2를 동일한 프로덕션 테넌트에 프로비전합니다.
-
단일 명령어 승격: 통과
--env prod는 완전한 승격 단계입니다. 파일 편집이나 수동 병합 단계가 필요하지 않습니다. - 환경 전반에 걸쳐 일관된 CI/CD: 단일 워크플로우가 동일한 단계로 모든 환경을 처리하므로 개발과 프로덕션 간의 구성 드리프트가 제거됩니다.
-
간소화된 온보딩: 새 팀 구성원
.env.dev.user은 . 매니페스트 변경이 필요하지 않습니다. -
감사 가능한 환경: 각 환경에는 단일 소스 파일이 있습니다. 두 파일의 diff 간에 변경된
prod내용을 비교합니다prod-v2.
이 접근 방식은 전체적으로 동일한 도구와 규칙을 사용하여 대상 환경과 에이전트 버전을 모두 배포 대상으로 처리합니다.