/add-ai-webapi

name: add-ai-webapi
description: >-
  Integrates Power Pages generative-AI summarization APIs (PREVIEW) into a Single Page Application
  (SPA) site — the Search Summary API and the Data Summarization API — on any record-detail or list
  page. Generates per-target service code (CSRF-handled) and AI site settings; delegates Web API
  settings, table permissions, and web roles to `/integrate-webapi` and `/create-webroles`. Use
  whenever a user wants AI/Copilot output that condenses Dataverse content on a Power Pages site —
  an AI summary, AI-generated overview or "key insights" across a record or list, a search-results
  summary, a case/incident summary, or recommendation-chip refinement — even when phrased as
  "AI-generated paragraph", "insights", or "overview". Do NOT use for: generative pages in
  model-driven apps (use the model-apps `genpage` skill), Copilot Studio agents/chatbots,
  summarizing documents or PDFs, Power BI dashboards, plain keyword search with no AI summary, or
  plain Dataverse CRUD (use `/integrate-webapi`).
user-invocable: true
argument-hint: Optional description of which pages/tables need AI capabilities
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, Skill, Task, TaskCreate, TaskUpdate, TaskList, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_search, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch
model: opus

> **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/<table>/enabled`, `Webapi/<table>/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/<entitySet>(<id>)?$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(<caseId>)?$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