Teams App Developer

MicrosoftOfficialPublished by Microsoft

Skill
Tool integration
Software development
MIT
Medium risk

From the author

Builds, tests, and deploys Microsoft 365 apps and agents for Teams and Copilot. Includes sub-skills for project creation, local testing, cloud deployment, troubleshooting, and Slack-to-Teams migration. USE FOR: Teams agent, bot, tab, message extension, Declarative Agents, Custom Engine Agents, local testing, Agents Playground, Azure resource provision, remote deployment, Slack to Teams migration, cross-platform bot development, Block Kit to Adaptive Cards conversion. DO NOT USE FOR: general web development, non-bot/non-Teams projects.

— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The teams-app-developer skill provides a structured framework for managing the lifecycle of Microsoft 365 agents and Teams applications. It leverages the ATK CLI to handle project scaffolding, local testing via the Agents Playground, cloud provisioning on Azure, and troubleshooting. The skill includes specialized guidance for migrating Slack bots to Teams, including converting Block Kit UI to Adaptive Cards, and provides access to an extensive library of micro-expert documentation for cross-platform development.

What it does

Scaffolds new Microsoft 365 agents and Teams applications from templates.
Facilitates local testing using the Agents Playground or Teams-specific environments.
Automates Azure resource provisioning and cloud deployment workflows.
Provides diagnostic procedures for common authentication and configuration errors.
Supports migration of Slack bots to the Teams platform.
Manages project configuration and environment variables for ATK-based projects.

When to use it

When starting a new Teams app, bot, or Declarative Agent project.
When you need to test an agent locally before deploying to the cloud.
When migrating existing Slack bots to the Microsoft Teams ecosystem.
When troubleshooting deployment or authentication issues in a Teams project.
When you need to provision Azure infrastructure for a Teams application.

Advantages

Streamlines the development lifecycle with standardized CLI commands.
Reduces development time by offering a local testing playground.
Provides expert-level guidance for complex cross-platform migrations.
Ensures consistent configuration management across development environments.
Includes robust error-handling protocols for common platform-specific pitfalls.

Usage examples

“Create a new Teams bot project using the default template.”: The agent will initialize a new project folder, configure the necessary YAML files, and guide you through the initial setup using the ATK CLI.
“How do I migrate my Slack bot to Microsoft Teams?”: The agent will initiate the slack-to-teams workflow, providing access to cross-platform bridging experts and guidance on converting UI components.
“My Teams bot is returning a 401 error, how do I fix it?”: The agent will trigger the troubleshooting workflow, checking your environment variables, tunnel status, and authentication configuration.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/microsoft/teams-app-developer/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip teams-app-developer.zip -d .agents/skills

Documentation by Microsoft

Microsoft 365 Agents Toolkit Skill

Build Microsoft 365 agents and Teams apps using the ATK CLI.

AI Behavior Guidelines

Testing Strategy: Recommend Agents Playground first (faster, no M365 needed). Use Teams workflow only if user explicitly requests it.
Environment Variables: NEVER hardcode secrets or make up placeholder values. Always ask users for real values.
Error Handling: Read error messages carefully. Check env/.env.local, .localConfigs, and atk auth list. Common pitfalls:
- AADSTS7000229 → aadApp/create missing generateServicePrincipal: true in YAML — add it and re-provision
- Missing TENANT_ID in .localConfigs → SDK uses wrong token authority → 401 from Bot Connector
- 401 persists after auth fix → devtunnel URL may be blacklisted — create a fresh tunnel
- See troubleshoot/troubleshoot.md for full diagnostic steps
Long-Running Commands — WAIT for completion:
- atk new, atk provision, atk deploy can take several minutes
- Always wait for completion before running the next step (timeout 120000ms+)
Local Service Startup — Hangs terminal (expected):
- npm run dev, npm start, python app.py, devtunnel host, etc. will hang — the process keeps running indefinitely
- ALWAYS run as a background process (isBackground=true) — NEVER use isBackground=false for these commands
- Do NOT wait for it to "finish" — verify startup by checking output for "listening on port" or tunnel URL
- If errors appear, read logs, diagnose, fix, restart
- Use a NEW terminal to launch Agents Playground or open Teams sideloading URL
Monitor App Logs: Periodically check background terminal output for runtime errors. If the app crashes, read the error, fix the root cause, and restart.
Telemetry Tagging: Before running any atk CLI commands, set the session environment variable so all CLI invocations are tagged as skill-initiated:
```
export ATK_CLI_SKILL=true
```
Run this once at the start of the session. All subsequent atk commands in the same terminal will inherit it.

ATK CLI Setup

atk --version  # Must be > 1.1.5-beta

If ATK is not found or version is too old:

npm i -g @microsoft/m365agentstoolkit-cli@beta

CLI Global Options

Option	Meaning	Recommendation
`-i`	Interactive mode	Always use `-i false` in automation to avoid hanging
`-f`	Project folder	Default to be current directory, used when specifying a custom folder. When scaffolding a new project, this is the parent folder where the project folder will be created under.
`-h`	Command help	Use `atk <command> -h` for quick syntax checks

Sub-Skills

Sub-Skill	When to Use	Reference
create-project	Scaffold new project from template, choose template, `atk new`	create-project/create-project.md
test-playground	Test locally with Agents Playground, `agentsplayground`, quick testing	test-playground/test-playground.md
test-teams	Run on Teams, devtunnel, sideload, Teams testing, test in Copilot	test-teams/test-teams.md
provision-deploy	Provision Azure resources, deploy to cloud, `atk provision`, `atk deploy`	provision-deploy/provision-deploy.md
troubleshoot	Fix errors, 401, port conflicts, YAML errors, stale bots	troubleshoot/troubleshoot.md
slack-to-teams	Migrate Slack bot to Teams, cross-platform bridging, Block Kit to Adaptive Cards	slack-to-teams/SKILL.md

MANDATORY: Before executing any workflow, read the corresponding sub-skill document.

Shared References

manifest-and-yaml.md — Project files, YAML config, env vars, .localConfigs flow
commands.md — ATK CLI commands: package, validate, share, collaborate
templates.md — Complete template catalog with language support
experts/ — 100+ micro-expert files: Teams SDK, Slack SDK, cross-platform bridging, deploy, AI models, security, language conversion
docs/ — Platform comparison guides: UI, messaging, identity, infrastructure, feature gaps

Workflow Chains

Match user intent to the smallest valid workflow.

User Intent	Workflow (read in order)
Build new app from scratch	create-project → test-playground
Test existing project locally	test-playground (recommended) or test-teams
Deploy to Azure	provision-deploy
Fix broken bot	troubleshoot → re-test
Migrate Slack bot to Teams	slack-to-teams

MANDATORY: Before executing any slack-to-teams workflow, read slack-to-teams/SKILL.md first. The sub-skill contains a routed expert system with 100+ micro-expert files for cross-platform bot development.

ATK Project Context Resolution

Resolve config values only when missing. If a value is already known in the session, reuse it.

Step 1: Detect ATK Project

If m365agentstoolkit*.yml exists in the current folder, treat it as an ATK project and parse configuration.

Step 2: Resolve Common Configuration

Resolve variables referenced in m365agentstoolkit*.yml. Common variables: AZURE_OPENAI_API_KEY AZURE_OPENAI_ENDPOINT AZURE_OPENAI_DEPLOYMENT_NAME

Step 3: Collect Missing Values

If required values are missing, ask the user for only the missing ones.

Refer to manifest-and-yaml.md for full config-file details.

Files

ATTRIBUTION.mdAdded by AutoGineer906 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md7.6 KiB
create-project/create-project.md8.1 KiB
docs/README.md2.8 KiB
docs/advanced-features.md7.0 KiB
docs/feature-gaps.md46.3 KiB
docs/files-and-links.md4.2 KiB
docs/identity-and-auth.md4.3 KiB
docs/infrastructure.md6.7 KiB
docs/interactive-responses.md4.4 KiB
docs/messaging-and-commands.md4.5 KiB
docs/middleware-and-handlers.md4.4 KiB
docs/ui-components.md6.9 KiB
docs/workflows.md14.4 KiB
experts/README.md8.6 KiB
experts/_expert-ts.md2.2 KiB
experts/analyzer.md14.0 KiB
experts/bridge/app-distribution-packaging-ts.md14.2 KiB
experts/bridge/channel-ops-graph-ts.md15.4 KiB
experts/bridge/commands-slash-text-ts.md18.5 KiB
experts/bridge/cross-platform-advisor-ts.md36.4 KiB
experts/bridge/cross-platform-architecture-ts.md8.3 KiB
experts/bridge/events-activities-ts.md22.4 KiB
experts/bridge/files-upload-download-ts.md17.2 KiB
experts/bridge/identity-oauth-bridge-ts.md19.8 KiB
experts/bridge/index.md13.0 KiB
experts/bridge/infra-compute-ts.md14.6 KiB
experts/bridge/infra-observability-ts.md14.0 KiB
experts/bridge/infra-secrets-config-ts.md13.2 KiB
experts/bridge/infra-storage-ts.md14.3 KiB
experts/bridge/interactive-responses-ts.md19.6 KiB
experts/bridge/link-unfurl-preview-ts.md17.1 KiB
experts/bridge/middleware-handlers-ts.md15.4 KiB
experts/bridge/python-cross-platform.md9.3 KiB
experts/bridge/rate-limiting-resilience-ts.md17.6 KiB
experts/bridge/rest-only-integration-ts.md8.4 KiB
experts/bridge/scheduling-deferred-send-ts.md17.8 KiB
experts/bridge/shortcuts-extensions-ts.md17.5 KiB
experts/bridge/transport-socketmode-https-ts.md14.3 KiB
experts/bridge/ui-app-home-personal-tab-ts.md14.5 KiB
experts/bridge/ui-block-kit-adaptive-cards-ts.md21.5 KiB
experts/bridge/ui-legacy-attachments-cards-ts.md11.2 KiB
experts/bridge/ui-modals-dialogs-ts.md21.4 KiB
experts/bridge/workflow.composable-platform-ts.md13.7 KiB
experts/bridge/workflows-automation-ts.md14.3 KiB
experts/builder.md11.1 KiB
experts/convert/bulk-conversion-strategy-ts.md12.8 KiB
experts/convert/dependency-mapping-ts.md8.3 KiB
experts/convert/index.md3.5 KiB
experts/convert/java-to-ts-ts.md20.6 KiB
experts/convert/js-to-ts-ts.md6.2 KiB
experts/convert/json-serialization-ts.md11.0 KiB
experts/convert/kotlin-to-ts-ts.md11.2 KiB
experts/convert/ruby-to-ts-ts.md9.7 KiB
experts/convert/type-mapping-ts.md10.1 KiB
experts/deploy/aws-bot-deploy-ts.md14.6 KiB
experts/deploy/aws-cli-reference-ts.md52.4 KiB
experts/deploy/azure-bot-deploy-ts.md15.4 KiB
experts/deploy/azure-cli-reference-ts.md16.9 KiB
experts/deploy/index.md4.6 KiB
experts/fallback.md2.1 KiB
experts/index.md18.9 KiB
experts/models/anthropic-ts.md7.8 KiB
experts/models/bedrock-ts.md9.9 KiB
experts/models/foundry-cloud-ts.md8.1 KiB
experts/models/foundry-local-ts.md10.6 KiB
experts/models/index.md5.8 KiB
experts/models/openai-azure-openai-ts.md8.3 KiB
experts/models/oss-openai-compatible-ts.md10.7 KiB
experts/models/transformers-js-ts.md11.6 KiB
experts/prompt-engineer.md14.7 KiB
experts/researcher.md2.8 KiB
experts/security/index.md1.2 KiB
experts/security/input-validation-ts.md13.8 KiB
experts/security/secrets-ts.md13.9 KiB
experts/slack/bolt-assistant-ts.md9.9 KiB
experts/slack/bolt-events-ts.md9.3 KiB
experts/slack/bolt-java.md8.9 KiB
experts/slack/bolt-oauth-distribution-ts.md10.9 KiB
experts/slack/bolt-python.md9.5 KiB
experts/slack/cli.app-management.md7.9 KiB
experts/slack/cli.datastore-env.md8.6 KiB
experts/slack/cli.getting-started.md8.0 KiB
experts/slack/cli.local-dev-deploy.md8.4 KiB
experts/slack/cli.manifest-triggers.md9.9 KiB
experts/slack/index.md8.9 KiB
experts/slack/runtime.ack-rules-ts.md9.8 KiB
experts/slack/runtime.bolt-foundations-ts.md10.7 KiB
experts/slack/runtime.shortcuts-ts.md11.0 KiB
experts/slack/runtime.slash-commands-ts.md11.6 KiB
experts/slack/runtime.socket-mode-ts.md9.5 KiB
experts/slack/ui.block-kit-ts.md11.5 KiB
experts/slack/ui.modals-lifecycle-ts.md13.3 KiB
experts/slack/web-api-proactive-ts.md11.0 KiB
experts/slack/workflow.slack-automations-ts.md10.2 KiB
experts/teams/a2a.client-basics-ts.md9.7 KiB
experts/teams/a2a.orchestrator-patterns-ts.md12.7 KiB
experts/teams/a2a.server-basics-ts.md11.4 KiB
experts/teams/ai.chatprompt-basics-ts.md8.1 KiB
experts/teams/ai.citations-feedback-ts.md6.9 KiB
experts/teams/ai.conversational-query-ts.md14.2 KiB
experts/teams/ai.function-calling-design-ts.md9.0 KiB
experts/teams/ai.function-calling-implementation-ts.md7.7 KiB
experts/teams/ai.memory-localmemory-ts.md7.3 KiB
experts/teams/ai.model-setup-ts.md6.6 KiB
experts/teams/ai.rag-retrieval-ts.md7.4 KiB
experts/teams/ai.rag-vectorstores-ts.md8.5 KiB
experts/teams/ai.streaming-ts.md6.9 KiB
experts/teams/auth.oauth-sso-ts.md10.1 KiB
experts/teams/compat.botbuilder-interop-ts.md14.6 KiB
experts/teams/dev.debug-test-ts.md14.1 KiB
experts/teams/graph.usergraph-appgraph-ts.md9.0 KiB
experts/teams/index.md9.8 KiB
experts/teams/mcp.client-basics-ts.md9.5 KiB
experts/teams/mcp.expose-chatprompt-tools-ts.md9.5 KiB
experts/teams/mcp.security-ts.md10.4 KiB
experts/teams/mcp.server-basics-ts.md9.9 KiB
experts/teams/project.scaffold-files-ts.md12.2 KiB
experts/teams/runtime.app-init-ts.md10.9 KiB
experts/teams/runtime.manifest-ts.md12.3 KiB
experts/teams/runtime.proactive-messaging-ts.md12.6 KiB
experts/teams/runtime.routing-handlers-ts.md12.3 KiB
experts/teams/state.storage-patterns-ts.md9.4 KiB
experts/teams/teams-dotnet.md8.2 KiB
experts/teams/teams-python.md8.3 KiB
experts/teams/ui.adaptive-cards-ts.md12.9 KiB
experts/teams/ui.dialogs-task-modules-ts.md15.1 KiB
experts/teams/ui.message-extensions-ts.md15.6 KiB
experts/teams/workflow.approvals-inline-ts.md12.4 KiB
experts/teams/workflow.message-native-records-ts.md10.6 KiB
experts/teams/workflow.sharepoint-lists-ts.md9.0 KiB
experts/teams/workflow.state-driven-events-ts.md12.2 KiB
experts/teams/workflow.triggers-compose-ts.md10.3 KiB
experts/update-experts.md10.0 KiB
provision-deploy/provision-deploy.md4.3 KiB
test-playground/playground-cli.md4.6 KiB
test-playground/playground.md4.5 KiB
test-playground/test-playground.md1.1 KiB
test-teams/test-teams.md4.9 KiB
toolkit/README.md4.2 KiB
toolkit/commands.md2.6 KiB
toolkit/environments.md12.6 KiB
toolkit/lifecycle-cli.md17.6 KiB
toolkit/manifest-and-yaml.md6.0 KiB
toolkit/playground.md7.6 KiB
toolkit/publish.md9.3 KiB
toolkit/templates.md6.7 KiB
troubleshoot/troubleshoot.md20.2 KiB

troubleshoot/troubleshoot.md

Troubleshooting

Consolidated troubleshooting for ATK projects — provisioning, runtime, Playground, and Teams issues.

Error Code Quick Reference

Error Code	Section
`Ext.FindProcessError`	Port already in use
`Ext.PortsConflictError`	Port already in use
`fileCreateOrUpdateEnvironmentFile.MissingEnvironmentVariablesError`	Missing environment variables at runtime
`botFrameworkCreate.MissingEnvironmentVariablesError`	Missing environment variables at runtime
`devToolInstall.TestToolInstallationError`	Agents Playground installation failed
`devToolInstall.FuncInstallationError`	Azure Functions Core Tools installation failed
`Ext.DebugTestToolFailedToStartError`	Playground won't start
`AppStudioPlugin.ManifestValidationFailed`	Manifest validation failed
`armDeploy.DeployArmError`	ARM deployment failed
`Ext.DevTunnelOperationError`	Dev tunnel operation failed

Common Provisioning Issues

Symptom	Cause	Fix
YAML schema validation error during `atk provision`	Wrong field names in `m365agents.yml` or `m365agents.local.yml`	Check field reference. Common: `outputJsonPath` → `outputFolder`, missing `description: ""` in `botFramework/create`
`teamsApp/validateManifest` fails with network error	Schema URL (`https://developer.microsoft.com/...`) unreachable	Remove `teamsApp/validateManifest` from local YAML, or retry with network access
`AADSTS7000229: missing service principal`	`aadApp/create` missing `generateServicePrincipal: true`	Add `generateServicePrincipal: true` to `aadApp/create` in YAML, re-provision — see Missing Service Principal
401 from Bot Connector (bot receives messages but can't reply)	`TENANT_ID` missing from `.localConfigs` → SDK uses wrong token authority	Copy `TENANT_ID` from `env/.env.local` to `.localConfigs` — see Missing TENANT_ID
Bot still gets 401 after fixing auth issues	Devtunnel URL blacklisted by Bot Framework due to repeated prior failures	Create a fresh devtunnel (`devtunnel delete` + `devtunnel create`), update `BOT_ENDPOINT`, re-provision — see Blacklisted Devtunnel URL
`Authorization: Bearer null` (401) at runtime	`clientId`/`clientSecret` not passed to Teams SDK `App` constructor	Pass credentials explicitly: `new App({ adapter: { credentials: { clientId, clientSecret, tenantId } } })`
401 after changing to single-tenant (`AzureADMyOrg`)	Tenant mismatch — SDK doesn't accept `api://botid-{appId}` audience	Add custom JWT middleware accepting all audience formats, or stay with `AzureADMultipleOrgs`
Stale bot after re-provisioning	Old AAD app still referenced by Bot Framework registration	Delete `env/.env.local` and `env/.env.local.user`, re-run `atk provision --env local -i false` + `atk deploy --env local -i false`
Bot works in Playground but not in Teams	Missing dev tunnel or wrong `BOT_ENDPOINT`	Start `devtunnel host -p 3978 --allow-anonymous`, set `BOT_ENDPOINT` in `env/.env.local` before provisioning
Manifest v1.25 validation fails with `"team"` scope	`supportsChannelFeatures` required at runtime but rejected by v1.25 schema	Use `"personal"` scope only in v1.25, or use devPreview schema that defines the property

YAML Schema Errors

Common field name mistakes in m365agents.local.yml:

outputJsonPath does not exist — use outputFolder in teamsApp/zipAppPackage
AAD_APP_OBJECT_ID — use BOT_OBJECT_ID in local YAML's aadApp/create writeToEnvironmentFile
Missing description: "" in botFramework/create — this field is required

See ../toolkit/manifest-and-yaml.md for the full field reference.

Known ATK Pitfalls

Pitfall	Symptom	Fix
`aadApp/create` missing `generateServicePrincipal: true`	`AADSTS7000229: missing service principal in tenant` when bot calls Bot Connector	Add `generateServicePrincipal: true` to `aadApp/create` in YAML, then re-provision
`TENANT_ID` not written to `.localConfigs`	SDK defaults to `botframework.com` tenant → 401 from Bot Connector (wrong issuer/tid in token)	Copy `TENANT_ID` from `env/.env.local` (where `aadApp/create` writes it) into `.localConfigs`
Devtunnel URL blacklisted after repeated 401s	Bot still gets 401 even after fixing auth — Bot Framework cached the tunnel URL as failing	Delete old tunnel, create a fresh one, update `BOT_ENDPOINT`, re-provision

Authorization / 401 Issues

Missing Service Principal (AADSTS7000229)

The aadApp/create action in m365agents.local.yml must include generateServicePrincipal: true to create the service principal (enterprise application) alongside the app registration. Without it, the client credentials grant fails:

AADSTS7000229: The client application <BOT_ID> is missing service principal in the tenant <TENANT_ID>

Fix — add generateServicePrincipal: true to your YAML:

  - uses: aadApp/create
    with:
      name: ${{CONFIG__MANIFEST__NAME}}-aad
      generateClientSecret: true
      generateServicePrincipal: true   # ← REQUIRED — without this, no SP is created
      signInAudience: AzureADMultipleOrgs
    writeToEnvironmentFile:
      clientId: BOT_ID
      clientSecret: SECRET_BOT_PASSWORD
      objectId: BOT_OBJECT_ID

Then re-provision:

atk provision --env local -i false

Manual fallback (if you can't re-provision): az ad sp create --id <BOT_ID>

Blacklisted Devtunnel URL

After repeated 401 failures (e.g., from a missing service principal), Bot Framework may blacklist the devtunnel URL. Even after fixing the auth issue, the bot continues to get 401.

Fix — create a fresh devtunnel:

devtunnel delete <old-tunnel-id>
devtunnel create --allow-anonymous
devtunnel port create -p 3978
devtunnel host

Update BOT_ENDPOINT in env/.env.local with the new tunnel URL, then re-provision:

atk provision --env local -i false
atk deploy --env local -i false

Missing TENANT_ID (wrong token authority → 401)

When TENANT_ID is not set in .localConfigs or environment, the Teams SDK (both Python and Node) may default to acquiring tokens from the shared botframework.com tenant (d6d49420-f39b-4df7-a1dc-d59a935871db) instead of your home tenant. The resulting token has:

Wrong iss (issuer) and tid (tenant) claims
No roles assigned

Bot Connector rejects this token with 401 Unauthorized.

Diagnose:

# Check if TENANT_ID is set
grep TENANT_ID .localConfigs
# Or in env file
grep TENANT_ID env/.env.local

Fix:

# Copy TENANT_ID from env file (aadApp/create writes it there, not to .localConfigs)
grep TENANT_ID env/.env.local
# Add the value to .localConfigs
echo TENANT_ID=<tenant-id-from-env-file> >> .localConfigs

This ensures the SDK uses https://login.microsoftonline.com/<your-tenant-id> instead of https://login.microsoftonline.com/botframework.com.

Python SDK note: TokenManager._resolve_tenant_id() falls back to botframework.com when TENANT_ID is unset. Always set it explicitly.

`Authorization: Bearer null`

The Teams SDK v2 App constructor requires explicit credentials. If clientId/clientSecret are not passed, the auth header will be Bearer null:

const app = new App({
  adapter: {
    credentials: {
      clientId: process.env.CLIENT_ID,
      clientSecret: process.env.CLIENT_SECRET,
      tenantId: process.env.TENANT_ID, // required for single-tenant
    },
  },
});

Ensure .localConfigs has CLIENT_ID and CLIENT_SECRET. Run atk deploy --env local -i false to regenerate.

401 with single-tenant bots (`AzureADMyOrg`)

If aadApp/create uses signInAudience: AzureADMyOrg, Bot Framework tokens have audience api://botid-{appId}. The Teams SDK v2 only validates {appId} and api://{appId} by default, causing 401 errors. Solutions:

Stay with AzureADMultipleOrgs (recommended for most scenarios)
Create custom auth middleware with skipAuth: true on the HttpPlugin, then manually validate JWT tokens accepting all three audience formats: {appId}, api://{appId}, api://botid-{appId}

Stale Bot Framework Registration

If you delete and re-create Azure AD apps, the Bot Framework registration may still reference the old app ID. Fix:

Delete env/.env.local and env/.env.local.user
Re-run atk provision --env local -i false
Re-run atk deploy --env local -i false
Re-sideload the Teams app

Playground Issues

Playground won't start

Error code: Ext.DebugTestToolFailedToStartError

Check if port 56150 is in use:

# Windows
netstat -ano | findstr :56150
# macOS / Linux
lsof -i :56150

The playground will automatically find an available port if 56150 is taken. If it still fails to start:

Check the output/terminal for error messages.
Ensure Agents Playground is installed correctly — see Agents Playground installation failed.
Try launching manually: ./devTools/playground/node_modules/.bin/agentsplayground start

Bot not responding in Playground

Verify bot is running on specified endpoint
Check bot logs for errors
Ensure your bot endpoint is accessible:
```
curl http://localhost:3978/api/messages
```

Teams Issues

Teams shows "app not available"

This usually means BOT_ENDPOINT requires HTTPS. Use Agents Playground instead, or ensure dev tunnel is running and BOT_ENDPOINT is properly configured.

App not loading

Verify M365_APP_ID (for declarative agents) or TEAMS_APP_ID (for bots/tabs) exists in env/.env.local.

Manifest validation failed

Error code: AppStudioPlugin.ManifestValidationFailed

The app manifest (appPackage/manifest.json) failed validation against the Teams schema.

Check the error details — the output lists which fields are invalid.
Common fixes:
- Missing required fields (e.g., description, version, icons).
- Invalid scope — e.g., "team" scope with supportsChannelFeatures on schema v1.25 (use "personal" only, or switch to devPreview schema).
- Schema URL mismatch — ensure $schema points to the correct manifest version.
Validate locally:
```
atk validate --env <env>
```
Re-build and re-provision after fixing:
```
atk provision --env local -i false
```

Runtime Issues

Port already in use

Error codes: Ext.FindProcessError, Ext.PortsConflictError

Common ports used by ATK projects: 3978 (bot), 9239 (Node debugger), 56150 (Agents Playground).

Find and release occupied ports:

# Check which ports are in use (replace PORT with 3978, 9239, 56150, etc.)
# Windows
netstat -ano | findstr :PORT
# macOS / Linux
lsof -i :PORT

# Kill the process occupying the port
# Windows (replace PID with the process ID from above)
taskkill /PID PID /F
# macOS / Linux
kill -9 PID

If the issue continues after releasing those three ports, inspect your bot logs and code for additional ports (e.g., custom API servers, function hosts on port 7071). Release them the same way.

Missing environment variables at runtime

Error codes: fileCreateOrUpdateEnvironmentFile.MissingEnvironmentVariablesError, botFrameworkCreate.MissingEnvironmentVariablesError

Check that environment config files exist and contain all required values:

For local debug: check .localConfigs
For Agents Playground debug: also check .localConfigs.playground

Run atk deploy --env local -i false (or --env playground for Playground) to regenerate.

If a specific variable is reported missing, locate it in the relevant config file. Either fill in the correct value or remove the variable reference from your YAML if it is not needed.

Agents Playground installation failed

Error code: devToolInstall.TestToolInstallationError

If automatic installation of Agents Playground fails, install it manually.

Option 1 — npm (recommended):

npm install -g @microsoft/m365agentsplayground

Option 2 — winget (Windows only):

winget install agentsplayground

Option 3 — script (Linux only):

curl -s https://raw.githubusercontent.com/OfficeDev/microsoft-365-agents-toolkit/dev/.github/scripts/install-agentsplayground-linux.sh | bash

If installation still fails, clear cached installation files and retry:

npm version cache: ~/.fx/bin/testTool/
Binary version cache: ~/.fx/bin/testToolBinary/

# Clear caches (adjust path separator for your OS)
rm -rf ~/.fx/bin/testTool
rm -rf ~/.fx/bin/testToolBinary

Then reinstall using one of the options above.

Verify installation structure (npm version):

A valid npm installation looks like:

~/.fx/bin/testTool/<version>/

where <version> is the npm version of @microsoft/m365agentsplayground, and the folder contains the installed package contents.

After installation, create a symlink under your project root:

# From your project root
ln -s ~/.fx/bin/testTool/<version> devTools/playground

Verify installation structure (binary version):

A valid binary installation looks like:

~/.fx/bin/testToolBinary/<version>/agentsplayground.exe

To install manually, download the release from: https://github.com/OfficeDev/microsoft-365-agents-toolkit/releases/tag/teams-app-test-tool%40<version> (e.g., teams-app-test-tool%400.2.25 for version 0.2.25).

Extract teamsapptester-win32-x64.zip and place the contents (including the .exe) into ~/.fx/bin/testToolBinary/<version>/.

If you encounter permission or OS-level errors (e.g., "access denied", "not recognized as executable"), try:

# Windows — unblock the downloaded file
powershell -Command "Unblock-File -Path '$HOME\.fx\bin\testToolBinary\<version>\agentsplayground.exe'"

# macOS / Linux — set executable permission
chmod +x ~/.fx/bin/testToolBinary/<version>/agentsplayground

If the issue persists, check your OS security settings and unblock the file manually.

Azure Functions Core Tools installation failed

Error code: devToolInstall.FuncInstallationError

The devTool/install action in m365agents.local.yml installs Azure Functions Core Tools. The version range is defined in your YAML, for example:

- uses: devTool/install
  with:
    func:
      version: ^4.0.5530
      symlinkDir: ./devTools/func
  writeToEnvironmentFile:
    funcPath: FUNC_PATH

Manual installation steps:

Check your required version range in m365agents.local.yml under devTool/install → func → version.

Install via npm:

npm install azure-functions-core-tools@<version> --prefix ~/.fx/bin/azfunc/<version> --no-audit

Replace <version> with a version matching your YAML range (e.g., 4.0.5530).

Create the sentinel file (marks the installation as valid):

touch ~/.fx/bin/azfunc/<version>/node_modules/azure-functions-core-tools/bin/func-sentinel

Create the project symlink:

# From your project root
ln -s ~/.fx/bin/azfunc/<version>/node_modules/azure-functions-core-tools/bin devTools/func

Verify the installation:
```
./devTools/func/func --version
```

If npm is not available, install it first (npm ships with Node.js). On Linux, the npm-based portable installation is not supported — install Azure Functions Core Tools via the system package manager instead (see Azure docs).

ARM deployment failed

Error code: armDeploy.DeployArmError

ARM deployment errors usually come from invalid Bicep templates or Azure resource configuration issues.

Check the deployment log — the error message includes the log file path (typically under .fx/ or the output pane). Open it and look for the first error entry.
Common causes and fixes:
- Invalid parameter or resource property: open the Bicep files under infra/ (e.g., azure.bicep, azure.parameters.json) and fix the flagged property.
- Resource name conflict: Azure resource names must be globally unique. Change the name in your Bicep parameters.
- Quota or region limitation: check if the target region supports the requested SKU or resource type.
- Missing role assignment: ensure the deploying identity has Contributor (or required) role on the target resource group.

Validate Bicep locally before re-deploying:

az bicep build --file infra/azure.bicep
az deployment group validate --resource-group <rg-name> --template-file infra/azure.bicep --parameters infra/azure.parameters.json

Re-deploy after fixing:
```
atk provision --env <env>
```

Dev tunnel operation failed

Error code: Ext.DevTunnelOperationError

This error occurs when a dev tunnel operation (create, delete, host, list) fails. Common causes:

Not logged in to dev tunnels:
```
devtunnel user login
```
Tunnel limit reached — free accounts have a limit on active tunnels. List and delete unused ones:
```
devtunnel list
devtunnel delete <tunnel-id>
```

Port already hosted by another tunnel session:

# Check if another devtunnel process is running
# Windows
tasklist | findstr devtunnel
# macOS / Linux
ps aux | grep devtunnel

# Kill stale sessions
# Windows
taskkill /IM devtunnel.exe /F
# macOS / Linux
killall devtunnel

Network or proxy issues — dev tunnels require outbound HTTPS. If behind a corporate proxy, configure it:
```
set HTTPS_PROXY=http://proxy:port   # Windows
export HTTPS_PROXY=http://proxy:port # macOS / Linux
```
Stale tunnel state — if the tunnel was deleted externally or is in a bad state, create a fresh one:
```
devtunnel create --allow-anonymous
devtunnel port create -p 3978
devtunnel host
```
Update BOT_ENDPOINT in env/.env.local with the new tunnel URL, then re-provision:
```
atk provision --env local -i false
atk deploy --env local -i false
```

See also Blacklisted Devtunnel URL if you continue to get 401 errors after fixing tunnel issues.

Diagnostics Commands

atk doctor              # Check ATK installation and dependencies
atk validate --env <env> # Validate project configuration
atk auth list           # Check logged-in accounts
agentsplayground --help # Playground CLI help
atk provision --help    # Provision help
atk deploy --help       # Deploy help

Expert Deep Dives

Applicability per row: lifecycle / environments rows apply to all ATK projects. The dev-debug, OAuth/SSO, and manifest rows apply only to code-based Teams bots/agents. Declarative-agent and API-plugin troubleshooting (Copilot recognition, instructions tuning, action invocation) is not covered by these experts — use the Microsoft 365 Copilot extensibility docs and the in-product Copilot developer mode logs.

Symptom area	Expert
YAML actions, `aadApp/create` options, `m365agents.yml` field reference (all projects)	../toolkit/lifecycle-cli.md
`.localConfigs` vs `env/.env.local`, `TENANT_ID` mapping, `SECRET_` files (all projects)	../toolkit/environments.md
DevTools plugin, sideloading URL, `skipAuth`, devtunnel debugging (Teams bots only)	../experts/teams/dev.debug-test-ts.md
401 / `Bearer null` / single-tenant audience issues, JWT validation (Teams bots only)	../experts/teams/auth.oauth-sso-ts.md
Manifest validation errors, scope/permission rejections (Teams bots / tabs / message extensions)	../experts/teams/runtime.manifest-ts.md

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an API key, Needs Python, Needs Node.js

Security

What our scanner noticed· Medium risk

Possible data-exfiltration endpoints
Instructions that use the network
Downloads piped into a shell

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

Microsoft

Publisher

Microsoft (Official)

Source

microsoft/skills · .github/plugins/microsoft-365-agents-toolkit/skills/teams-app-developer · commit 0696600

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by Microsoft.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download teams-app-developer.zip