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, <code v-pre>${{VAR}}</code> 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.26 schema is also offered as vDevPreview (3 templates use it for early-access features). Stick with 1.26 unless a feature you need only exists in vDevPreview.
• The declarativeAgent.json version field is the schema version (e.g., "v1.7"), not your app version. The app version still lives in manifest.json's top-level version field.

// 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-4o

After updating the YAML, run atk deploy --env local -i false to write values to .localConfigs.