feat(ultraplan-local): v1.6.0 — /ultraresearch-local deep research command

Add /ultraresearch-local for structured research combining local codebase analysis with external knowledge via parallel agent swarms. Produces research briefs with triangulation, confidence ratings, and source quality assessment. New command: /ultraresearch-local with modes --quick, --local, --external, --fg. New agents: research-orchestrator (opus), docs-researcher, community-researcher, security-researcher, contrarian-researcher, gemini-bridge (all sonnet). New template: research-brief-template.md. Integration: --research flag in /ultraplan-local accepts pre-built research briefs (up to 3), enriches the interview and exploration phases. Planning orchestrator cross-references brief findings during synthesis. Design principle: Context Engineering — right information to right agent at right time. Research briefs are structured artifacts in the pipeline: ultraresearch → brief → ultraplan --research → plan → ultraexecute. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-08 08:58:35 +02:00 · 2026-04-08 08:58:35 +02:00 · baa2d0220b
commit baa2d0220b
488 changed files with 213221 additions and 0 deletions
--- a/skills/ms-ai-advisor/references/copilot-extensibility/copilot-studio-topics-and-entities.md
+++ b/skills/ms-ai-advisor/references/copilot-extensibility/copilot-studio-topics-and-entities.md
@ -0,0 +1,442 @@
+# Topics and Entities in Copilot Studio
+
+**Last updated:** 2026-02
+**Status:** GA
+**Category:** Copilot Extensibility & Integration
+
+---
+
+## Introduksjon
+
+Topics og entities utgjør kjernen i samtalelogikken i Copilot Studio. En **topic** er en diskret samtaletråd mellom bruker og agent, strukturert som en samtaleflyt med noder. **Entities** er AI-drevne datatyper som identifiserer og ekstraherer spesifikk informasjon fra brukerens input — som navn, datoer, beløp eller egendefinerte verdier.
+
+Sammen muliggjør de:
+- **Strukturerte samtaleflyter** med spørsmål, betingelser, videresendinger og handlinger
+- **Intelligent informasjonsinnhenting** via slot filling, hvor agenten automatisk gjenkjenner og husker nøkkelinformasjon
+- **Kontekstavhengig logikk** som tilpasser samtalebanen basert på brukerens svar og entitetsverdier
+
+Topics kan opprettes manuelt, ved AI-assistert beskrivelse (Copilot-generering), eller fra eksisterende innhold. Entities finnes både som prebuilt-varianter (age, money, email, phone number, etc.) og egendefinerte (closed list eller regex).
+
+**Verificert:** Basert på Microsoft Learn-dokumentasjon (januar 2026).
+
+---
+
+## Kjernekomponenter
+
+### Topics
+
+| Komponent | Beskrivelse | Modelltilknytning |
+|-----------|-------------|-------------------|
+| **Trigger phrases** | Ord, fraser eller spørsmål som triggererer topic (kun i classic orchestration) | NLU-matching, krever 5-10 fraser for god trening |
+| **Topic description** | Beskriver topicets formål (nødvendig i generative orchestration) | Brukes av GPT-modell til å velge riktig topic dynamisk |
+| **Conversation nodes** | Byggeklosser i samtaleflyt: Message, Question, Condition, Variable management, Tool, Redirect, End | Hver node utfører en handling (sende melding, stille spørsmål, kalle flow, etc.) |
+| **Authoring canvas** | Visuell editor med low-code-grensesnitt | Støtter drag-and-drop, betinget logikk og variabelhåndtering |
+| **Code editor (YAML)** | Tekstbasert editor for eksport/import av topic-logikk | YAML-format, støtter kopiering og versjonering |
+| **Input/output parameters** | Parametere som brukes ved videresending mellom topics eller i generative actions | Automatisk slot filling i generative mode |
+
+### Entities
+
+| Type | Beskrivelse | Bruk |
+|------|-------------|------|
+| **Prebuilt entities** | 30+ innebygde typer: age, boolean, city, color, country, date/time, email, money, number, phone, URL, etc. | Direkte tilgjengelig via entity picker i Question-noder |
+| **Closed list entities** | Egendefinert liste med verdier og synonymer (f.eks. "hiking" med synonymer "trekking", "mountaineering") | Best for små, oversiktlige lister med forutsigbare verdier |
+| **Regex entities** | Mønsterbasert matching med regulære uttrykk | For strukturerte formater som ordre-ID (INC000001), lisensplater, IP-adresser |
+| **Smart matching** | Fuzzy logic for stavefeil og semantisk utvidelse (f.eks. "softball" → "baseball") | Aktiveres per closed list entity |
+| **External entities** | Importerte entities fra CLU (Conversational Language Understanding) med custom JSON resolutions | For avanserte NLU-scenarier med komplekse datatyper |
+
+**Sammenligning: Closed List vs. Regex**
+
+| Kriterium | Closed List | Regex |
+|-----------|-------------|-------|
+| **Format** | Liste med verdier + synonymer | Mønster (f.eks. `^INC\d{6}$`) |
+| **Best for** | Produkt-kategorier, valg, steder | Strukturerte data med fast format |
+| **Smart matching** | Støttes (aktiveres per entity) | Nei (pattern må matche eksakt) |
+| **Vedlikehold** | Enkelt å legge til/fjerne verdier | Krever regex-kompetanse |
+| **Eksempel** | "Hiking" med synonymer "Trekking", "Mountaineering" | Tracking ID: `[A-Z]{2}\d{8}` |
+
+---
+
+## Arkitekturmønstre
+
+### Topic Design Patterns
+
+#### 1. Single-turn vs. Multi-turn Conversations
+
+| Mønster | Beskrivelse | Eksempel |
+|---------|-------------|----------|
+| **Single-turn** | Ett spørsmål, ett svar | "Hva er åpningstidene?" → svar med link til nettside |
+| **Multi-turn** | Flere spørsmål i sekvens, med betinget logikk | "Hvilken butikk?" → "Hvilken dato?" → viser åpningstider for valgt butikk og dato |
+
+#### 2. Branching Logic med Betingelser
+
+```yaml
+- kind: ConditionGroup
+  conditions:
+    - condition: =Topic.State = "California" || Topic.State = "Washington"
+      actions:
+        - kind: SendMessage
+          message: "Shipping is free to West Coast states."
+  elseActions:
+    - kind: SendMessage
+      message: "Additional shipping charge of $27.50."
+```
+
+**Arkitekturprinsipp:** Bruk ConditionGroup-noder for å route samtalen basert på entity-verdier, brukerinput eller globale variabler.
+
+#### 3. Topic Redirect og Subtopics
+
+```yaml
+- kind: RedirectToTopic
+  targetTopic: "StoreClosureInformation"
+```
+
+| Scenario | Redirect-strategi |
+|----------|-------------------|
+| **Underemne** | Redirect til subtopic, fortsett original topic etter |
+| **Avslutning** | Redirect til system-topics (End of Conversation, Escalate, Goodbye) |
+| **Globale topics** | System fallback-topic for ugjenkjente forespørsler |
+
+#### 4. Slot Filling Patterns
+
+##### Pattern A: Sequential Slot Filling (tradisjonell)
+Agent stiller spørsmål i rekkefølge for å samle informasjon:
+1. "Hvilken aktivitet?" → "hiking"
+2. "Hvor lenge?" → "2 timer"
+3. "Budsjett?" → "under $100"
+
+##### Pattern B: Proactive Slot Filling (intelligent)
+Bruker sier: *"I want to buy hiking boots under $100 for a weekend trip"*
+
+Agent gjenkjenner automatisk:
+- **Activity**: hiking
+- **Product**: boots
+- **Budget**: $100
+- **Duration**: weekend (implisitt)
+
+Agent hopper over allerede besvarte spørsmål.
+
+**Arkitekturvalg:**
+
+| Funksjon | Beskrivelse | Kontroll |
+|----------|-------------|----------|
+| **Skip question (default)** | Agent hopper over spørsmål hvis slot allerede er fylt | `alwaysPrompt: false` (YAML) |
+| **Ask every time** | Tving spørsmål uavhengig av om slot er fylt | `alwaysPrompt: true` (YAML) eller via node properties |
+
+#### 5. Multiple Entity Recognition
+
+En Question-node kan akseptere opptil 5 forskjellige entities:
+
+```yaml
+- kind: Question
+  prompt: "Provide your account number or phone number"
+  entity:
+    - AccountNumber (regex)
+    - PhoneNumber (prebuilt)
+    - UnknownOption (closed list: "I don't know")
+```
+
+**Variable type:** Record med ett element per entity (f.eks. `Identifier.account`, `Identifier.phone`, `Identifier.unknown`).
+
+**Begrensning:** Agent identifiserer kun første matchende entity i listen ved multiple matches.
+
+---
+
+## Beslutningsveiledning
+
+### Når bruke Topics vs. Generative Answers
+
+| Scenario | Anbefaling | Begrunnelse |
+|----------|------------|-------------|
+| Strukturert prosess (bestilling, onboarding) | **Topics** | Full kontroll over samtaleflyt, validering, betingelser |
+| Åpne spørsmål fra kunnskapsbase | **Generative Answers** | AI genererer svar fra knowledge sources (websites, SharePoint, Dataverse) |
+| Hybrid (prosess + fleksibilitet) | **Generative Orchestration** | AI velger automatisk mellom topics, tools og knowledge |
+| Task automation (e-post, CRM-oppdatering) | **Topics med Tools** | Topic kaller Power Automate flow eller connector |
+
+### Når bruke Prebuilt vs. Custom Entities
+
+| Kriterium | Prebuilt | Custom (Closed List) | Custom (Regex) |
+|-----------|----------|---------------------|---------------|
+| **Datatye er standard** (email, phone, date) | ✅ Ja | - | - |
+| **Domene-spesifikk liste** (produkter, lokasjoner) | - | ✅ Ja | - |
+| **Fast format** (ordre-ID, tracking code) | - | - | ✅ Ja |
+| **Trenger synonymer** | Nei (innebygd) | ✅ Ja | Nei |
+| **Smart matching/fuzzy logic** | Automatisk | Valgfritt (toggle) | Nei |
+
+### Topic Design Checklist
+
+1. **Identifiser topic-formål:** Informasjon, oppgavegjennomføring eller feilsøking?
+2. **List alle scenarioer:** Hvilke varianter av samtalen kan oppstå?
+3. **Design samtaletreet:** Tegn flyt på høyt nivå med betingelser og veivalg
+4. **Minimér antall spørsmål:** Bruk slot filling for å samle flere verdier fra én input
+5. **Valider og iterer:** Test med ekte brukere, les session transcripts i Analytics
+
+**Anti-patterns:**
+- ❌ Replikere funksjonalitet som allerede finnes på nettside/app (brukere kan gjøre dette selv)
+- ❌ Bygge topics for "long tail"-scenarioer før høyvolum-issues er dekket
+- ❌ Bruke periods (`.`) i topic-navn (blokkerer solution export)
+
+---
+
+## Integrasjon med Microsoft-stakken
+
+### Power Automate Integration
+
+Topics kan kalle Power Automate flows via Tool-noder:
+
+```yaml
+- kind: CallAction
+  id: call-flow-get-weather
+  action: GetWeatherForecast
+  inputs:
+    city: =Topic.City
+    zipcode: =Topic.ZipCode
+  output: Topic.WeatherData
+```
+
+**Brukstilfeller:**
+- Send e-post med data samlet i topic
+- Oppdater Dataverse-record
+- Trigger external API (via HTTP action i flow)
+- Hente data fra SharePoint eller SQL
+
+### Dynamics 365 og Dataverse
+
+Topics kan referere til Dataverse-tables via:
+- **Generative answers** fra Dataverse knowledge sources
+- **Power Automate flows** som oppretter/leser records
+- **Copilot Studio connectors** (Dataverse connector i Tool-node)
+
+**Eksempel:** Topic som oppretter sample account records med lat/long-koordinater (se code samples i dokumentasjon).
+
+### Microsoft 365 Copilot Handoff
+
+Topics kan videresende samtale til Microsoft 365 Copilot via continuation token:
+
+```typescript
+await context.sendActivities([
+  { type: ActivityTypes.Message, text: "Continuing conversation from copilot..." },
+  { type: ActivityTypes.Message, text: `Fetching more details using continuation token: ${token}` },
+  { type: ActivityTypes.Message, text: "Handoff successful!" }
+]);
+```
+
+**Brukstilfeller:**
+- Copilot Studio-agent starter samtale, M365 Copilot tar over for dype spørsmål i organisasjonens data
+- Agent i Teams/M365 redirecter til Copilot Studio for strukturerte workflows
+
+### Azure Bot Service Channels
+
+Topics kan publiseres til eksterne kanaler (SMS, Facebook, Slack) via Azure Bot Service integration:
+
+1. **DirectLineClient** starter Copilot Studio-samtale via DirectLine API
+2. **OnMessageActivityAsync** handler i bot-relay sender brukermelding til Copilot Studio
+3. **Watermark** tracker turntaking i samtalen
+4. **Token refresh** kreves hver 30. minutt (håndteres i relay-logikk)
+
+---
+
+## Offentlig sektor (Norge)
+
+### Compliance og Datahåndtering
+
+| Krav | Implementasjon via Topics og Entities |
+|------|---------------------------------------|
+| **GDPR** | Entities (email, phone, name) lagres i Dataverse med compliance-settings; variable retention via "Clear variable" node |
+| **Arkivloven** | Topic session transcripts kan eksporteres til arkivsystem via Power Automate (Azure Blob/Sharepoint) |
+| **Personvern** | Bruk regex entities for sensitive ID-formater (fødselsnummer, passnummer) med masking i logs |
+| **Tilgjengelighet (UU)** | Topics støtter SSML for voice-kanaler; adaptive cards følger accessibility-standarder |
+
+### Flerspråklig Support
+
+Topics og trigger phrases kan defineres per språk:
+
+| Språk | Støtte | NLU-kvalitet |
+|-------|--------|--------------|
+| **Norsk bokmål** | ✅ GA | God (prebuilt entities, GPT-modell) |
+| **Norsk nynorsk** | Delvis (via custom entities) | Moderat (krever custom training) |
+| **Samisk** | Nei (bruk engelsk som fallback) | Ikke støttet |
+
+**Anbefalinger for norsk offentlig sektor:**
+1. Bruk engelsk for entity-navn og variable-navn (code readability)
+2. Bruk norsk i trigger phrases og meldinger til brukere
+3. Definer custom closed list entities for norske geografiske navn, organisasjoner og termer
+4. Test med ekte innbyggerhenvendelser for å iterere på trigger phrases
+
+---
+
+## Kostnad og lisensiering
+
+### Lisenskriterier
+
+| Lisens | Topics-kapabilitet | Entities-kapabilitet |
+|--------|-------------------|---------------------|
+| **Copilot Studio** (standalone) | Ubegrenset topics, 25 000 messages/måned per $200 capacity | Alle prebuilt + custom entities, external entities (NLU+) |
+| **Power Apps Premium** | Inkludert (inntil 250 messages/bruker/måned) | Alle prebuilt + custom entities |
+| **Microsoft 365 Copilot** | Topics via Copilot Studio extension | Entities støttes i generative orchestration |
+
+### Kostnadsoptimalisering
+
+| Kostnadsfaktor | Påvirkning | Optimalisering |
+|----------------|-----------|----------------|
+| **Antall topic-traversals** | Hver gang topic redirectes eller topic kaldes, telles som én turn | Konsolider logikk i færre topics |
+| **Generative answers calls** | GPT API calls koster mer enn statiske svar | Bruk topics for kjente scenarioer, generative answers for "long tail" |
+| **Tool calls (Power Automate)** | Hver flow-kjøring teller mot Power Automate kvote | Batch flere handlinger i én flow |
+| **Session lengde** | Lengre samtaler (flere turns) øker message-forbruk | Design topics for å løse brukerens behov raskt |
+
+**Estimert kostnad (norsk offentlig virksomhet, 1000 brukere):**
+- Basis Copilot Studio lisens: $200/måned (25 000 messages)
+- Ekstra kapasitet: $100 per 10 000 messages
+- Typisk forbruk: 3-5 messages per samtale (én topic med 2-3 spørsmål)
+- Estimert månedlig kostnad: $200-$400 for 5000-10 000 samtaler
+
+---
+
+## For arkitekten (Cosmo)
+
+### Designprinsipper for Topics
+
+1. **Start med high-impact topics:** Analyser support-volum og bygg topics for topp 5-10 henvendelser først.
+2. **Bruk slot filling aggressivt:** La brukere gi flere opplysninger i én setning, unngå unødvendige spørsmål.
+3. **Design for fallback:** Alltid ha fallback-logikk (system fallback topic, escalate til agent, eller generative answers).
+4. **Test med ekte data:** Bruk Analytics-transcripts for å iterere på trigger phrases og betingelser.
+5. **Versjonskontroll topics:** Eksporter topics som YAML til git for versjonering og code review.
+
+### Entity-strategi
+
+| Scenario | Entity-valg | Rationale |
+|----------|-------------|-----------|
+| **Persondata (navn, e-post, telefon)** | Prebuilt | Innebygd validering og global NLU-støtte |
+| **Norske stedsnavn** | Custom closed list med smart matching | Fuzzy logic håndterer stavefeil ("Tronsheim" → "Trondheim") |
+| **Interne ordre-ID, sak-ID** | Regex | Fast format (f.eks. `SAK-\d{6}`) garanterer korrekt parsing |
+| **Kategori-valg (f.eks. tjenestetype)** | Custom closed list | Synlig for brukere som knapper, støtter synonymer |
+
+### Integrasjonsarkitektur
+
+```
+User → Copilot Studio Agent (Topic)
+         ↓
+      [Question Node med Entity]
+         ↓
+      [Slot Filling + Betingelser]
+         ↓
+      [Tool Node → Power Automate Flow]
+         ↓
+      [Dataverse / Azure / SAP / Custom API]
+         ↓
+      [Svar til bruker + Redirect eller End]
+```
+
+**Key Decisions:**
+- **Generative vs. Classic Orchestration:** Velg generative hvis brukerforespørsler er uforutsigbare; classic hvis du trenger deterministisk flyt.
+- **Topic granularity:** En topic per brukerforspørsel (f.eks. "Book møterom") vs. flere topics per domene (f.eks. "Møterom: søk", "Møterom: bestill", "Møterom: kanseller").
+- **Entity scope:** Globale entities (gjenbrukes på tvers av topics) vs. topic-spesifikke entities (scope-isolasjon).
+
+### Testing og Iterasjon
+
+1. **Test-panel i Copilot Studio:** Bruk "Track between topics" for å debugge samtaleflyt.
+2. **Variable watch window:** Inspiser entity-verdier real-time under testing.
+3. **Analytics:** Analyser "unanswered queries" og "generative answer quality" for å forbedre topics.
+4. **A/B-testing:** Lag to versjoner av samme topic med ulike trigger phrases, sammenlign CSAT-score.
+
+### Når Bruke Code Editor (YAML)
+
+- ✅ Kopiering av topics mellom agents
+- ✅ Versjonering i git (diffing, code review)
+- ✅ Bulk-editing av betingelser eller meldinger
+- ✅ Import av komplekse topics fra andre teams
+- ❌ IKKE for å designe nye topics fra scratch (bruk GUI først, eksporter YAML etter)
+
+---
+
+## Kilder og verifisering
+
+### Primærkilder (Verified)
+
+Alle referanser er hentet fra offisiell Microsoft Learn-dokumentasjon via MCP (`microsoft-learn` server), januar 2026:
+
+1. **Create and edit topics**
+   https://learn.microsoft.com/en-us/microsoft-copilot-studio/authoring-create-edit-topics
+   Comprehensive guide til topic authoring, node types, code editor (YAML), input/output parameters.
+
+2. **Use entities and slot filling in agents**
+   https://learn.microsoft.com/en-us/microsoft-copilot-studio/advanced-entities-slot-filling
+   Detaljer om prebuilt entities, custom entities (closed list, regex), slot filling, proactive slot filling, multiple entity recognition.
+
+3. **Topics in Copilot Studio (Guidance)**
+   https://learn.microsoft.com/en-us/microsoft-copilot-studio/guidance/topics-overview
+   Overview av topic-konseptet, trigger phrases, conversation nodes, AI-generering.
+
+4. **Defining agent topics (Guidance)**
+   https://learn.microsoft.com/en-us/microsoft-copilot-studio/guidance/defining-chatbot-topics
+   Topic design process, single-turn vs. multi-turn, best practices.
+
+5. **Variables overview (Entities table)**
+   https://learn.microsoft.com/en-us/microsoft-copilot-studio/authoring-variables-about
+   Fullstendig tabell over prebuilt entities og variable base types.
+
+6. **Implement slot-filling best practices (Guidance)**
+   https://learn.microsoft.com/en-us/microsoft-copilot-studio/guidance/slot-filling-best-practices
+   Best practices for entity-bruk, closed list vs. regex, user experience-forbedringer.
+
+7. **Training: Manage topics in Microsoft Copilot Studio**
+   https://learn.microsoft.com/en-us/training/modules/manage-power-virtual-agents-topics/
+   Strukturert læringssti for topic management, branching, fallback topics.
+
+8. **Training: Work with entities and variables**
+   https://learn.microsoft.com/en-us/training/modules/power-virtual-agents-entities/
+   Praktisk trening i entity-bruk og variable-håndtering.
+
+### Code Samples (Verified)
+
+YAML-eksempler hentet fra Microsoft Learn code samples:
+
+1. **AdaptiveDialog topic med conditional logic og entities**
+   https://learn.microsoft.com/en-us/microsoft-copilot-studio/authoring-create-edit-topics#edit-a-topic
+   YAML-eksempel med Question nodes, ConditionGroup, StatePrebuiltEntity, BooleanPrebuiltEntity.
+
+2. **Power Automate integration i topic**
+   https://learn.microsoft.com/en-us/microsoft-copilot-studio/advanced-use-flow
+   Eksempel på Tool node som kaller flow med inputs/outputs.
+
+3. **Azure Bot Service DirectLineClient integration**
+   https://learn.microsoft.com/en-us/microsoft-copilot-studio/publication-connect-bot-to-azure-bot-service-channels
+   C#-eksempel på session management, conversation routing.
+
+4. **Dynamics 365 account creation via topic**
+   https://learn.microsoft.com/en-us/dynamics365/guidance/resources/field-service-deploy-copilot-studio-create-sample-data
+   YAML-eksempel med SearchAndSummarizeContent node, Question nodes for lat/long, ConditionGroup.
+
+### Baseline (modellkunnskap)
+
+Følgende informasjon er basert på modellens treningsdata (januar 2025) og bekreftet mot Microsoft Learn januar 2026:
+- Generative orchestration vs. classic orchestration
+- Topic lifecycle (draft, published, deprecated)
+- Topic vs. Generative Answers use cases
+- Entity types og variable base types
+- Power Fx expressions i betingelser
+
+### Confidence Rating
+
+| Seksjon | Confidence | Kilde |
+|---------|-----------|-------|
+| Kjernekomponenter | **Verified** | Microsoft Learn (fetch + search) |
+| Arkitekturmønstre | **Verified** | Microsoft Learn + code samples |
+| Beslutningsveiledning | **Baseline** | Modellkunnskap, bekreftet mot docs |
+| Microsoft-integrasjon | **Verified** | Microsoft Learn (code samples) |
+| Offentlig sektor (Norge) | **Baseline** | Modell-ekstrapolasjon basert på general GDPR/compliance-kunnskap |
+| Kostnad og lisensiering | **Baseline** | Modellkunnskap (januar 2025), kan ha endret seg i 2026 |
+
+**Sist verifisert:** 2026-02-04 (via MCP `microsoft-learn` server)
+
+---
+
+**For Cosmo:**
+
+Når du rådgir om topics og entities, vurder:
+1. **Topic granularity:** Hvor mange topics trenger løsningen? (Tommelfingerregel: 1 topic per høynivå-brukerforspørsel)
+2. **Entity-strategi:** Hvilke entities er kritiske for slot filling? Prebuilt vs. custom?
+3. **Orchestration mode:** Classic (deterministisk) vs. Generative (fleksibel)?
+4. **Integration points:** Trenger topics å kalle Power Automate, Dataverse, eller eksterne APIer?
+5. **Fallback-strategi:** Hva skjer ved ugjenkjente forespørsler? (Generative answers, escalate, eller redirect?)
+
+Bruk dette dokumentet som referanse når du designer samtaleflyt, evaluerer entity-behov, og planlegger integrasjoner.