diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 7a08605..7fe6840 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -20,7 +20,7 @@ { "name": "microsoft-365-agents-toolkit", "description": "Toolkit for building and evaluating Microsoft 365 Copilot declarative agents \u2014 scaffolding, JSON manifest development, capability configuration, and eval workflows.", - "version": "1.3.1", + "version": "1.5.0", "source": "./plugins/microsoft-365-agents-toolkit" }, { diff --git a/marketplace.json b/marketplace.json index 91286fa..a8ce8ba 100644 --- a/marketplace.json +++ b/marketplace.json @@ -21,7 +21,7 @@ "name": "microsoft-365-agents-toolkit", "source": "./plugins/microsoft-365-agents-toolkit", "description": "Toolkit for building and evaluating Microsoft 365 Copilot declarative agents \u2014 scaffolding, JSON manifest development, capability configuration, and eval workflows.", - "version": "1.3.1" + "version": "1.5.0" }, { "name": "workiq-productivity", diff --git a/plugins/microsoft-365-agents-toolkit/.claude-plugin/plugin.json b/plugins/microsoft-365-agents-toolkit/.claude-plugin/plugin.json index e102d1a..4d278fa 100644 --- a/plugins/microsoft-365-agents-toolkit/.claude-plugin/plugin.json +++ b/plugins/microsoft-365-agents-toolkit/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "microsoft-365-agents-toolkit", - "version": "1.3.1", + "version": "1.5.0", "description": "Toolkit for building and evaluating Microsoft 365 Copilot declarative agents \u2014 scaffolding, JSON manifest development, capability configuration, and eval workflows.", "skills": "./skills/" } \ No newline at end of file diff --git a/plugins/microsoft-365-agents-toolkit/.codex-plugin/plugin.json b/plugins/microsoft-365-agents-toolkit/.codex-plugin/plugin.json index e102d1a..4d278fa 100644 --- a/plugins/microsoft-365-agents-toolkit/.codex-plugin/plugin.json +++ b/plugins/microsoft-365-agents-toolkit/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "microsoft-365-agents-toolkit", - "version": "1.3.1", + "version": "1.5.0", "description": "Toolkit for building and evaluating Microsoft 365 Copilot declarative agents \u2014 scaffolding, JSON manifest development, capability configuration, and eval workflows.", "skills": "./skills/" } \ No newline at end of file diff --git a/plugins/microsoft-365-agents-toolkit/.github/plugin/plugin.json b/plugins/microsoft-365-agents-toolkit/.github/plugin/plugin.json index e102d1a..4d278fa 100644 --- a/plugins/microsoft-365-agents-toolkit/.github/plugin/plugin.json +++ b/plugins/microsoft-365-agents-toolkit/.github/plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "microsoft-365-agents-toolkit", - "version": "1.3.1", + "version": "1.5.0", "description": "Toolkit for building and evaluating Microsoft 365 Copilot declarative agents \u2014 scaffolding, JSON manifest development, capability configuration, and eval workflows.", "skills": "./skills/" } \ No newline at end of file diff --git a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/SKILL.md b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/SKILL.md index a974c33..f55b7c1 100644 --- a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/SKILL.md +++ b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/SKILL.md @@ -10,6 +10,8 @@ description: > "configure my agent", "deploy my agent", "fix my agent manifest", "edit my agent", "localize my agent", "add localization", "translate my agent", "multi-language agent", "add an API plugin", "add an MCP plugin", "add OAuth to my plugin", + "add email actions to agent", "add meeting actions to agent", + "add editorial answers to agent", "set agent response mode", "review instructions", "improve instructions", "fix my instructions" --- @@ -67,7 +69,7 @@ When you encounter ANY problem (missing files, malformed JSON, validation errors - Missing `declarativeAgent.json` → Detect (file not found) → Inform ("no manifest found") → Ask ("would you like to create a new agent?") - Malformed JSON → Detect (parse errors) → Inform (list specific syntax issues) → Ask ("should I fix these syntax errors?") - Validation errors → Detect (parse and check manifest) → Inform (list all errors) → Ask ("how would you like to fix these?") -- Version incompatibility → Detect (feature requires newer version) → Inform ("this feature requires v1.6, your agent is v1.4") → Ask ("should I upgrade?") +- Version incompatibility → Detect (feature requires newer version) → Inform ("this feature requires v1.8, your agent is v1.7") → Ask ("should I upgrade?") --- @@ -80,6 +82,10 @@ When you encounter ANY problem (missing files, malformed JSON, validation errors | Adding an API plugin | [API Plugins](references/api-plugins.md) | | Adding an MCP server | [MCP Plugin](references/mcp-plugin.md) | | Adding OAuth to an MCP or API plugin | [Authentication](references/authentication.md) | +| Adding email write operations (`EmailActions`) | [Editing Workflow](references/editing-workflow.md) | +| Adding meeting or calendar write operations (`MeetingActions`) | [Editing Workflow](references/editing-workflow.md) | +| Adding predefined semantic Q&A (`editorial_answers`) | [Editing Workflow](references/editing-workflow.md) | +| Choosing the default response mode | [Conversation Design](references/conversation-design.md) | | Reviewing or improving existing agent instructions | [Instruction Review](references/instruction-review.md) | | User reports agent gives generic/wrong answers | [Instruction Review](references/instruction-review.md) | | Localizing an agent into multiple languages | [Localization](references/localization.md) | @@ -88,6 +94,21 @@ When you encounter ANY problem (missing files, malformed JSON, validation errors --- +## Build-Time Feature Discovery + +When creating or designing an agent, actively evaluate these features instead of waiting for the user to name their manifest identifiers: + +| Requirement signal | Feature to surface | +|--------------------|--------------------| +| Send, archive, flag, move, delete, or organize email; manage rules, auto-replies, or folders | `EmailActions` | +| Schedule meetings, create calendar events or time-finding polls, or provide time insights | `MeetingActions` | +| Return approved, stable answers for semantically similar FAQ-style questions | `editorial_answers` | +| Prefer fast replies or deeper reasoning by default | `behavior_overrides.default_response_mode` | + +Surface only relevant options during requirements discovery. Do not add them without clear user intent. For write capabilities, distinguish them from the read-only `Email` and `Meetings` capabilities and include confirmation guidance for sensitive operations. + +--- + ## ATK CLI Setup Before running any ATK commands, check if the ATK CLI is available by running `npx -y --package @microsoft/m365agentstoolkit-cli atk --version`. If not found, **STOP and tell the user** — do NOT attempt to install it yourself. @@ -133,7 +154,9 @@ Then read `M365_TITLE_ID` from `env/.env.local` and **ALWAYS** present the revie Before adding ANY feature, read the `version` field in `declarativeAgent.json` and check the [Schema](references/schema.md) feature matrix. If the feature isn't supported in that version, **refuse** and offer to upgrade. Key version gates: -- `sensitivity_label`, `worker_agents`, `EmbeddedKnowledge` → **v1.6 only** +- `EmailActions`, `MeetingActions` → **v1.8+** +- `editorial_answers`, `behavior_overrides.default_response_mode`, `conversation_starters[].depends_on` → **v1.7+** +- `sensitivity_label`, `worker_agents`, `EmbeddedKnowledge`, `user_overrides` → **v1.6+** - `Meetings` → **v1.5+** - `ScenarioModels`, `behavior_overrides`, `disclaimer` → **v1.4+** - `Dataverse`, `TeamsMessages`, `Email`, `People` → **v1.3+** diff --git a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/api-plugins.md b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/api-plugins.md index 6f25dc3..6d4410c 100644 --- a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/api-plugins.md +++ b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/api-plugins.md @@ -693,7 +693,7 @@ Reference the API plugin in your `declarativeAgent.json`: ```json { - "version": "v1.6", + "version": "v1.8", "name": "Repairs Agent", "description": "An agent to manage repair tickets", "instructions": "You help users manage repair tickets. Use the repairs API to search, create, update, and delete repairs.", diff --git a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/best-practices.md b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/best-practices.md index 9f662a7..ce285ac 100644 --- a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/best-practices.md +++ b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/best-practices.md @@ -10,6 +10,7 @@ Follow these best practices for successful M365 Copilot agent development. - **PII Handling:** Follow data protection regulations when handling personal information - **Audit Logging:** Implement comprehensive audit trails for all agent actions - **Secret Storage:** Never hardcode credentials; use Azure Key Vault or environment variables +- **Write Capability Confirmation:** Require clear user confirmation before sensitive `EmailActions` or `MeetingActions`, such as sending or deleting email and creating or changing calendar events ## Performance @@ -18,6 +19,7 @@ Follow these best practices for successful M365 Copilot agent development. - **Caching Strategy:** Implement appropriate caching for frequently accessed data - **Response Time:** Keep operations under 30 seconds to avoid timeouts - **Batch Operations:** Use batch APIs when processing multiple items +- **Response Mode Selection:** Use `Quick response` for latency-sensitive agents, `Think deeper` for complex analytical agents, and `Auto` for mixed workloads ## Error Handling @@ -30,6 +32,8 @@ Follow these best practices for successful M365 Copilot agent development. ## Testing - **Test All Conversation Starters:** Verify each starter works as intended +- **Test Write Actions:** Verify confirmation, permissions, cancellation, and failure behavior for `EmailActions` and `MeetingActions` +- **Test Editorial Matching:** Check close paraphrases and unrelated questions against every `editorial_answers` entry - **Test Edge Cases:** Test with missing data, invalid inputs, and error conditions - **Security Testing:** Verify scoping and permission controls - **Cross-Environment Testing:** Test in dev, staging, and production environments @@ -50,6 +54,7 @@ Follow these best practices for successful M365 Copilot agent development. - **Code Organization:** Separate concerns (capabilities, API plugins, models) - **Version Control:** Use semantic versioning for shared agents - **Change Management:** Document changes and maintain changelog +- **Editorial Answer Governance:** Assign an owner and review cadence for approved answers so stale canonical content is removed promptly ## Conversation Design diff --git a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/conversation-design.md b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/conversation-design.md index fb06599..52bfc78 100644 --- a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/conversation-design.md +++ b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/conversation-design.md @@ -108,12 +108,14 @@ Describe the purpose and context for each data source the agent can use. You don - **Copilot connector knowledge**: Reference by connector name — "Use `ServiceNow KB` for help articles." - **SharePoint/OneDrive**: Describe the data source — "Search internal HR policy documents" or "Reference company documents in SharePoint." - **Email**: Describe the scenario — "Check user emails for relevant information." +- **Email actions**: Describe when to send, archive, flag, move, delete, or organize email, and require confirmation before sensitive writes. - **Teams messages**: "Search Teams channels and chat messages." (messages only — NOT transcripts) - **Meetings**: "Check calendar events, attendees, and meeting transcripts." (transcripts come from `Meetings`, not `TeamsMessages`) +- **Meeting actions**: Describe when to schedule or change calendar events, create time-finding polls, or surface time insights, and require confirmation before calendar writes. - **Code interpreter**: "Use code interpreter to generate charts." - **People knowledge**: "Look up people in the organization for contact info." -> **Common mistake:** Assuming meeting transcripts are part of `TeamsMessages`. Transcripts are retrieved through the `Meetings` capability. `TeamsMessages` covers channel posts, DMs, and meeting chat messages only. See the [Capability Reference](instruction-review.md#capability-reference-v16) for the full mapping. +> **Common mistake:** Assuming meeting transcripts are part of `TeamsMessages`. Transcripts are retrieved through the `Meetings` capability. `TeamsMessages` covers channel posts, DMs, and meeting chat messages only. See the [Capability Reference](instruction-review.md#capability-reference-v18) for the full mapping. ### 8. Provide Examples @@ -163,6 +165,54 @@ Developing instructions is an iterative process: --- +## Manifest-Level Experience Controls + +Evaluate these options while designing a new agent; they are easy to miss if discovery focuses only on knowledge sources and plugins. + +### Editorial answers (v1.7+) + +Use `editorial_answers` for approved, stable answers that should be selected through semantic similarity, such as official support contacts or policy FAQs. + +- Use it for canonical content that changes infrequently. +- Do not use it for personalized, permission-sensitive, or rapidly changing answers. +- Keep each question and answer focused on one intent. +- Review inline answers as governed content because they reduce normal generative variation. + +```json +{ + "editorial_answers": { + "answers": [ + { + "question": "How do I contact the help desk?", + "answer": "Email helpdesk@contoso.com or call extension 5555." + } + ] + } +} +``` + +### Default response mode (v1.7+) + +Choose `behavior_overrides.default_response_mode` from the dominant workload: + +| Mode | Use when | +|------|----------| +| `Auto` | Requests vary between simple lookups and complex analysis. This is the default. | +| `Quick response` | Low latency matters more than deep reasoning, such as routing or short FAQ agents. | +| `Think deeper` | The agent primarily performs complex analysis, planning, or multi-step decisions. | + +Users can override the default in the model selector. Do not rely on the setting as a hard enforcement mechanism. + +```json +{ + "behavior_overrides": { + "default_response_mode": "Think deeper" + } +} +``` + +--- + ## Example Instructions The following example is for an IT help desk agent: @@ -369,14 +419,29 @@ Identify the top 3-5 tasks users will perform: } ``` -#### 4. Use Natural Language +#### 4. Gate Capability-Specific Starters (v1.7+) + +Use `depends_on` when a starter only works with specific configured capabilities. Every dependency must be present before the starter is shown. + +```json +{ + "title": "Project Update", + "text": "Summarize internal email and public web updates for this project.", + "depends_on": [ + { "name": "capabilities", "id": "Email" }, + { "name": "capabilities", "id": "WebSearch" } + ] +} +``` + +#### 5. Use Natural Language Write starters as users would naturally speak: ✅ Good: "What's the latest on Project Phoenix?" ❌ Bad: "Query project status for Phoenix" -#### 5. Provide 3-6 Starters (Not Too Many) +#### 6. Provide 3-6 Starters (Not Too Many) - **Too few** (<3): Users don't see the full capability range - **Just right** (3-6): Good variety without overwhelming - **Too many** (>6): Clutters UI, users won't read them all diff --git a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/editing-workflow.md b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/editing-workflow.md index d758c86..557d1da 100644 --- a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/editing-workflow.md +++ b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/editing-workflow.md @@ -65,6 +65,9 @@ When you add, remove, or modify ANY capability or plugin, you MUST complete ALL - Identify the agent's primary purpose and target users - Determine required data sources (M365 services, external APIs) - List necessary actions the agent must perform +- Identify email and calendar **write** operations separately from read/search requirements +- Identify approved, stable FAQ answers that should use canonical response content +- Decide whether the default experience should favor automatic selection, low latency, or deeper reasoning - Identify security and compliance requirements ### Step 2: Design the Agent Architecture @@ -76,6 +79,15 @@ When you add, remove, or modify ANY capability or plugin, you MUST complete ALL - Plan authentication and authorization strategy - Design conversation flow and instructions +**Build-time feature discovery:** + +| User requirement | Manifest feature | Design rule | +|------------------|------------------|-------------| +| Email triage, supervised send, delete, rules, auto-reply, or folder management | `EmailActions` (v1.8+) | This is independent of read-only `Email`; its scopes do not carry over. Add confirmation guidance for sensitive writes. | +| Meeting scheduling, calendar events, time-finding polls, or time insights | `MeetingActions` (v1.8+) | This is separate from read-only `Meetings`. Add confirmation guidance before creating or changing events. | +| Canonical answers for semantically similar questions | `editorial_answers` (v1.7+) | Use for approved, stable Q&A. Do not use for dynamic or personalized data. | +| A consistent default speed/reasoning experience | `behavior_overrides.default_response_mode` (v1.7+) | Choose `Auto`, `Quick response`, or `Think deeper` based on the dominant workload. | + ### Step 3: Edit JSON Manifest Files **⚠️ PRE-EDIT CHECK — Before making ANY edits, do ALL of these:** @@ -87,7 +99,7 @@ When you add, remove, or modify ANY capability or plugin, you MUST complete ALL - Only after the user confirms, fix with surgical edits, then re-read the file - Then continue with the user's original request as a separate step -2. **Check the schema version**: Read the `"version"` field in `declarativeAgent.json` (e.g., `"v1.4"`, `"v1.6"`). For EVERY feature you plan to add, verify it exists in that version using the [feature matrix](schema.md). If a requested feature requires a newer version → **STOP. Tell the user.** Offer to upgrade the version first. +2. **Check the schema version**: Read the `"version"` field in `declarativeAgent.json` (e.g., `"v1.4"`, `"v1.8"`). For EVERY feature you plan to add, verify it exists in that version using the [feature matrix](schema.md). If a requested feature requires a newer version → **STOP. Tell the user.** Offer to upgrade the version first. 3. **Run a proactive instruction review** (if the edit touches instructions or capabilities): Before modifying instructions or adding/removing capabilities, run [Instruction Review](instruction-review.md) **Phase 1 (Inventory)**, **Phase 2 (Comprehension Check)**, and **Phase 3 (Diagnose)** against the current instructions. This catches existing problems before you add to them. For Phase 2, use the brief confirmation shortcut ("I see this agent is designed to [purpose]…") since this is a proactive check. If the review finds high-severity issues (C1, C3, C11, D1-D8), inform the user and offer to fix them as part of the current edit. diff --git a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/examples.md b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/examples.md index 65132a1..285f6cc 100644 --- a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/examples.md +++ b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/examples.md @@ -63,7 +63,7 @@ A minimal declarative agent manifest file (`declarativeAgent.json`): ```json { - "version": "v1.6", + "version": "v1.8", "name": "My Support Agent", "description": "An agent to help with customer support inquiries", "instructions": "You are a helpful customer support agent. Help users find information about their issues and guide them to solutions. Be polite and professional at all times." @@ -78,7 +78,7 @@ A declarative agent with SharePoint and Email capabilities: ```json { - "version": "v1.6", + "version": "v1.8", "name": "Knowledge Base Agent", "description": "An agent that searches company knowledge bases and emails", "instructions": "You help employees find information from our SharePoint knowledge base and relevant emails. Always cite your sources when providing information.", @@ -106,7 +106,7 @@ A declarative agent with helpful conversation starters: ```json { - "version": "v1.6", + "version": "v1.8", "name": "HR Assistant", "description": "An agent that helps employees with HR-related questions", "instructions": "You are an HR assistant helping employees with common HR questions about policies, benefits, and procedures.", @@ -135,7 +135,7 @@ A declarative agent connected to an external API: ```json { - "version": "v1.6", + "version": "v1.8", "name": "Repairs Agent", "description": "An agent that helps manage repair tickets", "instructions": "You help users create, find, and track repair tickets. Use the repairs API to search for existing tickets and create new ones when requested.", @@ -238,7 +238,7 @@ A complete agent combining all features: ```json { - "version": "v1.6", + "version": "v1.8", "id": "customer-support-agent", "name": "Customer Support Agent", "description": "A comprehensive support agent for customer inquiries", @@ -293,7 +293,42 @@ A complete agent combining all features: --- -## Example 10: Localized Agent +## Example 10: Email, Meeting, and Experience Controls + +A v1.8 agent that surfaces the four build-time discovery features: + +```json +{ + "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.8/schema.json", + "version": "v1.8", + "name": "Executive Assistant", + "description": "An agent that manages email and meetings and answers common support questions", + "instructions": "Help users manage email and meetings. Confirm before sending or deleting email and before creating or changing calendar events.", + "capabilities": [ + { + "name": "EmailActions" + }, + { + "name": "MeetingActions" + } + ], + "behavior_overrides": { + "default_response_mode": "Quick response" + }, + "editorial_answers": { + "answers": [ + { + "question": "How do I contact executive support?", + "answer": "Email executive-support@contoso.com." + } + ] + } +} +``` + +--- + +## Example 11: Localized Agent A declarative agent with tokenized strings for multi-language support. @@ -301,8 +336,8 @@ A declarative agent with tokenized strings for multi-language support. ```json { - "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.6/schema.json", - "version": "v1.6", + "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.8/schema.json", + "version": "v1.8", "name": "[[agent_name]]", "description": "[[agent_description]]", "instructions": "$[file]('instructions.txt')", diff --git a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/instruction-review.md b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/instruction-review.md index 118c33f..51a6a7e 100644 --- a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/instruction-review.md +++ b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/instruction-review.md @@ -242,7 +242,7 @@ These apply specifically to agents with API plugins (actions). --- -## Capability Reference (v1.6) +## Capability Reference (v1.8) Use this table to understand what each built-in capability provides and to detect intent mismatches between instructions and the manifest. This is a **guide for understanding intent**, not a keyword checklist. @@ -258,9 +258,11 @@ Use this table to understand what each built-in capability provides and to detec | `Dataverse` | Search Dataverse tables | "Dataverse", "CRM", "Dynamics", "Power Platform data", "business data" | | `TeamsMessages` | Search Teams channels, chats, meeting chats (messages only — NOT transcripts) | "Teams", "channels", "chat", "messages", "Teams messages", "mentions", "DMs" | | `Email` | Search user's email (and shared/group mailboxes) | "email", "inbox", "messages", "mail", "sent items", "flagged", "unread" | +| `EmailActions` | Perform email write operations | "send email", "archive", "flag", "mark read", "move email", "delete email", "inbox rule", "auto-reply", "create mail folder" | | `People` | Search people in the organization | "people", "org chart", "who is", "manager", "reports to", "birthday", "OOO", "colleagues" | | `ScenarioModels` | Use task-specific AI models | "model", "custom model", "specialized model" | | `Meetings` | Search calendar events, meeting details, **and meeting transcripts** | "meetings", "calendar", "events", "schedule", "invites", "attendees", "join link", "transcript", "what was discussed", "meeting notes", "recording" | +| `MeetingActions` | Perform meeting and calendar write operations | "schedule meeting", "create event", "find a time", "time poll", "calendar availability", "time insights" | | `EmbeddedKnowledge` | Use files bundled in the app package | "embedded files", "local files", "bundled docs" (not yet available) | > **How to use this table:** During Phase 2 (Comprehension Check) and Phase 3 (Diagnose), use this table to understand intent alignment — not for strict keyword matching. For **A1**: if a capability is in the manifest but the instructions never describe a scenario where the agent would use that data source (even in general terms), flag it as a gap — but do NOT require the exact capability name. For **A5**: if the instructions clearly direct the agent to access a data source that has no corresponding capability configured, flag it as an intent mismatch. Ambiguous phrasing that could apply to multiple capabilities should NOT be flagged. @@ -293,6 +295,11 @@ Use this table during Phase 1 step 7 to check if the agent's schema version supp | `People.include_related_content` | v1.6 | Include related docs, emails, and Teams messages for people searches | | `Email.group_mailboxes` | v1.6 | Search Microsoft 365 Group mailboxes | | `Meetings.items_by_id` | v1.6 | Scope to specific meetings/series | +| `editorial_answers` | v1.7 | Predefined question-answer pairs selected through semantic similarity | +| `behavior_overrides.default_response_mode` | v1.7 | Default to `Auto`, `Quick response`, or `Think deeper` | +| `conversation_starters[].depends_on` | v1.7 | Display starters only when required capabilities are configured | +| `EmailActions` | v1.8 | Email triage, supervised send, delete, rules, auto-reply, and folder management | +| `MeetingActions` | v1.8 | Meeting scheduling, time-finding polls, and time insights | > **How to use:** If the agent is on v1.4 and the instructions reference "meeting transcripts" or "calendar events", flag that `Meetings` requires v1.5+. If the instructions reference "people and what we have in common", flag that `People.include_related_content` requires v1.6. Always offer to upgrade — never silently change the version. @@ -339,8 +346,8 @@ Present your understanding in this structure: | [For each capability implied by instructions but NOT configured] | ❌ | ✅ | [Instructions assume this exists but it's not configured — will fail or hallucinate] | **Version upgrade opportunities:** -- [If the current schema version is not the latest (v1.6), list capabilities available in newer versions that could benefit this agent's intent. Example: "You're on v1.4. Upgrading to v1.5 would unlock `Meetings` (calendar + transcripts), which aligns with your instruction's references to meeting prep and scheduling."] -- [If already on v1.6: "✅ You're on the latest schema version — no upgrade needed."] +- [If the current schema version is older than the skill baseline (v1.8), list features available in newer versions that could benefit this agent's intent. Example: "You're on v1.7. Upgrading to v1.8 would unlock `EmailActions`, which aligns with the instructions to triage and send email."] +- [If already on v1.8: "✅ You're on the skill's target schema version — no upgrade needed."] **Tone / personality:** [What personality or communication style the instructions establish, if any] diff --git a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/localization.md b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/localization.md index 3731fe0..1bd1c99 100644 --- a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/localization.md +++ b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/localization.md @@ -85,8 +85,8 @@ Replace ALL user-facing strings in `declarativeAgent.json` (and `plugin.json`, i ```json { - "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.6/schema.json", - "version": "v1.6", + "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.8/schema.json", + "version": "v1.8", "name": "[[agent_name]]", "description": "[[agent_description]]", "instructions": "$[file]('instructions.txt')", diff --git a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/schema.md b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/schema.md index 1650061..f7e0ad9 100644 --- a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/schema.md +++ b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/schema.md @@ -1,8 +1,8 @@ # JSON Schema Reference for M365 Copilot Agents -This document provides schema version information, compatibility rules, and links to the official documentation for M365 Copilot declarative agent and API plugin manifests. +This document provides schema version information, compatibility rules, and links to the official documentation for M365 Copilot declarative agent and API plugin manifests. The skill targets declarative agent schema v1.8. -For full property details, examples, and JSON structures, refer to the linked GitHub documentation below. +For full property details, examples, and JSON structures, refer to the linked official documentation below. ## Schema Resources @@ -10,7 +10,9 @@ For full property details, examples, and JSON structures, refer to the linked Gi | Version | JSON Schema | Documentation | |---------|-------------|---------------| -| **v1.6** | [schema.json](https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.6/schema.json) | [declarative-agent-manifest-1.6.md](https://raw.githubusercontent.com/MicrosoftDocs/m365copilot-docs/main/docs/declarative-agent-manifest-1.6.md) | +| **v1.8 (skill baseline)** | [schema.json](https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.8/schema.json) | [Declarative agent schema 1.8](https://learn.microsoft.com/microsoft-365/copilot/extensibility/declarative-agent-manifest-1.8) | +| v1.7 | [schema.json](https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.7/schema.json) | [Declarative agent schema 1.7](https://learn.microsoft.com/microsoft-365/copilot/extensibility/declarative-agent-manifest-1.7) | +| v1.6 | [schema.json](https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.6/schema.json) | [declarative-agent-manifest-1.6.md](https://raw.githubusercontent.com/MicrosoftDocs/m365copilot-docs/main/docs/declarative-agent-manifest-1.6.md) | | v1.5 | [schema.json](https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json) | [declarative-agent-manifest-1.5.md](https://raw.githubusercontent.com/MicrosoftDocs/m365copilot-docs/main/docs/declarative-agent-manifest-1.5.md) | | v1.4 | [schema.json](https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.4/schema.json) | [declarative-agent-manifest-1.4.md](https://raw.githubusercontent.com/MicrosoftDocs/m365copilot-docs/main/docs/declarative-agent-manifest-1.4.md) | | v1.3 | [schema.json](https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.3/schema.json) | [declarative-agent-manifest-1.3.md](https://raw.githubusercontent.com/MicrosoftDocs/m365copilot-docs/main/docs/declarative-agent-manifest-1.3.md) | @@ -38,3 +40,106 @@ When building or editing an agent manifest, **fetch the documentation for the ve - API plugin function and runtime structures - Response semantics and Adaptive Card templates - MCP Server (RemoteMCPServer) runtime configuration + +## Changes in v1.8 + +Schema v1.8 adds two optional write-capability objects: + +| Capability | Purpose | +|------------|---------| +| `EmailActions` | Performs email write operations, including triage, supervised send, delete, inbox rules, auto-reply, and folder management. | +| `MeetingActions` | Performs meeting and calendar operations, including scheduling events, creating time-finding polls, and surfacing time insights. | + +Both capabilities require only the `name` property. + +### Email actions + +`EmailActions` operates independently of the read-only `Email` capability. Scopes configured on `Email`, such as `folders`, `shared_mailbox`, or `group_mailboxes`, do not restrict `EmailActions`. + +```json +{ + "capabilities": [ + { + "name": "EmailActions" + } + ] +} +``` + +### Meeting actions + +```json +{ + "capabilities": [ + { + "name": "MeetingActions" + } + ] +} +``` + +## Changes in v1.7 + +Schema v1.7 adds these optional properties: + +| Property | Location | Purpose | +|----------|----------|---------| +| `editorial_answers` | Manifest root | Defines up to 300 predefined question-answer pairs inline, or references them with `url`, for semantic matching. | +| `default_response_mode` | `behavior_overrides` | Sets the default model-selector mode to `Auto`, `Quick response`, or `Think deeper`. | +| `depends_on` | `conversation_starters[]` | Shows a starter only when every referenced capability is present in the manifest. | + +### Editorial answers + +Specify exactly one of `answers` or `url`. Inline answers require non-empty `question` and `answer` values. Optional `similarity_thresholds.min` and `.max` values must both be between 0 and 10. + +```json +{ + "editorial_answers": { + "answers": [ + { + "question": "How do I contact support?", + "answer": "Email support@contoso.com.", + "similarity_thresholds": { + "min": 7, + "max": 10 + } + } + ] + } +} +``` + +### Default response mode + +```json +{ + "behavior_overrides": { + "default_response_mode": "Think deeper" + } +} +``` + +### Capability-dependent conversation starters + +Each dependency requires `name` set to `capabilities` and an `id` matching a capability identifier such as `Email` or `WebSearch`. + +```json +{ + "conversation_starters": [ + { + "title": "Research an update", + "text": "Summarize internal email and public web updates for this project.", + "depends_on": [ + { + "name": "capabilities", + "id": "Email" + }, + { + "name": "capabilities", + "id": "WebSearch" + } + ] + } + ] +} +```