fabioc-aloha M365 Declarative Agent Debugging Skill
Debug non-functional M365 Copilot declarative agents.
⚠️ Staleness Warning
M365 Copilot and Teams platform APIs are in rapid evolution. Schema versions, capabilities, and tooling change frequently. See EXTERNAL-API-REGISTRY.md for source URLs and recheck cadence.
Refresh triggers:
- New declarativeAgent schema versions
- M365 Agents Toolkit updates (formerly Teams Toolkit)
- New M365 Copilot capabilities
- Developer Portal changes
Last validated: February 2026 (Schema v1.6+, M365 Agents Toolkit with @m365agents chat participant)
Check current state: Declarative Agent Schema, M365 Agents Toolkit
Available MCP Tools
The M365 Agents Toolkit exposes MCP tools via the @m365agents chat participant. Use these before manual debugging:
| Tool | When to Use |
|---|---|
mcp_m365agentstoo_get_schema |
Validate manifest structure — get the current app manifest (v1.19), declarative agent (v1.0), or API plugin (v2.1) schema |
mcp_m365agentstoo_troubleshoot |
Diagnose common issues — schema validation failures, sideloading errors, conditional access blocks |
mcp_m365agentstoo_get_knowledge |
Look up M365 Copilot development knowledge — capabilities, limits, best practices |
mcp_m365agentstoo_get_code_snippets |
Find working examples — Teams AI, Teams JS, botbuilder code samples |
Workflow integration: Always try mcp_m365agentstoo_troubleshoot first when a user reports an M365 agent issue. Use mcp_m365agentstoo_get_schema to verify manifest structure before manual schema checks.
Schema Version Validation
Critical: Schema versions and their capabilities:
| Version | Status | Key Additions |
|---|---|---|
| v1.0 | Original baseline | Core capabilities |
| v1.2 | Stable | WebSearch sites, GraphicArt, CodeInterpreter |
| v1.5 | Extended | TeamsMessages, Email, People |
| v1.6 | LATEST | Dataverse, Meetings, EmbeddedKnowledge, worker_agents |
v1.3 and v1.4 DO NOT EXIST — unrecognized schema makes entire document invalid.
Capability Compatibility
| Capability | v1.2 | v1.5 | v1.6 |
|---|---|---|---|
| OneDriveAndSharePoint | ✅ | ✅ | ✅ |
| WebSearch | ✅ | ✅ | ✅ |
| GraphicArt | ✅ | ✅ | ✅ |
| CodeInterpreter | ✅ | ✅ | ✅ |
| GraphConnectors | ✅ | ✅ | ✅ |
| TeamsMessages | ❌ | ✅ | ✅ |
| ❌ | ✅ | ✅ | |
| People | ❌ | ✅ | ✅ |
| Meetings | ❌ | ❌ | ✅ |
| Dataverse | ❌ | ❌ | ✅ |
| EmbeddedKnowledge | ❌ | ❌ | ✅ (not yet available) |
| ScenarioModels | ❌ | ❌ | ✅ |
Lesson: v1.5/v1.6 capabilities with v1.2 schema = silent failure.
Manifest Limits (v1.6)
| Property | Limit |
|---|---|
name |
100 characters |
description |
1,000 characters |
instructions |
8,000 characters |
conversation_starters |
6 items max (was 12 in v1.2) |
actions |
1-10 items |
WebSearch.sites |
4 items |
TeamsMessages.urls |
5 items |
Meetings.items_by_id |
5 items |
Icon Requirements
color.png: 192×192px, solid background, logo in center 120×120 safe zone
outline.png: 32×32px, white only (#FFFFFF), transparent background (Alpha=0)
Common error:
Error: Outline icon is not transparent. Alpha,R,G,B: 255,X,X,X
Alpha=255 means opaque. Background pixels must be Alpha=0.
Debugging Workflow
MCP first: Call
mcp_m365agentstoo_troubleshootwith the error message or symptom — this often resolves the issue immediatelySchema check: Call
mcp_m365agentstoo_get_schemawith the relevant schema type (app_manifest,declarative_agent_manifest,api_plugin_manifest) to verify structureValidate package:
teamsapp validate --package-file <zip>(must pass all checks)Use
@m365agentschat participant: Ask@m365agentsin VS Code Copilot Chat for interactive troubleshooting — it has scaffolding, schema help, and guided debuggingManual schema check (fallback):
- ✅
.../declarative-agent/v1.2/schema.json - ❌
.../declarative-agent/v1.3/schema.json(doesn't exist)
- ✅
Verify capabilities match schema version
Test icon transparency:
Add-Type -AssemblyName System.Drawing
$bmp = New-Object System.Drawing.Bitmap("outline.png")
$pixel = $bmp.GetPixel(0, 0)
$bmp.Dispose()
"Alpha: $($pixel.A)" # Should be 0
Package Checklist
-
manifest.json— Teams app manifest (v1.19) -
declarativeAgent.json— Agent config (v1.2) -
color.png— 192×192 solid -
outline.png— 32×32 white on transparent
Symptom → Cause
| Symptom | Likely Cause | MCP Tool |
|---|---|---|
| Agent not responding | Invalid schema version | mcp_m365agentstoo_troubleshoot |
| Only 1 conversation starter | Schema validation failed | mcp_m365agentstoo_get_schema |
| Validation errors on icon | Wrong transparency/size | — (manual check) |
| Capability not working | Schema version mismatch | mcp_m365agentstoo_get_knowledge |
| Sideloading fails | Admin policy or manifest error | mcp_m365agentstoo_troubleshoot |
Memory via OneDrive
Agent reads from OneDrive using OneDriveAndSharePoint capability:
- User creates
Alex-Memory/folder in OneDrive - User shares folder link in chat
- Agent reads cognitive files from shared folder
- For writes: Alex generates content → user pastes
Benefits: No Azure Functions, no API costs, user controls data.
Deployment Flow
npx teamsapp package --env local
npx teamsapp validate --package-file appPackage/build/*.zip
# Upload to Developer Portal → Preview in Teams