Add Ai Webapi

> Plugin check: Run node "${PLUGIN_ROOT}/scripts/check-version.js" — if it outputs a message, show it to the user before proceeding.

Add AI Web API

> Note > > AI summarization APIs are a preview feature. Preview features aren't meant for production use and may have restricted functionality. These features are available before an official release so that customers can get early access and provide feedback.

Surface this note to the user verbatim during Phase 1 and again in the Phase 8 summary — copy the exact **Note** block above (including its wording about "available before an official release so that customers can get early access and provide feedback"). Do not paraphrase it into your own "Preview-feature note: ..." sentence; the wording matches the Microsoft Learn preview disclaimer and rephrasing it loses that fidelity.

Integrate Power Pages generative-AI summarization APIs into a SPA site. This skill focuses on the AI layer (Layer 3): the summarization service code and the Summarization/* site settings. The underlying Web API prerequisites — Webapi//enabled, Webapi//fields, table permissions, and web roles — are delegated to /integrate-webapi and /create-webroles so there is a single source of truth for every layer.

The two APIs covered

| # | API | URL | Body | Response | |---|-----|-----|------|----------| | 1 | Search Summary | POST /_api/search/v1.0/summary | { userQuery } | { Summary, Citations } | | 2 | Data Summarization | POST /_api/summarization/data/v1.0/()?$select=...&$expand=... | { InstructionIdentifier } or { RecommendationConfig } | { Summary, Recommendations } |

> Example: Microsoft-shipped Copilot summary on a support-case page. Data Summarization can be > called with any combination of entity set, columns, and prompt — but Microsoft documents and > ships one specific configuration for the standard incident table: > POST /_api/summarization/data/v1.0/incidents()?$select=description,title&$expand=incident_adx_portalcomments($select=description) > with body { "InstructionIdentifier": "Summarization/prompt/case_summary" }. This is sometimes > called the "Case-page Copilot preset" in Microsoft Learn. Treat it as one possible Data > Summarization recipe — useful when the user explicitly wants to mirror the Microsoft sample — > not as an automatic recommendation. A custom case-like table (cr363_servicerequest, > adx_case), or the standard incident table summarised on different facets (priority, owner, > SLA timer), is just a regular Data Summarization call with maker-defined values.

> Reference: ${PLUGIN_ROOT}/skills/add-ai-webapi/references/ai-api-reference.md — canonical > API shapes, required headers, site-setting names, error codes, and the documented support-case > example. Read this at the start of the workflow; fetch the Microsoft Learn source pages with > mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch if the user asks for the latest.

> Admin governance hierarchy: both APIs are gated by a three-level admin > hierarchy — tenant PowerShell setting (enableGenerativeAIFeaturesForSiteUsers), Copilot Hub > environment/site governance, and the site-level maker toggle (for Search Summary: Set up > workspace → Copilot → Site search (preview) → Enable Site search with generative AI (preview)). > Each level overrides the one below it, so "the maker toggle is on but the API still says > disabled" is a real scenario — admin-level governance wins. > > The two endpoints surface disablement differently: > > - Search Summary → HTTP 200 with an embedded envelope { Code: 400, Message: "Gen AI > Search is disabled." }. The generated fetchSearchSummary detects this and throws > SearchSummaryApiError; the UI renders a remediation card. > - Data Summarization → HTTP 400 with error.code = 90041001 (admin-level disabled) or > 90041003 (per-site Summarization/Data/Enable=false). > > Full troubleshooting checklist (tenant → environment → site, plus runtime version, Bing > dependency, and cross-region data movement) lives in > references/ai-api-reference.md §1 "Troubleshooting: AI feature appears disabled (admin > hierarchy)" — point users there when either disablement shape surfaces. Mention this governance > hierarchy explicitly to the user before Phase 7, and again in the Phase 8 summary.

> Built-in search control vs. custom code path: if the site uses the Microsoft-shipped Power > Pages search control and only wants AI-summarised search results on that page, they don't > need this skill — just the Copilot workspace toggle and the Search/Summary/Title content > snippet. This skill is for sites that build their own search UI or need to call > /_api/search/v1.0/summary from custom code. Confirm which path the user is on in Phase 1.

Core principles

• Layer 3 only, delegate the rest. Web API site settings, table permissions, and web roles all belong to /integrate-webapi and /create-webroles. This skill creates the summarization service code and the Summarization/* site settings — nothing else.
• Sequential agent spawning. Per plugins/power-pages/AGENTS.md, spawn the ai-webapi-integration agent sequentially per target (never in parallel). The first call establishes the shared summarization service file and CSRF helper; subsequent calls extend it. ai-webapi-settings-architect runs alone, after all code integrations land.
• Raw fetch + CSRF. Every summarization request attaches __RequestVerificationToken (from /_layout/tokenhtml) and X-Requested-With: XMLHttpRequest. Never route through an OData wrapper.
• Skip /integrate-webapi when it's not needed. If every confirmed target is Search Summary (which has no per-table Web API prerequisites), or every Layer 1/2 prerequisite already exists on disk, the skill goes straight from Phase 3 to Phase 5.
• Use TaskCreate/TaskUpdate — create the todo list upfront with all phases before starting.

> Prerequisites: > > - An existing Power Pages SPA site created via /create-site > - A Dataverse data model (tables + columns) set up via /setup-datamodel or manually — for any > Data Summarization target > - The site must have been deployed at least once (.powerpages-site folder must exist) for the > settings phase

Initial request: $ARGUMENTS

---

Workflow

(Phase headings below the workflow keep the technical "Layer 1+2 / Layer 3" names because they describe the runtime layering and are what maintainers grep for. The titles here mirror the user-facing task list.)

1. Check site is ready — locate project, detect framework, check data model, deployment status, and web-role presence.
2. Find where AI summaries fit — scan code for search / data summarization candidates.
3. Confirm what to add — review the manifest and pick which APIs / targets to integrate.
4. Set up data access for AI — invoke /create-webroles if needed, then invoke /integrate-webapi in AI-only read mode for data/case targets. Skip entirely for search-only or when prerequisites already exist.
5. Add AI summary code — invoke the ai-webapi-integration agent sequentially per target.
6. Register AI prompts — invoke the ai-webapi-settings-architect agent.
7. Verify everything — header-contract grep, $select grep, npm run build, validator script.
8. Review and deploy — record skill usage, summarise, offer /deploy-site.

---

Iteration mode (after first run)

This skill is a one-shot setup skill — Phases 1–8 run end-to-end the first time the user asks to integrate a summarization API. Once an AI surface is in place (service file, framework wrapper, UI call site, and Summarization/* settings all exist), follow-up requests to tweak the rendered UI (colours, spacing, copy, moving a button, a different empty-state message, wiring a second recommendation into the hook, etc.) are not a reason to re-enter this skill mentally and run every phase again. Doing so triggers a full pac pages upload-code-site and a chain of git commits for each tweak, which is exactly the noisy cadence the Phase 5.5 / 6.4 prompts above are there to avoid.

When the user asks for follow-up UI changes to an already-integrated AI surface:

• Edit the file(s) and run npm run build locally to verify the tweak compiles. That is the

whole validation loop for a UI change.

• Do NOT automatically run pac pages upload-code-site. Uploading should happen once, at the

end of the session, when the user has finished tweaking.

• Do NOT automatically git commit. Let the user batch related tweaks into a single commit.
• Batch the deployment and commit into a single end-of-session prompt once the user signals

they're done (or when you've completed the last requested change).

> 🚦 Gate (consent · add-ai-webapi:iter.deploy-commit): End-of-iteration batched deploy + commit prompt — avoids a noisy per-tweak upload/commit cadence. > > Trigger: User signals they're done with UI tweaks for the session. > Why we ask: Auto-deploying or committing after every small edit produces one git commit + one pac pages upload-code-site per tweak; batching keeps history readable and avoids redundant deploys. > Cancel leaves: Nothing — source files already edited; no deploy or commit fired.

Use AskUserQuestion:

| Question | Header | Options | |----------|--------|---------| | All the UI tweaks look good. Deploy the site and commit the changes now? | Deploy & commit | Yes, deploy and commit (Recommended), Just commit — I'll deploy later, Just deploy — I'll commit later, Neither — I'll handle both myself |

Re-enter the full skill flow only when the user is adding a new AI surface (a new page, a new table, a second API). If you're unsure whether a request is a tweak or a new surface, ask.

---

Phase 1: Verify Site Exists

Goal: Locate the Power Pages project root and confirm prerequisites.

1.0 Detect iteration mode (before anything else)

Re-entry detection comes first because the rest of the skill assumes a first-time setup. Capture two signals about the project state:

1. Service signal: a summarization service exists — src/services/aiSummaryService.*, or any

source file under src/ that contains /_api/search/v1.0/summary or /_api/summarization/data/v1.0/. When the signal is present, also note which API surface(s) the service code references — search-only, data-only, or both. This sub-classification matters below.

1. Settings signal: at least one Layer 3 site setting exists in

.powerpages-site/site-settings/Summarization-*.sitesetting.yml.

Then route on the combination:

• Both signals present → re-entry. A previous /add-ai-webapi run completed end-to-end. Show

the iteration-mode prompt below.

• Service signal present and the existing service code is search-only (it references

/_api/search/v1.0/summary but not /_api/summarization/data/v1.0/) → re-entry. Search-only sites legitimately have no Summarization/* settings (Search Summary uses the workspace toggle, not per-call settings), so the absence of the settings signal is the steady state, not a failed run. Show the iteration-mode prompt below.

• Service signal present and the existing service code includes Data Summarization but the

settings signal is absent → in-flight first run (a previous attempt failed before Phase 6 landed). Continue with the full flow without prompting.

• Neither signal present → first-time run. Continue with Phase 1.1.

When you reach the iteration-mode branch, ask:

| Question | Header | Options | |----------|--------|---------| | It looks like an AI summary surface is already wired into this site. Is this request a tweak to the existing one, or are you adding a brand-new surface (new page, new table, second API)? | Mode | Tweak the existing surface (Recommended for visual/copy edits), Add a new surface (run the full skill again), Not sure — show me what's already wired |

• Tweak the existing surface: stop running this skill. Switch into the workflow described in

the [Iteration mode](#iteration-mode-after-first-run) section above — Edit + npm run build, no auto upload-code-site, no auto commit, batched end-of-session prompt for deploy + commit.

• Add a new surface: continue with Phase 1.1 (full flow). The downstream phases will detect

existing infrastructure (CSRF helper, summarization service, settings) and extend rather than duplicate.

• Not sure — show me what's already wired: list the existing service file(s), wired UI

components, and Summarization/* settings, then re-ask the same question.

1.1 Create todo list

Create all 8 phase tasks upfront via TaskCreate — see [Progress Tracking](#progress-tracking).

1.2 Locate project

Look for powerpages.config.json in the current directory or immediate subdirectories.

If not found: tell the user to create a site first with /create-site.

1.3 Detect framework

Read package.json and detect React / Vue / Angular / Astro. See ${PLUGIN_ROOT}/references/framework-conventions.md.

1.4 Check for data model

Look for .datamodel-manifest.json. If found, read it — tables listed here are candidates for the Data Summarization API. The standard incident table is a candidate like any other; do not treat it specially.

1.5 Check deployment status — hard prerequisite

Look for .powerpages-site. Phase 4 (/integrate-webapi) and Phase 6 (ai-webapi-settings-architect) both require this folder to exist. Deferring the deploy until later is not a viable workaround: once Phase 5 has written the AI-calling service code, deploying a site whose Layer 1/2/3 settings aren't yet on disk publishes runtime-broken code (every summarization call 403/500s until a second deploy lands). The cleanest sequence is to deploy the clean scaffold now, before any AI code exists.

If .powerpages-site does NOT exist:

| Question | Header | Options | |----------|--------|---------| | .powerpages-site was not found. The AI summary skill needs the site deployed at least once before configuring permissions and settings. Deploy the clean scaffold now (no AI code yet — keeps the intermediate state safe), or stop and run /deploy-site yourself first? | Bootstrap deploy | Yes, deploy the scaffold now (Recommended), Stop — I'll deploy first then re-run /add-ai-webapi |

On Yes: invoke the Skill tool for power-pages:deploy-site and wait for completion. Then re-check .powerpages-site exists before proceeding. If it is still absent after the sub-skill returns (deploy failed mid-flow, the user cancelled it, or an upload completed but the local folder wasn't created), stop here with a clear message — surface the deploy-site outcome verbatim so the user can debug it, and tell them to re-run /deploy-site followed by /add-ai-webapi. Do NOT silently fall through to Phase 2; the downstream sub-skills require this folder.

On Stop: end the skill with a clear next-step message ("Run /deploy-site, then re-invoke /add-ai-webapi to continue"). Do NOT continue to Phase 2 — the downstream sub-skills can't run.

1.6 Check web roles

Look for .powerpages-site/web-roles/*.yml. Record whether any roles exist — the Phase 4 delegation needs at least one role before /integrate-webapi can create table permissions.

Output: confirmed project root, framework, data-model availability, deployment status, web-role inventory.

---

Phase 2: Explore AI integration points

Goal: Find every candidate for each of the two APIs — scoped to AI only.

The full Explore-agent prompt body, manifest shape, and delegation-decision rules live in ${PLUGIN_ROOT}/skills/add-ai-webapi/references/explore-prompt.md. Read that file first, then invoke the Explore agent (via Task with `subage

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: microsoft
• Source: microsoft/power-platform-skills
• License: MIT
• Homepage: https://aka.ms/ppskills

Install and usage instructions live in the source repository linked above.