Manifest and YAML Action Reference
Reference for appPackage/ files (manifest, declarative agent definition) and the field-by-field reference for m365agents.yml actions.
For environment files, ${{VAR}} resolution, .localConfigs flow, and the env-var catalog, see environments.md.
For the lifecycle YAML structure (provision/deploy/publish stages, action ordering, full anatomy), see lifecycle-cli.md.
Contents
- Key Project Files
- Schema Versions Used by Templates
- YAML Action Field Reference (Common Mistakes)
- signInAudience and Tenant Configuration
- Azure OpenAI Configuration
Key Project Files
| File | Purpose |
|---|---|
appPackage/manifest.json |
App metadata and capabilities (used by all capabilities) |
appPackage/declarativeAgent.json |
Agent instructions, conversation starters (Declarative Agents only) |
appPackage/color.png / outline.png |
Required icons (192x192 color, 32x32 outline with transparency) |
env/.env.{name} / .env.{name}.user |
Environment variables — see environments.md |
.localConfigs |
Runtime config generated by atk deploy --env local — see environments.md |
m365agents.yml |
Lifecycle config for dev/cloud — see lifecycle-cli.md |
m365agents.local.yml |
Lifecycle config for local development |
m365agents.playground.yml |
Lifecycle config for Agents Playground |
.m365agentsplayground.yml |
Optional Playground UI config — see playground.md |
Schema Versions Used by Templates
These are the canonical versions written by the current atk new templates (verified against templates/** in this repo). Use these in any hand-authored or hand-edited file unless you have a specific reason to pin an older one.
| File | Field | Value |
|---|---|---|
appPackage/manifest.json |
$schema |
https://developer.microsoft.com/en-us/json-schemas/teams/v1.26/MicrosoftTeams.schema.json |
appPackage/manifest.json |
manifestVersion |
1.26 |
appPackage/declarativeAgent.json |
$schema |
https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.7/schema.json |
appPackage/declarativeAgent.json |
version |
v1.7 |
m365agents.yml / m365agents.local.yml / m365agents.playground.yml |
version |
v1.11 (TS/Python templates) — some C# templates still ship v1.9 |
Notes:
- The Teams
manifestVersion: 1.26schema is also offered asvDevPreview(3 templates use it for early-access features). Stick with1.26unless a feature you need only exists invDevPreview. - The
declarativeAgent.jsonversionfield is the schema version (e.g.,"v1.7"), not your app version. The app version still lives inmanifest.json's top-levelversionfield.
// appPackage/declarativeAgent.json — minimal v1.7 example
{
"$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.7/schema.json",
"version": "v1.7",
"name": "My Agent",
"description": "Helps with X",
"instructions": "You are a helpful assistant that..."
}YAML Action Field Reference (Common Mistakes)
These field names are verified against official ATK templates. Wrong field names cause silent provisioning failures.
| Action | Correct Fields | Common Mistake |
|---|---|---|
teamsApp/zipAppPackage |
manifestPath, outputZipPath, outputFolder |
Using outputJsonPath (does not exist — use outputFolder) |
aadApp/create |
name, generateClientSecret, generateServicePrincipal, signInAudience |
Must include generateServicePrincipal: true — without it, no service principal is created and bot gets AADSTS7000229 |
aadApp/create writeToEnvironmentFile |
clientId, clientSecret, objectId → BOT_OBJECT_ID |
Writing objectId to AAD_APP_OBJECT_ID (wrong — use BOT_OBJECT_ID in local templates) |
botFramework/create |
botId, name, messagingEndpoint, channels; optional: description |
Only messagingEndpoint is strictly required by the driver; description defaults to "" if omitted. Templates ship description: "" explicitly for clarity. |
botAadApp/create |
name |
Only available in cloud (m365agents.yml), not used in local templates |
teamsApp/extendToM365 |
appPackagePath |
Required for declarative agents to surface in M365 Copilot — writes M365_APP_ID to env file |
signInAudience and Tenant Configuration
The aadApp/create action's signInAudience controls which tenants can authenticate:
| signInAudience | Use When | Bot Framework Behavior |
|---|---|---|
AzureADMultipleOrgs |
Multi-tenant bots (default in templates) | Bot tokens use audience {appId} or api://{appId} |
AzureADMyOrg |
Single-tenant bots | Bot tokens use audience api://botid-{appId} — requires custom JWT validation |
Single-tenant gotcha: If you change signInAudience to AzureADMyOrg, the Bot Framework sends tokens with audience api://botid-{appId}. The Teams SDK v2 (@microsoft/teams.apps) only validates {appId} and api://{appId} by default, causing 401 errors. Workaround: create a custom HttpPlugin with skipAuth: true and add manual JWT validation that also accepts api://botid-{appId}.
Azure OpenAI Configuration
For custom engine agents using Azure OpenAI, add these env vars to the YAML's file/createOrUpdateEnvironmentFile action:
# Add to m365agents.local.yml or m365agents.playground.yml
- uses: file/createOrUpdateEnvironmentFile
with:
target: ./.localConfigs
envs:
AZURE_OPENAI_API_KEY: ${{SECRET_AZURE_OPENAI_API_KEY}}
AZURE_OPENAI_ENDPOINT: ${{AZURE_OPENAI_ENDPOINT}}
AZURE_OPENAI_DEPLOYMENT_NAME: ${{AZURE_OPENAI_DEPLOYMENT_NAME}}Then set values in env/.env.local:
SECRET_AZURE_OPENAI_API_KEY=your-api-key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4oAfter updating the YAML, run atk deploy --env local -i false to write values to .localConfigs.