diff --git a/AGENTS.md b/AGENTS.md index d829a08..3a2108a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -77,7 +77,7 @@ plugins// - **microsoft-365-agents-toolkit** — Toolkit for building M365 Copilot declarative agents. Bundles: - `install-atk` skill — Install or update the M365 Agents Toolkit CLI and VS Code extension - - `declarative-agent-developer` skill — Scaffolding, JSON manifest authoring, capability configuration, deployment + - `declarative-agent-developer` skill — DA schema and capability guidance, with project lifecycle operations executed through the wiqd CLI - `teams-app-developer` skill — Build, test, and deploy code-based Teams apps: bots, CEA, tabs, message extensions, Agents Playground, Azure provision/deploy, and Slack-to-Teams migration - `ui-widget-developer` skill — Build MCP servers with OpenAI Apps SDK widget rendering for Copilot Chat - `m365-agent-evaluator` skill — Generate, run, and analyze evaluation suites for M365 Copilot declarative agents diff --git a/plugins/microsoft-365-agents-toolkit/README.md b/plugins/microsoft-365-agents-toolkit/README.md index 3292999..7dbd918 100644 --- a/plugins/microsoft-365-agents-toolkit/README.md +++ b/plugins/microsoft-365-agents-toolkit/README.md @@ -10,6 +10,16 @@ Toolkit for building Microsoft 365 Copilot declarative agents. /plugin install microsoft-365-agents-toolkit@work-iq ``` +## Prerequisites + +Declarative Agent project lifecycle operations through the +`declarative-agent-developer` skill require the wiqd CLI. Follow the +[official wiqd installation guide](https://microsoft.github.io/wiqd/getting-started/installation/) +for the current installation instructions. + +This requirement applies only to Declarative Agent workflows. Other ATK workflows continue to +use the ATK CLI and do not require wiqd. + ## Usage ``` @@ -20,7 +30,7 @@ Toolkit for building Microsoft 365 Copilot declarative agents. "Add web search to my agent" # Deploy -"Deploy my agent with ATK" +"Deploy my declarative agent" # Create evals "Create an eval suite for my agent based on it's capabilities." @@ -46,7 +56,7 @@ npx -y --package @microsoft/m365-copilot-eval@latest runevals --prompts-file eva | Skill | What It Does | |-------|-------------| | [**install-atk**](./skills/install-atk/SKILL.md) | Install or update the ATK CLI and VS Code extension | -| [**declarative-agent-developer**](./skills/declarative-agent-developer/SKILL.md) | Scaffolding, JSON manifest authoring, capability configuration, security patterns, deployment via ATK CLI | +| [**declarative-agent-developer**](./skills/declarative-agent-developer/SKILL.md) | DA schema, capability, and security guidance with lifecycle operations executed through the wiqd CLI | | [**ui-widget-developer**](./skills/ui-widget-developer/SKILL.md) | Build MCP servers with OpenAI Apps SDK widget rendering for Copilot Chat | | [**m365-agent-evaluator**](./skills/m365-agent-evaluator/SKILL.md) | Generate, run, and analyze evaluation suites for M365 Copilot declarative agents | 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..7942945 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 @@ -2,6 +2,7 @@ name: declarative-agent-developer description: > Create, build, deploy, and localize declarative agents for M365 Copilot and Teams. + Use the wiqd CLI for all declarative-agent lifecycle operations; never invoke the ATK CLI directly. USE THIS SKILL for ANY task involving a declarative agent — including localization, scaffolding, editing manifests, adding capabilities, and deploying. Localization requires tokenized manifests and language files that only this skill knows how to produce. @@ -15,22 +16,33 @@ description: > # M365 Agent Developer -## Telemetry Tagging +## wiqd CLI -Before running any `atk` CLI commands, set the session environment variable so all CLI invocations are tagged as skill-initiated: -```bash -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. +Use `wiqd` as the execution layer for every declarative-agent lifecycle operation. Keep using +this skill's references for manifest schemas, capability rules, plugins, authentication, +localization, and instruction design. + +Immediately before the first lifecycle command in a task, run `wiqd --version`. If it is +unavailable, stop and tell the user that wiqd is required. Direct them to the +[official wiqd installation guide](https://microsoft.github.io/wiqd/getting-started/installation/) for the current installation guidance; +do not duplicate platform-specific installer commands here. + +Do not fall back to direct `atk` commands. + +Reference-only requests that do not execute lifecycle commands can use this skill's schema, +capability, plugin, authentication, localization, and instruction guidance without requiring +wiqd to be installed. If the request does not inspect or modify a project and does not run a +project command, answer it directly from the relevant references and skip the workspace check +below. -## ⛔ Workspace Check — MANDATORY FIRST STEP +## ⛔ Workspace Check — MANDATORY FIRST STEP FOR PROJECT OPERATIONS -**Before doing ANYTHING, check the workspace files to fingerprint the project:** +**Before inspecting, modifying, validating, packaging, provisioning, sharing, or publishing a +project, check the workspace files to fingerprint it:** -1. Run `npx -y --package @microsoft/m365agentstoolkit-cli atk --version` to confirm ATK CLI is installed. If not found → **Stop.** Tell the user to install ATK. -2. Check for `m365agents.yml` or `teamsApp.yml` at the project root. -3. Check for `appPackage/declarativeAgent.json`. -4. Check for non-agent indicators (`package.json` with express/react/next, `src/index.js`, `app.py`, etc.) +1. Check for `m365agents.yml` or `teamsApp.yml` at the project root. +2. Check for `appPackage/declarativeAgent.json`. +3. Check for non-agent indicators (`package.json` with express/react/next, `src/index.js`, `app.py`, etc.) **Then follow the decision gate:** @@ -49,11 +61,11 @@ Run this once at the start of the session. All subsequent `atk` commands in the **These rules override ALL other instructions.** If any of these apply, you MUST stop immediately. -1. **NEVER create `declarativeAgent.json` yourself.** If the manifest is missing and the user asked to edit/modify/deploy, respond with text only: explain the manifest is missing, suggest `npx -y --package @microsoft/m365agentstoolkit-cli atk new` or starting from scratch. Do NOT create the file, do NOT create `appPackage/`, do NOT "help" by scaffolding implicitly. +1. **NEVER create `declarativeAgent.json` yourself.** If the manifest is missing and the user asked to edit/modify/deploy, respond with text only: explain the manifest is missing, suggest `wiqd agent create` or starting from scratch. Do NOT create the file, do NOT create `appPackage/`, do NOT "help" by scaffolding implicitly. 2. **NEVER create files in a non-agent project.** If the workspace is an Express/React/Django/etc. app without `appPackage/`, your response must be text-only. Do NOT create any files, do NOT run any commands. -3. **NEVER deploy when errors exist.** If the agent manifest has errors, STOP. Do NOT run `npx -y --package @microsoft/m365agentstoolkit-cli atk provision` — not "to test", not "to demonstrate the error", not "to see what happens". Report the errors and ask the user how to proceed. +3. **NEVER deploy when errors exist.** If the agent manifest has errors, STOP. Do NOT run `wiqd agent provision` — not "to test", not "to demonstrate the error", not "to see what happens". Report the errors and ask the user how to proceed. ### 🔍 Detect → Inform → Ask (Error-Handling Protocol) @@ -88,37 +100,31 @@ When you encounter ANY problem (missing files, malformed JSON, validation errors --- -## 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. - -All commands use the `npx -y --package @microsoft/m365agentstoolkit-cli atk` prefix (e.g., `npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local`). - ---- - ## Critical Rules -### 1. Deploy After EVERY Edit +### 1. Validate After Edits; Provision Only on Request -After ANY change to files in `appPackage/`, you MUST deploy and show the test link before responding: +After any change to files in `appPackage/`, validate the project before responding: ```bash -npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false +wiqd agent validate ``` -Then read `M365_TITLE_ID` from `env/.env.local` and **ALWAYS** present the review UX: +Provision only when the user explicitly asks to deploy, provision, test, share, or publish. After +a successful provision, use the deep link returned by wiqd. If it is unavailable, read +`M365_TITLE_ID` from the selected environment file and construct: ``` ✅ Agent deployed successfully! 🚀 Test Your Agent in M365 Copilot: -🔗 https://m365.cloud.microsoft/chat/?titleId={M365_TITLE_ID} +🔗 https://m365.cloud.microsoft/chat?titleId={M365_TITLE_ID} ``` -**⛔ Never respond without this link.** If you deployed, the test link MUST appear in your response. This is not optional — it is how the user tests their agent. +If you provisioned, include the test link in your response. - If the manifest has errors → **STOP. Fix errors. Do NOT deploy.** -- Exception: user explicitly asks you not to deploy +- Do not provision merely because files changed. ### 2. Never Invent Content or Create Missing Files @@ -138,18 +144,18 @@ Key version gates: - `ScenarioModels`, `behavior_overrides`, `disclaimer` → **v1.4+** - `Dataverse`, `TeamsMessages`, `Email`, `People` → **v1.3+** -### 4. Use `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` for API Plugins — NEVER Create Plugin Files Manually +### 4. Use `wiqd agent add action` for API Plugins — NEVER Create Plugin Files Manually You are **forbidden** from manually creating `ai-plugin.json`, OpenAPI specs, adaptive cards, or editing the `actions` array. Use the CLI: ```bash # ⛔ Always list ALL operations in a single call — NEVER run separate calls per operation -npx -y --package @microsoft/m365agentstoolkit-cli atk add action --api-plugin-type api-spec --openapi-spec-location URL --api-operation "GET /path,POST /path,PATCH /path/{id},DELETE /path/{id}" -i false +wiqd agent add action --openapi-spec URL --operations "GET /path,POST /path,PATCH /path/{id},DELETE /path/{id}" ``` -Run a **single** `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` call per OpenAPI spec, listing **all** operations as a comma-separated list in `--api-operation`. Never run separate `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` calls for different operations from the same spec — this creates multiple plugins instead of one. If `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` fails, report the error; do NOT fall back to manual creation. +Run a **single** `wiqd agent add action` call per OpenAPI spec, listing **all** operations as a comma-separated list in `--operations`. Never run separate `wiqd agent add action` calls for different operations from the same spec — this creates multiple plugins instead of one. If `wiqd agent add action` fails, report the error; do NOT fall back to manual creation. -> **Exception:** MCP servers are not supported by `npx -y --package @microsoft/m365agentstoolkit-cli atk add action`. Use the [MCP Plugin workflow](references/mcp-plugin.md) instead. +> MCP servers use the same command with `--mcp-server-url`; follow the [MCP Plugin workflow](references/mcp-plugin.md). ### 5. MCP Server Integration @@ -178,7 +184,7 @@ Always update the app name and description to something meaningful. Never leave - **[Best Practices](references/best-practices.md)** — Security, performance, testing, compliance - **[Conversation Design](references/conversation-design.md)** — Authoring instructions and conversation starters from scratch - **[Instruction Review](references/instruction-review.md)** — Auditing, diagnosing, and improving existing instructions; anti-pattern detection; before/after rewrites -- **[Deployment](references/deployment.md)** — ATK CLI workflows, environments, CI/CD +- **[Deployment](references/deployment.md)** — wiqd CLI workflows, environments, CI/CD - **[Localization](references/localization.md)** — Multi-language support, tokenized manifests, language files - **[Workspace Gates](references/workspace-gates.md)** — Detailed gate rules, examples, anti-patterns 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..792550c 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 @@ -12,91 +12,80 @@ API plugins (also called "actions") allow your M365 Copilot agent to interact wi --- -## ⛔ Post-`npx -y --package @microsoft/m365agentstoolkit-cli atk add action` Checklist — MANDATORY +## ⛔ Post-`wiqd agent add action` Checklist — MANDATORY -After running `npx -y --package @microsoft/m365agentstoolkit-cli atk add action`, you **MUST** complete ALL of these before validating and deploying: +After running `wiqd agent add action`, you **MUST** complete ALL of these before validation and any +user-requested deployment: 1. **Update `name_for_human`** in ai-plugin.json — descriptive, user-facing name (max 20 chars) 2. **Update `description_for_model`** in ai-plugin.json — detailed guidance for the AI on when and how to use each function 3. **Customize adaptive cards** in `appPackage/adaptiveCards/` for each operation — different layouts per HTTP verb (list view for GET collections, detail view for GET by ID, confirmation for DELETE, etc.) 4. **Add `confirmation` dialogs** for all destructive operations (POST, PUT, PATCH, DELETE) -5. **Deploy** with `npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false` +5. **Validate** with `wiqd agent validate`; provision only when the user explicitly requests + deployment, provisioning, testing, sharing, or publishing -Skipping ANY of these steps = incomplete work. The `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` command generates scaffolding — **you must finish the job** by customizing every generated file. +Skipping ANY of these steps = incomplete work. The `wiqd agent add action` command generates scaffolding — **you must finish the job** by customizing every generated file. --- -## Adding API Plugins with ATK CLI +## Adding API Plugins with wiqd CLI -> **⚠️ IMPORTANT:** When adding an API, OpenAPI spec, or REST API to your agent, you **MUST** use the `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` command. This is the required method for adding API plugins to M365 Copilot agents. **Do NOT manually create plugin files** - the path resolution between local packaging and M365 service validation is complex and error-prone. +> **⚠️ IMPORTANT:** When adding an API, OpenAPI spec, or REST API to your agent, you **MUST** use the `wiqd agent add action` command. This is the required method for adding API plugins to M365 Copilot agents. **Do NOT manually create plugin files** - the path resolution between local packaging and M365 service validation is complex and error-prone. -> **⛔ ONE PLUGIN PER API — HARD RULE:** Always add ALL operations from the same OpenAPI spec in a **single** `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` call. List every operation in the `--api-operation` parameter as a comma-separated list. **NEVER** run separate `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` calls for different operations from the same spec — this creates multiple plugins instead of one unified plugin. One OpenAPI spec = one `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` call = one plugin. +> **⛔ ONE PLUGIN PER API — HARD RULE:** Always add ALL operations from the same OpenAPI spec in a **single** `wiqd agent add action` call. List every operation in the `--operations` parameter as a comma-separated list. **NEVER** run separate `wiqd agent add action` calls for different operations from the same spec — this creates multiple plugins instead of one unified plugin. One OpenAPI spec = one `wiqd agent add action` call = one plugin. -### The `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` Command +### The `wiqd agent add action` Command **ALWAYS use this command** when asked to add an API, OpenAPI specification, or REST API to an M365 Copilot agent: ```bash -npx -y --package @microsoft/m365agentstoolkit-cli atk add action \ - --api-plugin-type api-spec \ - --openapi-spec-type enter-url-or-open-local-file \ - --openapi-spec-location URL_OR_FILE_PATH \ - --api-operation "OPERATIONS_TO_MAP" \ - -i false +wiqd agent add action \ + --openapi-spec URL_OR_FILE_PATH \ + --operations "OPERATIONS_TO_MAP" ``` ### Command Parameters | Parameter | Description | |-----------|-------------| -| `--api-plugin-type` | Type of plugin. Use `api-spec` for OpenAPI-based plugins. | -| `--openapi-spec-type` | How to provide the spec. Use `enter-url-or-open-local-file`. | -| `--openapi-spec-location` | URL or local file path to the OpenAPI specification. | -| `--api-operation` | Comma-separated list of operations to include (format: `METHOD /path`). | -| `-i false` | Non-interactive mode. | +| `--openapi-spec` | URL or local file path to the OpenAPI specification. | +| `--operations` | Comma-separated list of operations to include (format: `METHOD /path`). | -### ⚠️ CRITICAL: Use Absolute Paths for Local Files +### Local File Paths -When using a local OpenAPI specification file, you **MUST use an absolute path**: +`--openapi-spec` accepts relative and absolute local file paths. Relative paths are resolved from +the project directory selected by `--folder`; when `--folder` is omitted, it defaults to the +current working directory. Prefer a project-relative path when the specification belongs to the +project: ```bash -# ✅ CORRECT - Absolute path ---openapi-spec-location /home/user/project/openapi.json - -# ❌ WRONG - Relative path (will fail!) ---openapi-spec-location ./openapi.json ---openapi-spec-location openapi.json +--openapi-spec ./api/openapi.yaml --folder ./my-agent ``` -**Why?** The ATK CLI executes from a temporary directory, so relative paths cannot be resolved. Always use the full absolute path to your OpenAPI specification file. +Use an absolute path when the specification is outside the project or when the working directory +is uncertain. ### Operation Format -The `--api-operation` parameter uses the format: `METHOD /path,METHOD /path,...` +The `--operations` parameter uses the format: `METHOD /path,METHOD /path,...` **Example with Repairs API (URL):** ```bash -npx -y --package @microsoft/m365agentstoolkit-cli atk add action \ - --api-plugin-type api-spec \ - --openapi-spec-type enter-url-or-open-local-file \ - --openapi-spec-location "https://repairshub.azurewebsites.net/openapi.json" \ - --api-operation "GET /repairs,GET /repairs/{id},POST /repairs,PATCH /repairs/{id},DELETE /repairs/{id}" \ - -i false +wiqd agent add action \ + --openapi-spec "https://repairshub.azurewebsites.net/openapi.json" \ + --operations "GET /repairs,GET /repairs/{id},POST /repairs,PATCH /repairs/{id},DELETE /repairs/{id}" ``` **Example with local file (absolute path):** ```bash -npx -y --package @microsoft/m365agentstoolkit-cli atk add action \ - --api-plugin-type api-spec \ - --openapi-spec-type enter-url-or-open-local-file \ - --openapi-spec-location /home/user/myproject/nhl-openapi.json \ - --api-operation "GET /v1/standings/now,GET /v1/score/now,GET /v1/schedule/now" \ - -i false +wiqd agent add action \ + --openapi-spec /home/user/myproject/nhl-openapi.json \ + --operations "GET /v1/standings/now,GET /v1/score/now,GET /v1/schedule/now" ``` ### What the Command Creates -After running `npx -y --package @microsoft/m365agentstoolkit-cli atk add action`, the following files are created/updated: +After running `wiqd agent add action`, the following files are created/updated: ``` appPackage/ @@ -115,7 +104,7 @@ appPackage/ ### Post-Generation: Enhance the Plugin -After running `npx -y --package @microsoft/m365agentstoolkit-cli atk add action`, you **MUST** enhance the generated files: +After running `wiqd agent add action`, you **MUST** enhance the generated files: 1. **Update `name_for_human`** - Make it descriptive and user-friendly 2. **Update `description_for_model`** - Add detailed guidance on when and how to use each function @@ -134,11 +123,11 @@ The `description_for_model` is critical - it tells the AI when to use each funct ### 🎨 Post-Generation: Enhance Adaptive Cards for Each Action -The `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` command auto-generates basic adaptive cards in `appPackage/adaptiveCards/` — one per operation. These default cards are generic and only display raw data. **You MUST customize each card** to provide a valuable UX tailored to the data each action returns. +The `wiqd agent add action` command auto-generates basic adaptive cards in `appPackage/adaptiveCards/` — one per operation. These default cards are generic and only display raw data. **You MUST customize each card** to provide a valuable UX tailored to the data each action returns. #### ⚠️ CRITICAL: Check ALL Operations Have Adaptive Cards -After running `npx -y --package @microsoft/m365agentstoolkit-cli atk add action`, **verify that an adaptive card exists for EVERY operation**. The command may not generate cards for POST, PATCH, or DELETE operations. **If any operation is missing an adaptive card, CREATE one manually** in `appPackage/adaptiveCards/`. +After running `wiqd agent add action`, **verify that an adaptive card exists for EVERY operation**. The command may not generate cards for POST, PATCH, or DELETE operations. **If any operation is missing an adaptive card, CREATE one manually** in `appPackage/adaptiveCards/`. - **GET operations** → List or detail layout showing returned data - **POST operations** → Confirmation/summary layout showing what was created @@ -782,7 +771,7 @@ For API key-protected APIs: } ``` -> **Note:** The `reference_id` is obtained when configuring authentication in the Microsoft 365 admin center or through the ATK CLI during provisioning. +> **Note:** The `reference_id` is obtained when configuring authentication in the Microsoft 365 admin center or through the wiqd CLI during provisioning. --- @@ -1107,7 +1096,7 @@ Content-Type: application/json ```bash # Provision the agent -npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false +wiqd agent provision --env local # Use the returned test URL to test in M365 Copilot ``` @@ -1161,10 +1150,10 @@ Test with various prompts: | CORS errors | API doesn't allow agent origin | Configure API CORS to allow M365 origins | | Timeout errors | API response too slow | Optimize API, add caching, increase timeout | | Schema mismatch | Plugin expects different response format | Update OpenAPI spec to match actual API response | -| "No operations selected" | Empty `--api-operation` parameter | Specify operations in correct format: `METHOD /path` | -| "File not found" during `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` | Relative path used for local OpenAPI spec | **Use absolute path**: `/full/path/to/openapi.json` | -| "File not found in zip archive" during provision | Manual plugin creation with incorrect spec path | **Use `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` command** - do not manually create plugins | -| OpenAPI spec path resolution fails | Path conflicts between zipAppPackage and M365 service | The ATK CLI handles this correctly - always use `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` | +| "No operations selected" | Empty `--operations` parameter | Specify operations in correct format: `METHOD /path` | +| "File not found" during `wiqd agent add action` | Path is not valid relative to `--folder` | Correct `--folder` or the relative path, or use an absolute path | +| "File not found in zip archive" during provision | Manual plugin creation with incorrect spec path | **Use `wiqd agent add action` command** - do not manually create plugins | +| OpenAPI spec path resolution fails | Path conflicts between zipAppPackage and M365 service | The wiqd CLI handles this correctly - always use `wiqd agent add action` | ### Why Manual Plugin Creation Fails @@ -1173,7 +1162,7 @@ If you try to manually create API plugin files, you'll encounter path resolution 1. **zipAppPackage** resolves spec paths relative to the plugin file location 2. **M365 extendToM365** resolves spec paths relative to the zip archive root -These different resolution strategies make manual path configuration nearly impossible. The `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` command handles this complexity automatically by: +These different resolution strategies make manual path configuration nearly impossible. The `wiqd agent add action` command handles this complexity automatically by: - Placing the OpenAPI spec in `apiSpecificationFile/` - Using the correct relative path `apiSpecificationFile/openapi.yaml` in the plugin - Ensuring the zip archive structure matches the path expectations diff --git a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/authentication.md b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/authentication.md index f783a22..2a5d446 100644 --- a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/authentication.md +++ b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/authentication.md @@ -6,7 +6,7 @@ This guide explains how to configure authentication for MCP server plugins and A > - You want your agent to sign in the current M365 user and pass their verified identity to your plugin (Entra SSO) > - Your MCP server requires OAuth authentication (most third-party MCP servers do) > - Your API plugin requires OAuth (not just API key auth) -> - You need to register SSO or OAuth credentials in the Teams Developer Portal via ATK +> - You need to register SSO or OAuth credentials in the Teams Developer Portal through the wiqd lifecycle > **When NOT to use this guide:** > - The MCP server or API is unauthenticated → use `"auth": {"type": "None"}` directly @@ -35,7 +35,9 @@ This guide covers two distinct patterns. Pick the one that matches your goal — Use this pattern when you want the agent to authenticate the **signed-in M365 user** and pass their verified identity (claims like `name`, `oid`, `tid`) to your plugin's backend — no separate login screen. This is **single sign-on against your own Entra tenant**, not a connection to a third-party OAuth service. -> **⚡ Automate this end-to-end.** For an agent built with the `ui-widget-developer` skill (OAI Apps path — `mcpPlugin.json` + a raw-http MCP server), the **`setup-sso-ui-widget`** skill (in this same `microsoft-365-agents-toolkit` plugin) performs every step below automatically — Entra app registration, ATK OAuth, manifest wiring, JWKS token guard, and sideload. Its [`sso-explained.md`](../../setup-sso-ui-widget/references/sso-explained.md) has the runtime token-flow deep dive. +> For a new MCP action, prefer `wiqd agent add action --mcp-auth-type entra-sso +> --mcp-client-id ""`. Use the detailed steps below to review or customize an existing +> action, then validate and provision through wiqd. > **Same config for API plugins and MCP servers.** The Entra app registration, the `oauth/register` step, and the `OAuthPluginVault` manifest reference are identical for both. Only the location of the `auth` block in the manifest differs. @@ -48,7 +50,7 @@ Use this pattern when you want the agent to authenticate the **signed-in M365 us | | Entra SSO | Third-party OAuth (Steps 1–4) | |---|---|---| | `identityProvider` | `MicrosoftEntra` | `Custom` | -| Client secret | Not required (ATK derives it from the tenant) | Required | +| Client secret | Not required (the lifecycle derives it from the tenant) | Required | | `authorizationUrl` / `tokenUrl` | Not needed (derived from tenant) | Required | | Who signs in | The current M365 user | An account on the external service | | Result | Verified caller identity (no downstream access without OBO) | Delegated access to the external API | @@ -74,9 +76,9 @@ az ad app update --id $ClientId ` > **Tenants with an app-creation policy:** some tenants require additional metadata on `az ad app create` (for example a `--service-management-reference ` value), and may require multiple owners on both the app and its service principal before admin consent can be granted. If your tenant enforces such a policy, `az ad app create` will fail with a policy error — add the value it asks for and retry. -### Step S2 — Register the SSO Config with ATK (`MicrosoftEntra`) +### Step S2 — Register the SSO Config (`MicrosoftEntra`) -Add an `oauth/register` step to **both** `m365agents.yml` and `m365agents.local.yml`. The `MicrosoftEntra` flow only needs the **Client ID** and the **service (base) URL** — **no** `clientSecret`, `authorizationUrl`, or `tokenUrl`. ATK derives those from the tenant and writes back the generated **Application ID URI**: +Add an `oauth/register` step to **both** `m365agents.yml` and `m365agents.local.yml`. The `MicrosoftEntra` flow only needs the **Client ID** and the **service (base) URL** — **no** `clientSecret`, `authorizationUrl`, or `tokenUrl`. The lifecycle derives those from the tenant and writes back the generated **Application ID URI**: ```yaml - uses: oauth/register @@ -92,20 +94,18 @@ Add an `oauth/register` step to **both** `m365agents.yml` and `m365agents.local. applicationIdUri: _SSO_APP_ID_URI ``` -> Pre-seed `AAD_APP_CLIENT_ID=` and empty `_SSO_AUTH_ID=` / `_SSO_APP_ID_URI=` in your env file **before** provisioning. Run `atk provision` (use `--env local` for local projects, which runs `m365agents.local.yml`), then read the generated `_SSO_AUTH_ID` and `_SSO_APP_ID_URI` back from the env file. - -> **Concrete key names used by the `setup-sso-ui-widget` skill:** `` and the middle segment are project-chosen. Wherever this doc shows `_SSO_AUTH_ID` / `_SSO_APP_ID_URI`, that skill's automation concretely uses **`MCP_DA_OAUTH_AUTH_ID`** (the `configurationId`) and **`MCP_DA_OAUTH_APP_ID_URI`** (the `applicationIdUri`). +> Pre-seed `AAD_APP_CLIENT_ID=` and empty `_SSO_AUTH_ID=` / `_SSO_APP_ID_URI=` in your env file **before** provisioning. Run `wiqd agent provision` (use `--env local` for local projects, which runs `m365agents.local.yml`), then read the generated `_SSO_AUTH_ID` and `_SSO_APP_ID_URI` back from the env file. ### Step S3 — Link the Application ID URI Back to the Entra App -`oauth/register` **outputs** the Application ID URI (`_SSO_APP_ID_URI`). Read it back from the env file and set it as the app's identifier URI so the ATK OAuth config and the Entra app point at the same identity: +`oauth/register` **outputs** the Application ID URI (`_SSO_APP_ID_URI`). Read it back from the env file and set it as the app's identifier URI so the OAuth config and the Entra app point at the same identity: ```powershell $AppIdUri = ((Get-Content env/.env.local | Where-Object { $_ -match '^_SSO_APP_ID_URI=' }) -replace '^_SSO_APP_ID_URI=','').Trim() az ad app update --id $ClientId --identifier-uris "$AppIdUri" ``` -> This link is what lets Copilot request a token whose `aud` matches the URI your backend validates. Do this **after** S2 so you use the exact URI ATK generated. +> This link is what lets Copilot request a token whose `aud` matches the URI your backend validates. Do this **after** S2 so you use the exact URI generated by the lifecycle. > > **⛔ Critical — accept every audience form Entra may emit.** A real SSO token's `aud` is frequently the **bare client-id GUID**, *not* the `api://` URI — even on a `ver: 2.0` token. Validate `aud` against **all** of `[, api://, ]`. Accepting only the `api://` / Application ID URI form will **401 a valid token** and trigger the endless sign-in loop (see *SSO Behavior — 401 vs 403* below). Still reject tokens minted for a *different* app. @@ -190,11 +190,11 @@ Remove-Item $bodyFile -ErrorAction SilentlyContinue az ad app show --id $ClientId --query "{appIdUri:identifierUris[0], tokenVersion:api.requestedAccessTokenVersion, scopes:api.oauth2PermissionScopes[].value, preAuthCount:length(api.preAuthorizedApplications), graphPerms:length(requiredResourceAccess)}" -o json ``` -Expected: `appIdUri` = the ATK-generated URI, `tokenVersion` = `2`, `scopes` = `["access_as_user"]`, `preAuthCount` = `1` (M365 Copilot), `graphPerms` = `1`. +Expected: `appIdUri` = the lifecycle-generated URI, `tokenVersion` = `2`, `scopes` = `["access_as_user"]`, `preAuthCount` = `1` (M365 Copilot), `graphPerms` = `1`. ### Step S6 — Wire SSO into the Plugin Manifest -The **`auth` block is identical** for MCP servers and API plugins — only the surrounding runtime `type`/`spec` differs. Reference the ATK-generated SSO config via `OAuthPluginVault`: +The **`auth` block is identical** for MCP servers and API plugins — only the surrounding runtime `type`/`spec` differs. Reference the generated SSO config via `OAuthPluginVault`: ```json "auth": { @@ -277,7 +277,7 @@ Authenticated plugins use a three-part setup: 1. **Discover** OAuth endpoints from the server's well-known metadata 2. **Obtain** client credentials (via Dynamic Client Registration or manual entry) -3. **Register** the OAuth configuration in `m365agents.yml` so ATK provisions it in the Teams Developer Portal +3. **Register** the OAuth configuration in `m365agents.yml` so wiqd provisions it in the Teams Developer Portal The result is a `_MCP_AUTH_ID` environment variable that the plugin manifest references via `OAuthPluginVault`. 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..d982a37 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 @@ -64,7 +64,7 @@ Follow these best practices for successful M365 Copilot agent development. ## Deployment - **Environment Strategy:** Use separate environments for dev, staging, and production -- **CI/CD Integration:** Automate testing and deployment using ATK CLI +- **CI/CD Integration:** Automate testing and deployment using wiqd CLI - **Version Management:** Bump versions before re-provisioning shared agents - **Rollback Plan:** Have a rollback strategy for failed deployments - **Monitoring:** Implement monitoring and alerting for production agents diff --git a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/deployment.md b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/deployment.md index 3891652..ff94e0e 100644 --- a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/deployment.md +++ b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/deployment.md @@ -1,12 +1,16 @@ -# ATK CLI and Deployment for M365 Agents +# wiqd CLI and Deployment for M365 Agents -## ATK CLI Overview +## wiqd CLI Overview -The Agents Toolkit (ATK) CLI is the official toolchain for M365 agent project management. It handles the complete agent lifecycle from creation to deployment. +The wiqd CLI is the execution layer for M365 declarative-agent project management. It orchestrates the complete lifecycle from creation to deployment. **Golden Rule:** -Check if ATK CLI is available (`npx -y --package @microsoft/m365agentstoolkit-cli atk --version`). If not found, **STOP and tell the user** that the ATK CLI is required but not installed. Do NOT attempt to install it yourself. -Then use `npx -y --package @microsoft/m365agentstoolkit-cli atk` for all commands. +Check if wiqd CLI is available (`wiqd --version`). If not found, **STOP and tell the user** that +the wiqd CLI is required but not installed. Direct them to the +[official wiqd installation guide](https://microsoft.github.io/wiqd/getting-started/installation/) for the current installation guidance +instead of duplicating platform-specific installer commands here. + +Then use `wiqd` for all commands. 🚨 **Never** use shortcuts, .vscode tasks, or abbreviated commands. @@ -15,50 +19,49 @@ Then use `npx -y --package @microsoft/m365agentstoolkit-cli atk` for all command ### 1. Project Creation ```bash # Create new agent project -npx -y --package @microsoft/m365agentstoolkit-cli atk new \ - -n my-agent \ - -c declarative-agent \ - -with-plugin type-spec \ - -i false +wiqd agent create --name my-agent # Navigate into project cd my-agent ``` -**Project structure created:** +**Typical core project structure (verify the generated output):** ``` my-agent/ +├── .vscode/ ├── appPackage/ │ ├── manifest.json # Teams app manifest │ ├── declarativeAgent.json # Declarative agent definition -│ ├── instructions.txt # Agent instructions -│ └── adaptiveCards/ -│ └── card.json # Adaptive card template (from template) -├── assets/ # Asset files directory +│ ├── instruction.txt # Agent instructions referenced by the scaffold +│ ├── color.png +│ └── outline.png ├── env/ -│ ├── .env.local # Local environment (template) -│ └── .env.local.user # Local environment (secrets, generated) -├── package.json # Node.js dependencies +│ ├── .env.local +│ └── .env.dev +├── evals/ ├── m365agents.yml # M365 agents config ├── m365agents.local.yml # M365 agents local config -└── README.md +└── README.md ``` +Treat `declarativeAgent.json` as the source of truth for the instruction filename rather than +assuming a fixed name; existing projects may use a different valid filename. + ### 2. Provisioning Provisioning generates M365 Title ID on first time and makes the updated agent available to the developer on Microsoft 365 Copilot. ```bash # Provision for development -npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env dev --interactive false +wiqd agent provision --env dev # Provision for staging -npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env staging --interactive false +wiqd agent provision --env staging # Provision for production -npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env prod --interactive false +wiqd agent provision --env prod # Provision for a custom environment -npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env custom --interactive false +wiqd agent provision --env custom ``` **What provisioning does:** @@ -67,33 +70,26 @@ npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env custom --i - Sets up authentication and permissions - Registers OAuth credentials (if `oauth/register` is in the lifecycle — see [authentication.md](authentication.md)) -> **⚠️ `M365_TITLE_ID` requires `teamsApp/extendToM365`:** The `M365_TITLE_ID` environment variable is generated by the `teamsApp/extendToM365` lifecycle step during provisioning. Without this step, the Teams app registers but the agent will **not** appear in Copilot Chat. If you scaffolded the project with `npx -y --package @microsoft/m365agentstoolkit-cli atk new`, this step is included automatically. If you set up the project manually, verify that your `m365agents.yml` includes the `teamsApp/extendToM365` lifecycle action — see the [mcp-plugin.md scaffold section](mcp-plugin.md#scaffold-the-agent-project-first) for the required lifecycle steps. +> **⚠️ `M365_TITLE_ID` requires `teamsApp/extendToM365`:** The `M365_TITLE_ID` environment variable is generated by the `teamsApp/extendToM365` lifecycle step during provisioning. Without this step, the Teams app registers but the agent will **not** appear in Copilot Chat. If you scaffolded the project with `wiqd agent create`, this step is included automatically. If you set up the project manually, verify that your `m365agents.yml` includes the `teamsApp/extendToM365` lifecycle action — see the [mcp-plugin.md scaffold section](mcp-plugin.md#scaffold-the-agent-project-first) for the required lifecycle steps. **⚠️ CRITICAL: ALWAYS RENDER THIS AFTER ANY PROVISION OPERATION ⚠️** After EVERY provisioning command (regardless of environment or whether it's first-time or re-provisioning), you MUST output a test link: -**Local environment** — read `M365_TITLE_ID` from `env/.env.local` and construct the URL: +For every environment, prefer the `deepLink` returned by wiqd. If it is unavailable, read +`M365_TITLE_ID` from `env/.env.{environment}` and construct: ``` ✅ Provision completed successfully! 🚀 Test Your Agent: -🔗 https://m365.cloud.microsoft/chat/?titleId={M365_TITLE_ID} -``` - -**Non-local environments (dev, staging, prod, etc.)** — use the `SHARE_LINK` value from `env/.env.{environment}`: -``` -✅ Provision completed successfully! - -🚀 Test Your Agent: -🔗 {SHARE_LINK} +🔗 https://m365.cloud.microsoft/chat?titleId={M365_TITLE_ID} ``` **This is REQUIRED for:** - ✅ First-time provisioning - ✅ Re-provisioning after changes - ✅ Any environment (local, dev, staging, prod, custom) -- ✅ Every single `npx -y --package @microsoft/m365agentstoolkit-cli atk provision` command — **ALWAYS** use `--interactive false` +- ✅ Every single `wiqd agent provision` command **Do NOT skip this output. The user needs this link to test their agent.** @@ -102,10 +98,10 @@ Package agent for distribution or publishing. ```bash # Package for development -npx -y --package @microsoft/m365agentstoolkit-cli atk package --env dev +wiqd agent package --env dev # Package for production -npx -y --package @microsoft/m365agentstoolkit-cli atk package --env prod +wiqd agent package --env prod ``` **What packaging does:** @@ -130,33 +126,36 @@ If the developers isn't clear on the sharing scope, ask follow-up questions to c **Share with entire tenant:** ```bash -npx -y --package @microsoft/m365agentstoolkit-cli atk share \ +wiqd agent share \ --scope tenant \ - --env dev \ - -i false + --env dev ``` **Share with specific users:** ```bash -npx -y --package @microsoft/m365agentstoolkit-cli atk share \ +wiqd agent share \ --scope users \ --email 'user1@contoso.com,user2@contoso.com' \ - --env dev \ - -i false + --env dev ``` -### 6. Publishing (Optional) -Publish to Microsoft 365 App Store or organizational catalog. +### 6. Publish to the Organizational Admin Catalog (Optional) + +`wiqd agent publish` publishes to the tenant's organizational admin catalog: ```bash # Publish to catalog -npx -y --package @microsoft/m365agentstoolkit-cli atk publish --env prod +wiqd agent publish --env prod ``` **What publishing does:** -- Submits agent to Microsoft 365 catalog +- Submits the agent to the organizational admin catalog - Requires admin approval in tenant -- Makes agent discoverable to users +- Makes the agent discoverable to users in that organization + +For public Microsoft commercial marketplace or AppSource submission, follow the current Partner +Center guidance in the [official wiqd documentation](https://aka.ms/wiqd/docs); +`wiqd agent publish` is not the public marketplace submission flow. ## Environment Management @@ -171,7 +170,7 @@ Two deployment models: **Shared Agents (`AGENT_SCOPE=shared`):** - Single instance shared by multiple users -- Requires explicit sharing via `npx -y --package @microsoft/m365agentstoolkit-cli atk share` +- Requires explicit sharing via `wiqd agent share` - Use for: Team agents, organizational assistants ### Environment Files Structure @@ -321,13 +320,13 @@ Required for sharing and publishing agents. ```bash # Login to M365 -npx -y --package @microsoft/m365agentstoolkit-cli atk auth login m365 +wiqd auth login # List current authentication -npx -y --package @microsoft/m365agentstoolkit-cli atk auth list +wiqd auth status # Logout -npx -y --package @microsoft/m365agentstoolkit-cli atk auth logout m365 +wiqd auth logout ``` **Required permissions:** @@ -336,7 +335,7 @@ npx -y --package @microsoft/m365agentstoolkit-cli atk auth logout m365 ## Testing Agents ### Testing Deployed Agents -After deployment, ATK provides a test link: +After deployment, wiqd provides a test link: ``` 🚀 Test Your Agent: 🔗 https://m365.cloud.microsoft/chat/?titleId=abc123xyz @@ -354,30 +353,31 @@ After deployment, ATK provides a test link: ### Check System Prerequisites ```bash -npx -y --package @microsoft/m365agentstoolkit-cli atk doctor +wiqd doctor ``` **Checks:** -- Node.js version -- npm version -- Azure CLI installation -- Authentication status -- Network connectivity +- Core runtime and dependency health reported by the installed wiqd version +- Extension registration and routing health +- Other platform-specific checks surfaced in the command output + +Do not treat `wiqd doctor` success as proof that Azure CLI, network connectivity, or Microsoft 365 +authentication is ready. Check those prerequisites separately when the requested operation needs +them; use `wiqd auth status` for wiqd authentication. ### Common Issues -**"Command not found" or slow first run:** -- ATK CLI downloads on first use (10-30 seconds) -- Wait for download to complete -- Ensure internet connectivity +**"Command not found":** +- Follow the current installation guidance in the [official wiqd installation guide](https://microsoft.github.io/wiqd/getting-started/installation/) +- Restart the terminal, then verify with `wiqd --version` **"Authentication required":** ```bash # Check auth status -npx -y --package @microsoft/m365agentstoolkit-cli atk auth list +wiqd auth status # Login to M365 -npx -y --package @microsoft/m365agentstoolkit-cli atk auth login m365 +wiqd auth login ``` **"Environment not provisioned":** 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..374b8d7 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 @@ -18,18 +18,17 @@ When developing an agent, you MUST ALWAYS update the app name and description in --- -## 🚨 CRITICAL DEPLOYMENT RULE 🚨 +## 🚨 CRITICAL VALIDATION AND DEPLOYMENT RULE 🚨 -When making ANY edits to an agent — including instructions, conversation starters, capabilities, plugins, or any file in `appPackage/` — you MUST ALWAYS deploy using `npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false` before returning to the user. This applies to EVERY turn, not just the final turn. Never return to the user with undeployed changes. +After editing an agent, validate it with `wiqd agent validate` before returning to the user. +Provision only when the user explicitly asks to deploy, provision, test, share, or publish. **You must NEVER:** -- Skip deploy because "it's just instructions" — deploy after every change -- Tell the user to "run `npx -y --package @microsoft/m365agentstoolkit-cli atk provision` yourself" — YOU must run it +- Skip validation after changing manifests, instructions, capabilities, or plugins +- Provision merely because files changed - Deploy when validation found errors — not even "to test" or "to demonstrate" - Deploy "to show the user what happens" when there are errors — just report the errors -- Run `npx -y --package @microsoft/m365agentstoolkit-cli atk provision` "for educational purposes" to demonstrate failure — errors = STOP, not a teaching moment - -**Only exception:** The user explicitly asks you NOT to deploy. Only the user can opt out, never you. +- Run `wiqd agent provision` "for educational purposes" to demonstrate failure — errors = STOP, not a teaching moment --- @@ -45,7 +44,8 @@ Every agent needs meaningful conversation starters that help users understand wh **This is NOT optional.** Adding a capability without updating instructions is incomplete work. -When you add, remove, or modify ANY capability or plugin, you MUST complete ALL of these steps before deploying: +When you add, remove, or modify ANY capability or plugin, you MUST complete ALL of these steps +before validation and any user-requested deployment: 1. **Update `instructions`** — Add a section describing what the new capability/plugin enables. For removals, delete all references to the removed capability. 2. **Add conversation starters** — Add at least 1 new conversation starter per added capability or plugin. Each starter should demonstrate the new functionality. @@ -96,24 +96,26 @@ When you add, remove, or modify ANY capability or plugin, you MUST complete ALL **Action:** Configure the agent using JSON manifest files: - Edit `declarativeAgent.json` to define agent properties - Configure capabilities with appropriate scoping -- Set up API plugin integrations using `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` (**NEVER manually create plugin files**) +- Set up API plugin integrations using `wiqd agent add action` (**NEVER manually create plugin files**) - Write clear instructions and conversation starters - Ensure proper JSON syntax and schema compliance -**After ALL edits, immediately run:** +**After ALL edits, run:** ```bash -npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false +wiqd agent validate ``` -This command is part of the edit — not a separate optional step. Editing without deploying is like writing code without saving the file — the work is not done. +If validation fails, report the errors and follow the workspace-gate error protocol. Do not +provision unless the user explicitly requested deployment, testing, sharing, or publishing and +validation passes. -**⛔ API Plugin Rule — HARD RULE, NO EXCEPTIONS:** To add an API plugin, you MUST use `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` — one command per OpenAPI spec with **ALL operations included in a single call**. Never run separate `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` calls for different operations from the same spec — this creates multiple plugins instead of one. You are FORBIDDEN from manually creating `ai-plugin.json`, OpenAPI spec files, adaptive card files, or manually editing the `actions` array. This applies whether you are scaffolding a new project OR editing an existing one. If the workspace already has an agent and the user says "add an API plugin", you STILL must use `npx -y --package @microsoft/m365agentstoolkit-cli atk add action`. If `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` fails, report the error — do NOT fall back to manual file creation. **Manual plugin file creation = automatic eval failure.** +**⛔ API Plugin Rule — HARD RULE, NO EXCEPTIONS:** To add an API plugin, you MUST use `wiqd agent add action` — one command per OpenAPI spec with **ALL operations included in a single call**. Never run separate `wiqd agent add action` calls for different operations from the same spec — this creates multiple plugins instead of one. You are FORBIDDEN from manually creating `ai-plugin.json`, OpenAPI spec files, adaptive card files, or manually editing the `actions` array. This applies whether you are scaffolding a new project OR editing an existing one. If the workspace already has an agent and the user says "add an API plugin", you STILL must use `wiqd agent add action`. If `wiqd agent add action` fails, report the error — do NOT fall back to manual file creation. **Manual plugin file creation = automatic eval failure.** ```bash # ✅ The ONLY way to add an API plugin — ALL operations in ONE call: -npx -y --package @microsoft/m365agentstoolkit-cli atk add action --api-plugin-type api-spec --openapi-spec-location --api-operation "GET /path,POST /path,PATCH /path/{id},DELETE /path/{id}" -i false +wiqd agent add action --openapi-spec --operations "GET /path,POST /path,PATCH /path/{id},DELETE /path/{id}" ``` -**After adding a plugin with `npx -y --package @microsoft/m365agentstoolkit-cli atk add action`, you MUST complete ALL of these — skipping any step is an eval failure:** +**After adding a plugin with `wiqd agent add action`, you MUST complete ALL of these — skipping any step is an eval failure:** **🔌 POST-PLUGIN MANDATORY STEPS (do ALL of these, in order):** 1. **Customize `ai-plugin.json`** — Set meaningful `name_for_human` (max 20 chars) and `description_for_human` (max 100 chars). Set a descriptive `description_for_model` on each function. NEVER leave defaults. @@ -124,7 +126,7 @@ npx -y --package @microsoft/m365agentstoolkit-cli atk add action --api-plugin-ty **After ANY capability or plugin change (add, remove, modify), complete this checklist:** 1. ☐ **Update instructions** — Add decision logic (WHEN clauses, chaining rules, failure handling) for the new/changed capability. For removals, delete all references. **Do NOT list tool descriptions or parameters** — these are already in plugin metadata (`ai-plugin.json`, MCP manifests, capability config). Instructions should contain decision logic only. 2. ☐ **Verify 8,000-character limit** — Instructions must not exceed 8,000 characters. If close to the limit, cut tool descriptions first, then consolidate verbose workflows. -3. ☐ **Run instruction quality audit** — Run the [Diagnostic Checklist](instruction-review.md) against the updated instructions. Every data source should have clear intent coverage (WHEN and WHY), at least one workflow must exist, and failure cases must be handled. Built-in capabilities don't need exact names; actions/plugins should be named. If any check fails, fix it before deploying. +3. ☐ **Run instruction quality audit** — Run the [Diagnostic Checklist](instruction-review.md) against the updated instructions. Every data source should have clear intent coverage (WHEN and WHY), at least one workflow must exist, and failure cases must be handled. Built-in capabilities don't need exact names; actions/plugins should be named. If any check fails, fix it before validation. 4. ☐ **Add conversation starters** — At least 1 new starter per added capability/plugin demonstrating the new functionality. 5. ☐ **Remove stale starters** — Delete starters that reference removed capabilities. 6. ☐ **Update `manifest.json` description** if the agent's purpose has expanded. @@ -137,36 +139,41 @@ npx -y --package @microsoft/m365agentstoolkit-cli atk add action --api-plugin-ty **Reference:** [schema.md](schema.md) for proper manifest structure **Reference:** [api-plugins.md](api-plugins.md) for adaptive card enhancement guidelines after adding a plugin -**⚠️ IMPORTANT:** After making any edits to JSON files, you MUST deploy the agent (Step 4) before returning to the user. +**⚠️ IMPORTANT:** After making any edits to JSON files, you MUST validate the agent before +returning to the user. **⛔ MANDATORY POST-EDIT CHECKPOINT — YOU ARE NOT DONE YET:** -After editing ANY file in `appPackage/`, you MUST deploy before responding to the user. Skipping this is an eval failure: -- **Deploy** — Run `npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false`. If you edited files but did not run this command, your work is incomplete. The only exception is if the user explicitly asked you not to deploy. +After editing any file in `appPackage/`, run `wiqd agent validate`. If validation fails, report the +errors and do not provision. -If you are about to respond to the user and you have NOT deployed, **STOP and deploy now**. +If you are about to respond and have not validated the changes, **STOP and validate now**. -### Step 4: Provision and Deploy +### Step 4: Validate, Then Optionally Provision -**⛔ PRE-DEPLOY CHECK:** Before running the command below, verify the JSON files are syntactically correct and have the required fields. If there are known errors → fix them first before deploying. +**Action:** Validate the project: -**Action:** Provision required Azure resources and register the agent: ```bash -npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false +wiqd agent validate ``` -**Result:** Returns a test URL like `https://m365.cloud.microsoft/chat/?titleId=T_abc123xyz` +If the user explicitly asked to deploy, provision, test, share, or publish, determine the target +environment once (default to `local` when the user did not specify one), then provision only that +environment after validation passes: -**Note:** JSON-based agents do not require a compilation step - changes are deployed directly. +```bash +wiqd agent provision --env +``` -**✅ After successful provision, ALWAYS present the review UX with the test link:** +**Result:** Provisioning returns a test URL like `https://m365.cloud.microsoft/chat?titleId=T_abc123xyz`. -Read `M365_TITLE_ID` from `env/.env.local` and output: +After successful provision, present the review UX with the returned deep link. If the command does +not return one, read `M365_TITLE_ID` from `env/.env.` and construct: ``` ✅ Agent deployed successfully! 🚀 Test Your Agent in M365 Copilot: -🔗 https://m365.cloud.microsoft/chat/?titleId={M365_TITLE_ID} +🔗 https://m365.cloud.microsoft/chat?titleId={M365_TITLE_ID} ``` **⛔ Never respond without this link.** If you deployed, the test link MUST appear in your response. This is not optional. @@ -182,42 +189,48 @@ Then wait for the user's response. - Test error handling and edge cases - Validate security controls -### Step 6: Deploy to Environments +### Step 6: Deploy to Additional Environments When Requested -**Action:** Deploy to staging/production environments: +Step 4 already provisions the requested environment. Provision another environment only when the +user explicitly requests an additional deployment. For example: ```bash -npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env prod --interactive false +wiqd agent provision --env dev ``` **Reference:** [deployment.md](deployment.md) for environment management and CI/CD patterns ### Step 7: Package and Share -**Action:** Package and share the agent: +Packaging alone does not require provisioning. Sharing does: before sharing, provision the target +environment if Step 4 did not already provision it. Use the same environment consistently: ```bash -# Package the agent -npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env dev --interactive false +# Required before sharing; omit for a package-only request +wiqd agent provision --env dev + +# Package the agent when requested +wiqd agent package --env dev # Share to tenant (for shared agents) -npx -y --package @microsoft/m365agentstoolkit-cli atk share --scope tenant --env dev +wiqd agent share --scope tenant --env dev ``` --- ## Critical Workflow Rules -### Always Deploy After Edits +### Always Validate After Edits -**RULE:** When making any changes to an agent (JSON manifest files, instructions, capabilities, API plugins), you MUST complete the following workflow before returning to the user: +**RULE:** When making any changes to an agent, complete this workflow before returning: -1. Provision/deploy the agent: `npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false` -2. Read `M365_TITLE_ID` from `env/.env.local` -3. Present the review UX with the test link: +1. Validate the agent: `wiqd agent validate` +2. Report validation errors and follow the workspace-gate error protocol. +3. Only if the user requested deployment, testing, sharing, or publishing, provision the requested + environment and present the returned deep link: ``` ✅ Agent deployed successfully! 🚀 Test Your Agent in M365 Copilot: - 🔗 https://m365.cloud.microsoft/chat/?titleId={M365_TITLE_ID} + 🔗 https://m365.cloud.microsoft/chat?titleId={M365_TITLE_ID} ``` **⛔ Never respond without this link after deploying.** @@ -240,10 +253,10 @@ npx -y --package @microsoft/m365agentstoolkit-cli atk share --scope tenant --env **STOP.** Before writing your response to the user, verify ALL of the following: -- [ ] I ran `npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false` and it succeeded -- [ ] I read `M365_TITLE_ID` from `env/.env.local` -- [ ] I presented the review UX with the `🚀 Test Your Agent in M365 Copilot:` link +- [ ] I ran `wiqd agent validate` and it succeeded +- [ ] If the user requested deployment, testing, sharing, or publishing, I provisioned the requested environment +- [ ] If I provisioned, I presented the returned deep link (or constructed it from `M365_TITLE_ID`) **If you cannot check ALL boxes, you are NOT done.** Go back and complete the missing steps. -This checklist applies to **EVERY turn** — not just the last turn in a multi-turn conversation. Even if you "only edited instructions," you must deploy before responding. +Validation applies after every edit. Provisioning remains an explicit user-requested operation. 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..9760aa1 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 @@ -15,10 +15,10 @@ Complete workflow for provisioning a JSON-based agent to a development environme npm install # Provision agent to development environment (no compile step needed for JSON agents) -npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false +wiqd agent provision --env local ``` -**Result:** Returns a test URL like `https://m365.cloud.microsoft/chat/?titleId=T_abc123xyz` to test the agent in Microsoft 365 Copilot. +**Result:** Returns a test URL like `https://m365.cloud.microsoft/chat?titleId=T_abc123xyz` to test the agent in Microsoft 365 Copilot. **Use case:** Testing agent functionality in a live environment during development. @@ -30,10 +30,10 @@ Workflow for provisioning and sharing an agent with your organization: ```bash # Provision agent to target environment -npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env dev --interactive false +wiqd agent provision --env dev # Share agent with tenant users -npx -y --package @microsoft/m365agentstoolkit-cli atk share --scope tenant --env dev +wiqd agent share --scope tenant --env dev ``` **Result:** Agent becomes available to all users in the Microsoft 365 tenant. @@ -48,7 +48,7 @@ Workflow for creating an agent package for distribution: ```bash # Package agent for distribution -npx -y --package @microsoft/m365agentstoolkit-cli atk package --env prod +wiqd agent package --env prod ``` **Result:** Creates a distributable package file that can be uploaded to the Microsoft 365 admin center or shared externally. 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..71eaca0 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 @@ -305,14 +305,19 @@ When reviewing instructions, follow this sequence: ### Phase 1: Inventory 1. Read `declarativeAgent.json` — list all capabilities, actions, conversation starters, and the schema version -2. Read `instructions.txt` (or inline instructions) — note the structure (or lack of it) -3. **Measure instruction length** — count the characters in `instructions.txt`. If inline, count the `instructions` field value. Record the count against the **8,000-character limit**. If over → flag immediately as a blocking issue. +2. Read the instruction file referenced by `declarativeAgent.json` (commonly `instruction.txt` or + `instructions.txt`), or the inline instructions — note the structure (or lack of it) +3. **Measure instruction length** — count the characters in the referenced instruction file. If + inline, count the `instructions` field value. Record the count against the **8,000-character + limit**. If over → flag immediately as a blocking issue. 4. If API plugins exist, read the `ai-plugin.json` to understand what functions are available and their parameter requirements 5. If MCP plugins exist, read the plugin manifest to understand what tools are available 6. Check the `version` field — note which GPT model era the instructions were likely written for 7. **Version upgrade analysis** — Cross-reference the current schema version against the capabilities implied by the instructions (use the Version-Capability Matrix below). If the instructions describe functionality that requires a newer schema version, flag it. Example: instructions say "review meeting transcripts" but the agent is on v1.4 — `Meetings` capability (which includes transcripts) requires v1.5+. -> **Quick length check:** `wc -m appPackage/instructions.txt` (Unix/macOS/WSL) or `(Get-Content appPackage/instructions.txt -Raw).Length` (PowerShell) +> **Quick length check:** Substitute the filename referenced by `declarativeAgent.json`, for +> example `wc -m appPackage/instruction.txt` (Unix/macOS/WSL) or +> `(Get-Content appPackage/instruction.txt -Raw).Length` (PowerShell). ### Phase 2: Comprehension Check 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..169b637 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 @@ -7,14 +7,14 @@ 1. ⛔ Tokenize `declarativeAgent.json` → replace `name`, `description`, all `conversation_starters[].title` and `.text` with `[[token]]` syntax 2. ⛔ Create language files → `en.json` (default) + one per additional language, each with `name.short`, `name.full`, `description.short`, `description.full`, and `localizationKeys` mapping EVERY token 3. ⛔ Update `manifest.json` → add `localizationInfo` with `defaultLanguageTag`, `defaultLanguageFile`, `additionalLanguages` -4. ⛔ Deploy → `npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false` +4. ⛔ Validate → `wiqd agent validate`; provision only for an explicit deploy, provision, test, share, or publish request **For adding a language to an already-localized agent (Workflow B):** 1. Read existing default language file to get the list of `localizationKeys` 2. Create new `{lang}.json` with the SAME set of keys, translated values 3. Add new entry to `additionalLanguages` in `manifest.json` -4. ⛔ Deploy +4. ⛔ Validate; provision only for an explicit deploy, provision, test, share, or publish request --- @@ -213,15 +213,17 @@ Add the `localizationInfo` section to `manifest.json`: - Language files live in `appPackage/` alongside the manifests - Use language-only tags (e.g., `en` rather than `en-us`) for top-level translations; add region-specific overrides only when needed -### Step A4: Deploy — MANDATORY +### Step A4: Validate — MANDATORY -After completing ALL localization changes, deploy the agent: +After completing all localization changes, validate the agent: ```bash -npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false +wiqd agent validate ``` -Then read `M365_TITLE_ID` from `env/.env.local` and present the test link. **⛔ Never skip deployment after localization changes.** +If validation fails, report the errors and follow the workspace-gate error protocol. Provision +only for an explicit deploy, provision, test, share, or publish request after validation passes; +if provisioned, present the returned deep link. --- @@ -260,15 +262,16 @@ Add the new language to the `additionalLanguages` array: **⛔ Do NOT modify existing language files or the `defaultLanguageFile` entry.** Only add to `additionalLanguages`. -### Step B4: Deploy — MANDATORY +### Step B4: Validate — MANDATORY -Deploy the agent: +Validate the agent: ```bash -npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false +wiqd agent validate ``` -Then present the test link. **⛔ Never skip deployment.** +Provision only for an explicit deploy, provision, test, share, or publish request; if provisioned, +present the returned deep link. --- @@ -348,7 +351,7 @@ my-agent/ 2. **Keep token names descriptive** — use `starter_vpn_title` not `key1`. 3. **Do NOT localize instructions** — externalize to `instructions.txt` via `$[file]('instructions.txt')`. Never use `[[tokens]]` for instructions. 4. **Schema version consistency** — `$schema` in language files must match `manifest.json`. -5. **Always deploy after localization changes.** +5. **Always validate after localization changes; provision only when explicitly requested.** 6. **Do NOT invent translations** — ask the user for translated strings. Never machine-translate without confirmation. 7. **Tokenization is MANDATORY** — language files have no effect without `[[token]]` syntax in the manifests. @@ -363,8 +366,8 @@ my-agent/ - [ ] A default language file exists (e.g., `en.json`) with `name.short`, `name.full`, `description.short`, `description.full`, and ALL `localizationKeys` - [ ] Every additional language file has the EXACT SAME set of `localizationKeys` as the default - [ ] `manifest.json` has `localizationInfo` with `defaultLanguageTag`, `defaultLanguageFile`, and `additionalLanguages` -- [ ] I deployed with `npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false` -- [ ] I presented the test link +- [ ] I validated with `wiqd agent validate` +- [ ] If the user requested deployment, provisioning, testing, sharing, or publishing, I provisioned and presented the returned deep link **If you cannot check ALL boxes, you are NOT done.** Go back and complete the missing steps. diff --git a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/mcp-plugin.md b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/mcp-plugin.md index 547553b..eb18579 100644 --- a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/mcp-plugin.md +++ b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/mcp-plugin.md @@ -8,11 +8,15 @@ This guide explains how to integrate Model Context Protocol (MCP) servers as act MCP servers expose tools that can be consumed by your agent. Unlike OpenAPI-based plugins, MCP plugins use a `RemoteMCPServer` runtime type and embed the tool descriptions directly in the plugin manifest. -> **⚠️ IMPORTANT:** `npx -y --package @microsoft/m365agentstoolkit-cli atk add action` does NOT support MCP servers — it only supports `--api-plugin-type api-spec` for OpenAPI plugins. MCP plugins MUST be created manually following the steps below. This is NOT a violation of the "Always Use `npx -y --package @microsoft/m365agentstoolkit-cli atk add action`" rule — that rule applies only to OpenAPI/REST API plugins. +> **⚠️ IMPORTANT:** Use `wiqd agent add action --mcp-server-url` to create and register the +> MCP plugin. Do not create the initial plugin manifest manually. The detailed manifest sections +> below are retained for reviewing generated output and for advanced customization such as +> pinning discovered tools or adding response semantics. Follow Step 2 to select an authentication +> mode and supply all credentials required by that mode. ## Prerequisites -- MCP server URL (must be accessible via HTTP/HTTPS) +- MCP server URL (must use HTTPS and must not contain embedded credentials) - Node.js installed (for `mcp-remote` authentication helper) - Logo images for the agent (color.png 192×192 and outline.png 32×32) — optional, see [Step 5: Logo Images](#step-5-logo-images-optional) @@ -20,13 +24,10 @@ MCP servers expose tools that can be consumed by your agent. Unlike OpenAPI-base ## Scaffold the Agent Project First -Before adding an MCP plugin, you **must** have a scaffolded agent project. Run `npx -y --package @microsoft/m365agentstoolkit-cli atk new` if you haven't already: +Before adding an MCP plugin, you **must** have a scaffolded agent project. Run `wiqd agent create` if you haven't already: ```bash -npx -y --package @microsoft/m365agentstoolkit-cli atk new \ - -n my-agent \ - -c declarative-agent \ - -i false +wiqd agent create --name my-agent ``` This creates `m365agents.yml` (and `m365agents.local.yml`) with the **5 required lifecycle steps**: @@ -39,13 +40,17 @@ This creates `m365agents.yml` (and `m365agents.local.yml`) with the **5 required | 4 | `teamsApp/update` | Uploads the package to Teams | | 5 | `teamsApp/extendToM365` | **Extends the app to M365 Copilot** — generates `M365_TITLE_ID` | -**What breaks without `extendToM365`:** If this step is missing, `npx -y --package @microsoft/m365agentstoolkit-cli atk provision` will register the Teams app and generate `TEAMS_APP_ID`, but the agent will **never appear in Copilot Chat** because no `M365_TITLE_ID` is generated. This is the most common reason for "provision succeeded but agent not found" failures. +**What breaks without `extendToM365`:** If this step is missing, `wiqd agent provision` will register the Teams app and generate `TEAMS_APP_ID`, but the agent will **never appear in Copilot Chat** because no `M365_TITLE_ID` is generated. This is the most common reason for "provision succeeded but agent not found" failures. > **If you already have a project** but are missing `teamsApp/extendToM365`, add it to the `provision` lifecycle in `m365agents.yml` after `teamsApp/update`. See [deployment.md](deployment.md) for the full provisioning reference. --- -## Step-by-Step Integration +## Generated Plugin Review and Advanced Customization + +Run `wiqd agent add action --mcp-server-url` first. The steps below explain how to inspect and, +when requested, augment the generated plugin. If the command fails, report the error and stop; +do not fall back to manual creation. ### Step 1: Get MCP Server URL @@ -53,7 +58,7 @@ Ask the user for the MCP server URL. Example: `https://learn.microsoft.com/api/m Derive the **server root** (scheme + host only): e.g., `https://learn.microsoft.com` -### Step 2: Detect Authentication Requirements +### Step 2: Select Authentication and Add the MCP Action Before discovering tools, determine if the MCP server requires OAuth authentication. @@ -65,14 +70,49 @@ curl -s /.well-known/openid-configuration ``` **Decision:** -- **OAuth metadata found** (either endpoint returns valid JSON with `authorization_endpoint`) → the server requires authentication. Follow [authentication.md](authentication.md) Steps 1-3 to discover endpoints, obtain credentials, and configure `oauth/register` in both `m365agents.yml` and `m365agents.local.yml`. Then continue to [Step 3](#step-3-discover-mcp-tools-mandatory) below for authenticated tool discovery. -- **No OAuth metadata** (both return 404 or non-JSON) → the server is unauthenticated. Skip directly to [Step 3](#step-3-discover-mcp-tools-mandatory) for unauthenticated tool discovery. +- **OAuth metadata found** (either endpoint returns valid JSON with `authorization_endpoint`) → ask the user to choose `oauth`, `oauth-dynamic`, or `entra-sso`, then collect the inputs required below. +- **No OAuth metadata** (both return 404 or non-JSON) → use `none`. + +Run the command for the selected mode: + +```bash +# No authentication +wiqd agent add action \ + --mcp-server-url "" \ + --mcp-auth-type none + +# OAuth dynamic client registration +wiqd agent add action \ + --mcp-server-url "" \ + --mcp-auth-type oauth-dynamic + +# Static OAuth +wiqd agent add action \ + --mcp-server-url "" \ + --mcp-auth-type oauth \ + --mcp-client-id "" \ + --mcp-client-secret "" \ + --mcp-scopes "" + +# Microsoft Entra SSO +wiqd agent add action \ + --mcp-server-url "" \ + --mcp-auth-type entra-sso \ + --mcp-client-id "" +``` + +`--mcp-scopes` is optional for static OAuth. Do not run a command containing unresolved +placeholders, and never invent credentials. -### Step 3: Discover MCP Tools (MANDATORY) +The command creates the plugin manifest, registers it in the agent manifest, and configures the +required authentication lifecycle. Review any discovery or configuration warnings before +continuing. -🚨 **THIS STEP IS MANDATORY — DO NOT SKIP** +### Step 3: Discover MCP Tools When Pinning (Optional) -You MUST discover tools via the MCP protocol directly. Tool discovery uses HTTP POST requests to the MCP server URL. +Dynamic discovery is the default. Perform direct MCP tool discovery only when the user asks to +pin selected tools or when advanced customization requires inline tool metadata. Tool discovery +uses HTTP POST requests to the MCP server URL. #### 3a. Authenticate (OAuth servers only) @@ -202,17 +242,18 @@ EXTRACT_TOOLS > **⚠️ IMPORTANT:** The example above shows commonly seen fields (`annotations`, `execution`, `_meta`), but MCP servers may return **any** additional properties on tool objects. You **MUST** preserve every property returned by tools/list — copy each tool object in its entirety into `mcp_tool_description.tools[]`. Do NOT cherry-pick known fields; treat the tools/list output as the source of truth and inline it verbatim. -#### 3c. Use All Discovered Tools +#### 3c. Select Tools to Pin -**Include ALL tools** returned by `tools/list` in the plugin manifest. Do NOT filter or exclude tools unless the developer explicitly asks to limit the tool set. +Pin only the tools requested by the developer. If the developer asks to pin every tool, include +all tools returned by `tools/list`. **Copy each tool object verbatim** — every property the server returns (`name`, `description`, `inputSchema`, `annotations`, `execution`, `_meta`, `outputSchema`, `title`, or any other field) must be preserved in `mcp_tool_description.tools[]`. Do NOT maintain a hardcoded list of "known" fields — the MCP protocol evolves and servers may return new properties at any time. Tell the user how many tools were discovered and confirm they will all be included. -### Step 4: Create the Plugin Manifest +### Step 4: Review the Generated Plugin Manifest -Create `{name}-plugin.json` in the `appPackage` folder: +Locate the generated `{name}-plugin.json` in the `appPackage` folder: ```json { @@ -233,9 +274,12 @@ Create `{name}-plugin.json` in the `appPackage` folder: | `description_for_human` | Brief description of the plugin (max 100 characters) | | `namespace` | Unique identifier, lowercase alphanumeric only (no hyphens, no underscores) | -### Step 4a: Add Functions from Discovered Tools +### Step 4a: Add Functions for Pinned Tools -For EACH discovered tool from Step 3, add a function entry with `name`, `description`, and `capabilities` only. Do **NOT** duplicate `parameters`/`inputSchema` in the function — all tool schema data lives exclusively in `mcp_tool_description.tools[]` (see Step 6). +For each tool selected in Step 3, add a function entry with `name`, `description`, and +`capabilities` only. Do **NOT** duplicate `parameters`/`inputSchema` in the function — all tool +schema data lives exclusively in `mcp_tool_description.tools[]` (see Step 6). If no tools are +pinned, keep the generated `functions` array empty. ```json { @@ -336,7 +380,7 @@ For each tool: ### Step 5: Logo Images (Optional) -Logos are **not mandatory**. The default logos from `npx -y --package @microsoft/m365agentstoolkit-cli atk new` work fine. Ask the user casually: +Logos are **not mandatory**. The default logos from `wiqd agent create` work fine. Ask the user casually: > "Would you like to use a custom logo for [name], or is the default fine?" @@ -373,9 +417,11 @@ Output files: `appPackage/color.png` (192×192) and `appPackage/outline.png` (32 Show the resulting icon(s) to the user for approval before proceeding. If the user rejects, ask them to provide their own images and do NOT proceed until approved. -### Step 6: Configure the Runtime +### Step 6: Review or Customize the Generated Runtime -Add the `RemoteMCPServer` runtime with the tools inlined in `mcp_tool_description.tools`: +For pinned-tool customization, update the generated `RemoteMCPServer` runtime with the selected +tools inlined in `mcp_tool_description.tools`. Otherwise, preserve the generated dynamic-discovery +runtime. **For authenticated servers** (see [authentication.md](authentication.md)): ```json @@ -441,9 +487,10 @@ Add the `RemoteMCPServer` runtime with the tools inlined in `mcp_tool_descriptio > - Do NOT fabricate properties that the server did not return. Only include what tools/list actually gives you. > - For authenticated servers, both `m365agents.yml` and `m365agents.local.yml` must include the `oauth/register` step — see [authentication.md](authentication.md). -### Step 7: Register Plugin in Agent Manifest +### Step 7: Verify Plugin Registration in the Agent Manifest -Add the plugin to your `declarative-agent.json`: +Verify that `wiqd agent add action` added the plugin to `declarative-agent.json`. Do not add a +duplicate action: ```json { @@ -461,17 +508,16 @@ Add the plugin to your `declarative-agent.json`: ## Complete Workflow Checklist ``` -□ Step 0: Scaffold agent project with `npx -y --package @microsoft/m365agentstoolkit-cli atk new` (if not already scaffolded) ← MANDATORY +□ Step 0: Scaffold agent project with `wiqd agent create` (if not already scaffolded) ← MANDATORY □ Step 1: Get MCP server URL from user -□ Step 2: Detect authentication requirements (probe well-known endpoints) -□ → If OAuth: follow authentication.md (discover endpoints, get creds, configure oauth/register) -□ Step 3: Discover tools via MCP protocol (initialize → tools/list) ← MANDATORY -□ → Include ALL tools (do not filter unless developer explicitly requests it) -□ Step 4: Create {name}-plugin.json with functions + response_semantics +□ Step 2: Select authentication and run `wiqd agent add action --mcp-server-url` +□ Step 3: If pinning tools, discover them via MCP protocol (initialize → tools/list) +□ → Include the selected tools exactly as returned +□ Step 4: Review the generated {name}-plugin.json; add pinned functions or response_semantics only when needed □ Step 5: Ask user about custom logo (optional — skip if user declines) -□ Step 6: Add runtime with RemoteMCPServer type (OAuthPluginVault or None) -□ Step 7: Register plugin in declarativeAgent.json -□ Step 8: Run npx -y --package @microsoft/m365agentstoolkit-cli atk provision --env local --interactive false +□ Step 6: Review or customize the generated RemoteMCPServer runtime +□ Step 7: Verify the generated action registration in declarativeAgent.json +□ Step 8: Run `wiqd agent validate`; provision only for an explicit deploy, provision, test, share, or publish request ``` --- @@ -625,7 +671,7 @@ For the Zava Insurance MCP server at `https://zava-insurance-mcp.azurewebsites.n > **Note how tools with UI widgets** (e.g., `show-claims-dashboard`, `show-claim-detail`, `show-contractors`) include `annotations`, `execution`, AND `_meta` with `resourceUri` — all copied verbatim from the tools/list response. Tools without UI (e.g., `update-claim-status`) still include `execution` when the server returned it, but omit `annotations` and `_meta` since the server didn't provide them. -Register in `declarative-agent.json`: `{ "actions": [{ "id": "zavaPlugin", "file": "zava-plugin.json" }] }` +Verify the generated registration in `declarative-agent.json`: `{ "actions": [{ "id": "zavaPlugin", "file": "zava-plugin.json" }] }` --- @@ -713,21 +759,20 @@ You can integrate multiple MCP servers by adding multiple runtimes, each with it ## Best Practices -1. **Always discover tools via MCP protocol** — run the full handshake (initialize → notifications/initialized → tools/list) before writing the plugin manifest. **NEVER fabricate tool names or descriptions.** -2. **Full-fidelity tool copying in `mcp_tool_description.tools`** — each tool object must be a verbatim copy of the tools/list output. Copy every property exactly as returned (`inputSchema`, `annotations`, `execution`, `_meta`, `outputSchema`, `title`, and any other field). The MCP protocol evolves — do NOT maintain a hardcoded allowlist of known fields. If the server returns it, the plugin must include it. Never abbreviate, omit, or rename properties. Do NOT duplicate `inputSchema` or other properties in `functions[]`. -3. **Inline tools in `mcp_tool_description.tools`** — do NOT use a separate tools file; embed the tools array directly in the runtime spec +1. **Use dynamic discovery by default** — do not pin tools unless the developer requests a fixed tool set or advanced customization requires inline metadata. +2. **Discover before pinning** — run the full MCP handshake (initialize → notifications/initialized → tools/list), and never fabricate tool names or descriptions. +3. **Preserve pinned tools exactly** — copy every property returned by `tools/list` into `mcp_tool_description.tools`; do not use a separate tools file or duplicate schema properties in `functions[]`. 4. **Match function names exactly** — copy tool names directly from the tools/list output 5. **Always add response semantics** — every function must have `capabilities.response_semantics`, even if using the default (empty body) pattern -6. **Include all tools by default** — inline every tool from `tools/list` unless the developer explicitly asks to limit the set; for all included tools always keep the complete tool object with all properties -7. **Logos are optional** — ask the user if they want a custom logo; if not, use the defaults from `npx -y --package @microsoft/m365agentstoolkit-cli atk new`. Logos must be **PNG only** (no JPG, SVG, etc.) +6. **Pin only the requested tools** — preserve the generated dynamic-discovery configuration when no fixed tool set is requested +7. **Logos are optional** — ask the user if they want a custom logo; if not, use the defaults from `wiqd agent create`. Logos must be **PNG only** (no JPG, SVG, etc.) --- -## Next Step — Add Entra SSO (optional) - -If the MCP server is **your own** (e.g. scaffolded with `create-mcp-app` or `ui-widget-developer`, running on a devtunnel) and you want it to receive the **signed-in M365 user's verified identity** — Entra SSO, no separate login — the companion **`setup-sso-ui-widget`** skill (in this same `microsoft-365-agents-toolkit` plugin) automates every step on top of the plugin you just added: Entra app registration, ATK OAuth (`MicrosoftEntra`), flipping the manifest's `runtimes[].auth` from `None` → `OAuthPluginVault`, a minimal JWKS bearer-token guard in the server, and sideload. It auto-detects and supports **both** the Express (MCP Apps) and raw-http (OAI Apps) server layouts. SSO only — no OBO. - -> This closes the **create-mcp-app → add MCP plugin (here) → SSO** path: `create-mcp-app` emits a standalone MCP server, this integration wraps it into the declarative agent (`declarativeAgent.json` + `{name}-plugin.json` + `m365agents.yml`), and `setup-sso-ui-widget` adds Entra SSO to that wrapped agent. +## Microsoft Entra SSO -**Tell the user** (after the MCP plugin is added, the server is running, and the agent is provisioned): -> **Your MCP plugin is wired into the agent.** 🎉 Want me to add **Entra SSO** next, so your tools get the signed-in user's verified identity? I can run the **`setup-sso-ui-widget`** skill — just say the word. (SSO only, no OBO.) +For a new MCP action, configure Entra SSO during generation with +`--mcp-auth-type entra-sso --mcp-client-id ""` as shown in Step 2. For an existing +generated action, use [authentication.md](authentication.md) to review the required manifest and +lifecycle configuration, then validate and provision through wiqd. Do not route this workflow +through a setup path that directly invokes ATK lifecycle commands. diff --git a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/scaffolding-workflow.md b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/scaffolding-workflow.md index 9c42d28..d687349 100644 --- a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/scaffolding-workflow.md +++ b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/scaffolding-workflow.md @@ -4,27 +4,29 @@ Step-by-step instructions for scaffolding a new M365 Copilot agent project. ## ⛔ STOP — READ THIS FIRST -### ATK CLI Setup +### wiqd CLI Setup -Check if ATK CLI is available by running `npx -y --package @microsoft/m365agentstoolkit-cli atk --version`. If the command is not found, **STOP and tell the user** that the ATK CLI is required but not installed. Do NOT attempt to install it yourself — the user must install ATK separately before you can proceed. +Check if wiqd CLI is available by running `wiqd --version`. If the command is not found, **STOP +and tell the user** that the wiqd CLI is required but not installed. Direct them to the +[official wiqd installation guide](https://microsoft.github.io/wiqd/getting-started/installation/) for the current installation guidance +instead of duplicating platform-specific installer commands here. ### The Only Valid Command Copy this command EXACTLY. Replace `` with the user's project name: ```bash -npx -y --package @microsoft/m365agentstoolkit-cli atk new -n -c declarative-agent -with-plugin no -i false +wiqd agent create --name ``` ### Forbidden Commands — These Do Not Exist | ❌ Invalid Command | Why It Fails | |-------------------|--------------| -| `npx -y --package @microsoft/m365agentstoolkit-cli atk init` | DOES NOT EXIST — there is no init command | -| `npx -y --package @microsoft/m365agentstoolkit-cli atk init --template` | DOES NOT EXIST — there is no init or --template flag | -| `npx -y --package @microsoft/m365agentstoolkit-cli atk create` | DOES NOT EXIST — there is no create command | -| `npx -y --package @microsoft/m365agentstoolkit-cli atk scaffold` | DOES NOT EXIST — there is no scaffold command | -| `--template anything` | DOES NOT EXIST — there is no --template flag | +| `wiqd agent init` | DOES NOT EXIST — use `wiqd agent create` | +| `wiqd create` | DOES NOT EXIST — the `agent` noun is required | +| `wiqd agent scaffold` | DOES NOT EXIST — use `wiqd agent create` | +| `wiqd agent new` | DOES NOT EXIST — use `wiqd agent create` | --- @@ -64,17 +66,15 @@ npx -y --package @microsoft/m365agentstoolkit-cli atk new -n -c d - ✅ Good: `sales-dashboard`, `document-finder`, `hr-faq-agent` - ❌ Bad: `agent1`, `test`, `ExpenseTrackerAgent`, `my project` -### Step 3: Run ATK CLI Command and Move Files +### Step 3: Run wiqd CLI Command and Move Files -**Action:** Execute the scaffolding command, then move files from the ATK-created subfolder to the current directory. - -Always use `-i false` (non-interactive mode) to prevent unexpected prompts. +**Action:** Execute the scaffolding command, then move files from the wiqd-created subfolder to the current directory. **Commands to execute sequentially:** 1. **Create the project:** ```bash -npx -y --package @microsoft/m365agentstoolkit-cli atk new -n -c declarative-agent -with-plugin no -i false +wiqd agent create --name ``` 2. **Move all files from the subfolder to current directory:** @@ -88,8 +88,10 @@ rmdir ``` 4. **Verify success:** -- Check that key files exist in the current directory (`package.json`, `m365agents.yml`) -- Confirm the ATK-created subfolder was removed +- Check that `m365agents.yml`, `appPackage/manifest.json`, and + `appPackage/declarativeAgent.json` exist in the current directory +- Read the `instructions` property in `declarativeAgent.json` and verify that its referenced file exists +- Confirm the wiqd-created subfolder was removed - If the command fails, report the error and stop — do NOT retry automatically ### Step 4: Add Agent Context Files @@ -110,7 +112,7 @@ rmdir ````markdown # M365 Declarative Agent Project -This is an M365 Copilot declarative agent project managed by the ATK CLI. +This is an M365 Copilot declarative agent project managed by the wiqd CLI. ## Available Skills @@ -120,7 +122,6 @@ When working on this project, you MUST use the appropriate skill for the task. * |-------|-------------| | **declarative-agent-developer** | Any task involving this agent (see scenarios below). **This is the primary skill for this project.** | | **ui-widget-developer** | Only when adding an MCP server that renders rich interactive widgets (HTML) in Copilot Chat using the OpenAI Apps SDK. | -| **install-atk** | Only when the ATK CLI is not installed or needs updating. | ## ⛔ MANDATORY: Invoke `declarative-agent-developer` Skill First @@ -137,13 +138,13 @@ When working on this project, you MUST use the appropriate skill for the task. * - Localizing an agent into multiple languages - Adding a new language to an already-localized agent - Writing or updating agent instructions -- Deploying and provisioning with `atk provision` -- Validating the project with `atk validate` +- Deploying and provisioning with `wiqd agent provision` +- Validating the project with `wiqd agent validate` - Fixing manifest errors or validation failures **Do NOT:** - Edit `declarativeAgent.json` or other manifest files directly without the skill -- Run `npx -y --package @microsoft/m365agentstoolkit-cli atk` commands without the skill +- Run `wiqd` commands without the skill - "Help" by manually making changes — always delegate to the skill ```` @@ -186,8 +187,8 @@ This workflow **only** handles project creation and agent context setup. After s | Error | Action | |-------|--------| -| ATK CLI not installed | Stop. Tell the user to install ATK first. | +| wiqd CLI not installed | Stop. Direct the user to the [official wiqd installation guide](https://microsoft.github.io/wiqd/getting-started/installation/) for current installation guidance. | | Directory not empty | Stop. Show error message. Do not proceed. | | Invalid project name | Warn and suggest a corrected name. | -| `npx -y --package @microsoft/m365agentstoolkit-cli atk new` command fails | Report the error with full output. Do not retry. | +| `wiqd agent create` command fails | Report the error with full output. Do not retry. | | File move fails | Report the error. Files may still be in the subfolder. | diff --git a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/workspace-gates.md b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/workspace-gates.md index afb0869..997cde7 100644 --- a/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/workspace-gates.md +++ b/plugins/microsoft-365-agents-toolkit/skills/declarative-agent-developer/references/workspace-gates.md @@ -10,7 +10,7 @@ This document contains detailed rules for workspace detection, gate scenarios, a 1. **If `declarativeAgent.json` does NOT exist and the user asked to edit/modify/add/deploy → REJECT.** Respond with text only. Do NOT create the file. Do NOT create `appPackage/`. Do NOT look at other directories for examples to copy. 2. **If `declarativeAgent.json` has malformed JSON → DETECT first, then INFORM, then ASK.** You must parse the file and report errors to the user BEFORE making any edits. Never edit a broken file without first telling the user it's broken. -3. **If validation finds errors → NEVER run `npx -y --package @microsoft/m365agentstoolkit-cli atk provision`.** There are zero exceptions. Report errors and ask the user. +3. **If validation finds errors → NEVER run `wiqd agent provision`.** There are zero exceptions. Report errors and ask the user. **The "Detect → Inform → Ask" protocol is mandatory for ALL error states:** - **Detect**: Identify the problem (missing file, parse error, validation error) @@ -49,8 +49,8 @@ No `appPackage/declarativeAgent.json` exists but user implies an existing agent - ❌ Creating `declarativeAgent.json` from scratch to "help" the user - ❌ Creating the `appPackage/` directory - ❌ Looking at other directories/fixtures for examples and copying them -- ❌ Running `npx -y --package @microsoft/m365agentstoolkit-cli atk new` when the user asked to edit (editing ≠ scaffolding) -- ❌ Running ANY `npx -y --package @microsoft/m365agentstoolkit-cli atk` command — the project is not an agent project +- ❌ Running `wiqd agent create` when the user asked to edit (editing ≠ scaffolding) +- ❌ Running ANY `wiqd` command — the project is not an agent project **Example rejection:** ``` @@ -78,7 +78,7 @@ User explicitly says "create a new agent", "scaffold", "start from scratch". The - Parse and check `declarativeAgent.json` against the expected schema - Report ALL errors to the user with specific details - ASK the user before making changes -- **Do NOT** run `npx -y --package @microsoft/m365agentstoolkit-cli atk provision` — fix errors first, no exceptions +- **Do NOT** run `wiqd agent provision` — fix errors first, no exceptions - **Do NOT** silently rewrite the entire file — surgical fixes only - **Do NOT** invent placeholder values for missing required fields @@ -90,12 +90,12 @@ User explicitly says "create a new agent", "scaffold", "start from scratch". The 3. **ASK**: Ask the user if you should fix the syntax errors. Wait for their response. 4. **FIX** (only after user confirms): Fix with surgical edits (not a rewrite — if you're changing >20% of lines, stop and reconsider) 5. **VALIDATE**: Check the manifest against the schema after fixing -6. **DO NOT DEPLOY**: Even after fixing, do NOT run `npx -y --package @microsoft/m365agentstoolkit-cli atk provision` until the user's original request is also addressed and validation passes cleanly +6. **DO NOT DEPLOY**: Even after fixing, do NOT run `wiqd agent provision` until the user's original request is also addressed and validation passes cleanly **⛔ Malformed JSON anti-patterns that WILL cause eval failure:** - ❌ Reading the file and immediately editing it without telling the user it's broken - ❌ Fixing JSON errors as part of a larger edit (fix syntax → inform → ask, THEN handle the user's request separately) -- ❌ Running `npx -y --package @microsoft/m365agentstoolkit-cli atk provision` after fixing syntax errors +- ❌ Running `wiqd agent provision` after fixing syntax errors - ❌ Validating AFTER editing instead of detecting errors BEFORE editing - ❌ Mentioning malformed JSON only in a summary at the end instead of upfront @@ -122,9 +122,9 @@ User explicitly says "create a new agent", "scaffold", "start from scratch". The | Scenario | What you see | What you MUST do | What you MUST NOT do | |----------|-------------|-----------------|---------------------| -| Express/React/Node app | `package.json` + `src/index.js` but NO `appPackage/` | Text-only: tell user this is NOT an agent project | ❌ Create `appPackage/` ❌ Run `npx -y --package @microsoft/m365agentstoolkit-cli atk new` ❌ Create ANY files | +| Express/React/Node app | `package.json` + `src/index.js` but NO `appPackage/` | Text-only: tell user this is NOT an agent project | ❌ Create `appPackage/` ❌ Run `wiqd agent create` ❌ Create ANY files | | No manifest, edit request | No `declarativeAgent.json`, user says "add capability" | Text-only: explain manifest is missing | ❌ Create files ❌ Scaffold ❌ "Help" by creating missing files | -| Manifest missing fields | `declarativeAgent.json` missing `name`/`description`/`instructions` | List ALL missing fields, ASK user | ❌ Invent placeholders ❌ Auto-fill ❌ Run `npx -y --package @microsoft/m365agentstoolkit-cli atk provision` | +| Manifest missing fields | `declarativeAgent.json` missing `name`/`description`/`instructions` | List ALL missing fields, ASK user | ❌ Invent placeholders ❌ Auto-fill ❌ Run `wiqd agent provision` | | Manifest has errors | Manifest has structural/schema errors | Report ALL errors, suggest fixes, ask user | ❌ Silently fix ❌ Deploy ❌ Auto-correct | | Valid project, behavior issues | Valid manifest, user says "agent doesn't work well" | Run Instruction Review workflow (5 phases) | ❌ Jump to editing without diagnosis ❌ Deploy without review ❌ Rewrite without user approval | @@ -150,8 +150,8 @@ These will cause eval failure: - ❌ Mentioning "the file had malformed JSON" only in a final summary **Deployment violations:** -- ❌ Running `npx -y --package @microsoft/m365agentstoolkit-cli atk provision` when validation found errors — not even "to test" -- ❌ Running `npx -y --package @microsoft/m365agentstoolkit-cli atk provision` "to see what happens" +- ❌ Running `wiqd agent provision` when validation found errors — not even "to test" +- ❌ Running `wiqd agent provision` "to see what happens" - ❌ Auto-correcting errors and deploying without asking - ❌ Deploying "for educational purposes" to show error output