ms-ai-architect/skills/ms-ai-advisor/references/copilot-extensibility/copilot-studio-topics-and-entities.md

# 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.

**Merk (oppdatert 2026):** Proactive slot filling er aktivert som standard. Deaktiver per node via **Skip question → Ask every time** i Question-noden Properties. Agenten lytter aktivt og husker informasjon gjennom hele samtalen.

**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, WhatsApp) via Azure Bot Service integration (GA):

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)

**WhatsApp (GA jul 2025):** Copilot Studio støtter nå direkte publisering til WhatsApp-nummer — ingen mellomlagring via Azure Bot Service nødvendig.

---

## 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), april 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-04-10 (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.