ms-ai-architect/skills/ms-ai-advisor/references/copilot-extensibility/microsoft-graph-api-copilot-integration.md

# Microsoft Graph API for Copilot Extensions

**Last updated:** 2026-02
**Status:** GA
**Category:** Copilot Extensibility & Integration

---

## Introduksjon

Microsoft Graph API for Copilot Extensions gir mekanismer for å utvide Microsoft 365 Copilot med ekstern data og funksjonalitet gjennom tre hovedveier: **Copilot Connectors** (tidligere Microsoft Graph Connectors), **API Plugins**, og **Graph Actions med Semantic Kernel**. Disse teknologiene lar organisasjoner integrere line-of-business-data, eksterne APIer og Microsoft 365-funksjonalitet i Copilot-opplevelser.

**Copilot Connectors** importerer ekstern innhold inn i Microsoft Graph for å berike Copilots kunnskapsbase. **API Plugins** kobler REST-APIer til declarative agents for å utføre handlinger. **Graph Actions** lar custom engine agents (bygget med Semantic Kernel) bruke Microsoft Graph API-funksjoner som å sende e-post, opprette kalenderhendelser og hente filer gjennom naturlig språk.

**Confidence:** Verified (microsoft-learn MCP, januar 2026)

---

## Kjernekomponenter

### 1. Copilot Connectors (Microsoft Graph Connectors)

**Formål:** Indeksere ekstern data inn i Microsoft Graph for å gjøre den søkbar og tilgjengelig for Copilot, Microsoft Search, Context IQ og andre M365-opplevelser.

| Komponent | Beskrivelse | API Resource |
|-----------|-------------|--------------|
| **External Connection** | Logisk container for ekstern data | `externalConnection` |
| **Schema** | Definerer struktur og metadata for innholdet | `schema` |
| **External Item** | Individuelt dataobjekt indeksert i Microsoft Graph | `externalItem` |
| **External Group** | Ikke-Entra ID grupper for tilgangskontroll (ACL) | `externalGroup` |
| **Activity Settings** | Konfigurasjon for brukeraktiviteter og URL-resolving | `activitySettings` |
| **Semantic Labels** | Metadata for å hjelpe Copilot tolke schemameningen | `iconUrl`, `title`, `url`, etc. |

**Fire steg for å bygge custom Copilot Connector:**

1. **Opprett Entra ID app registration** med nødvendige Graph API-permissions
2. **Opprett external connection** med unik ID, navn og beskrivelse
3. **Registrer schema** (long-running operation, async provisioning)
4. **Ingest external items** med innhold og ACL

**Confidence:** Verified (microsoft-learn docs_fetch)

### 2. API Plugins

**Formål:** Koble REST APIer til declarative agents for å utføre handlinger på vegne av brukeren.

**Støttes kun som actions innenfor declarative agents** (ikke standalone i M365 Copilot).

| Komponent | Beskrivelse |
|-----------|-------------|
| **OpenAPI Specification** | Beskriver REST API-endepunkter, parametere og autentisering |
| **Plugin Manifest** | API plugin manifest (schema v2.4) som definerer plugin capabilities |
| **Authentication** | Token/API key fra token store (støtter OAuth2, API keys) |
| **Confirmation Prompts** | Brukerbekreftelse før data sendes til plugin (konfigurerbart) |

**Dataflyt:**
1. Bruker stiller spørsmål → Agent identifiserer relevant plugin
2. Agent mapper spørsmål til funksjon og parametere
3. Agent ber om brukerbekreftelse
4. Plugin henter token fra token store (hvis nødvendig)
5. API-kall sendes til eksternt endepunkt
6. Agent genererer respons basert på API-svar

**Confidence:** Verified (microsoft-learn docs_search)

### 3. Graph Actions med Semantic Kernel

**Formål:** La custom engine agents bruke Microsoft Graph API-funksjoner gjennom naturlig språk.

**Prebuilt plugins:**
- **ContactsPlugin** – Administrer kontakter
- **MessagesPlugin** – Interager med e-post
- **CalendarPlugin** – Opprett og list møter
- **DriveItemsPlugin** – Søk, les og last opp filer
- **M365 Copilot Plugin (Retrieval API)** – Søk i M365-innhold via semantic index

**Hvordan det fungerer:**
1. Semantic Kernel analyserer brukerintensjon
2. Matcher til riktig plugin (f.eks. CalendarPlugin)
3. Genererer Microsoft Graph API-kall
4. Kjører request med delegated auth
5. Returnerer resultat som naturlig språk-respons

**Verktøy:** Kiota CLI for å generere plugins fra OpenAPI spec.

**Confidence:** Verified (microsoft-learn docs_search)

---

## Arkitekturmønstre

### Mønster 1: Knowledge Augmentation (Copilot Connectors)

**Bruksområde:** Berike Copilots kunnskapsbase med line-of-business data (ERP, CRM, wiki, dokumenter).

```
[External Data Source]
    ↓ (API/SDK)
[Custom Connector Code]
    ↓ (Graph Connectors API)
[Microsoft Graph - External Items]
    ↓ (Semantic Index)
[M365 Copilot + Search + Context IQ]
```

**Best practices:**
- Bruk **semantic labels** (`title`, `content`, `iconUrl`, `url`) for å forbedre Copilot-relevans
- Inkluder **urlToItemResolver** for å oppdage delte URLer (booster viktighet)
- Legg til **user activities** (view, modify, comment) for relevansscoring
- Rik **description** i connection-konfigurasjon
- Ingest content som **tekst** i `content`-property (ikke bare metadata)

**Confidence:** Verified (microsoft-learn docs_fetch)

### Mønster 2: Action Execution (API Plugins)

**Bruksområde:** Utføre handlinger i eksterne systemer fra declarative agents (f.eks. "Opprett Jira ticket", "Sjekk budsjett i ERP").

```
[User Prompt]
    ↓
[Declarative Agent]
    ↓ (Confirmation)
[API Plugin] → [Token Store] → [External REST API]
    ↓
[Agent Response]
```

**Best practices:**
- Følg [OpenAPI guidance for Copilot](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/openapi-document-guidance)
- Bruk **confirmation prompts** fornuftig (default: read-only = "Always allow", write = no "Always allow")
- Implementer robust **error handling** i API
- Begrens antall operasjoner per plugin (fokuser på kjernefunksjonalitet)

**Confidence:** Verified (microsoft-learn docs_search)

### Mønster 3: M365 Data Integration (Graph Actions)

**Bruksområde:** Custom agents som trenger tilgang til M365-data (e-post, kalender, filer, kontakter).

```
[User Prompt]
    ↓
[Semantic Kernel Agent]
    ↓ (Plugin Selection)
[Graph Action Plugin] → [Microsoft Graph API]
    ↓ (Delegated Auth)
[M365 Data: Mail/Calendar/Files/Contacts]
```

**Eksempel:**
- "Sjekk e-post fra min leder, oppsummer, og sett opp møte" → bruker MessagesPlugin + CalendarPlugin + ContactsPlugin

**Best practices:**
- Bruk **prebuilt plugins** der tilgjengelig (vedlikeholdes av Microsoft)
- Implementer **delegated permissions** (ikke application permissions for brukerdata)
- Kombiner flere plugins for komplekse workflows

**Confidence:** Verified (microsoft-learn docs_search)

### Mønster 4: Hybrid (Connector + Plugin)

**Bruksområde:** Søkbar data + handlinger i samme ekstern tjeneste.

**Eksempel:** Salesforce-integrasjon
- **Connector:** Indekser Salesforce-objekter (Accounts, Opportunities) for søk
- **Plugin:** Opprett nye leads, oppdater kontakter

**Fordel:** Brukere kan både finne ("Vis alle accounts i Norge") og handle ("Opprett ny contact for Acme Corp").

**Confidence:** Baseline (arkitekturprinsipp basert på Microsoft-docs patterns)

---

## Beslutningsveiledning

### Når bruke Copilot Connectors?

| Scenario | Anbefaling | Hvorfor |
|----------|------------|---------|
| Store mengder lesbar data (dokumenter, wiki, CRM-objekter) | ✅ Copilot Connector | Semantic indexing, søk, oppsummering |
| Data må være søkbart i Search + Copilot | ✅ Copilot Connector | Deler samme index |
| Trenger filtere basert på brukerrettigheter (ACL) | ✅ Copilot Connector | External groups støtter ikke-Entra ID ACL |
| Kun lese-operasjoner | ✅ Copilot Connector | Optimalisert for retrieval |
| Data endres sjelden (statisk innhold) | ✅ Copilot Connector | Ingest kan være batch/scheduled |

**Confidence:** Verified (microsoft-learn docs_fetch + docs_search)

### Når bruke API Plugins?

| Scenario | Anbefaling | Hvorfor |
|----------|------------|---------|
| Utføre handlinger (create, update, delete) | ✅ API Plugin | Designet for actions |
| Real-time data fra REST API (ikke indeksering) | ✅ API Plugin | On-demand API calls |
| Behov for brukerbekreftelse før handling | ✅ API Plugin | Innebygd confirmation flow |
| Integration med declarative agent | ✅ API Plugin | Kun støttet som agent actions |
| Liten, fokusert funksjonalitet (f.eks. "Hent budsjett") | ✅ API Plugin | Lightweight, ikke persistence |

**Merk:** API Plugins er **ikke** standalone i M365 Copilot (kun som actions i declarative agents).

**Confidence:** Verified (microsoft-learn docs_search)

### Når bruke Graph Actions?

| Scenario | Anbefaling | Hvorfor |
|----------|------------|---------|
| Custom engine agent trenger M365-data | ✅ Graph Actions | Prebuilt plugins for Graph API |
| Sende e-post, opprette møter, hente filer | ✅ Graph Actions | ContactsPlugin, MessagesPlugin, CalendarPlugin, DriveItemsPlugin |
| Semantic Kernel-basert agent | ✅ Graph Actions | Native integration |
| Multi-step workflows med M365-data | ✅ Graph Actions | Kombiner flere plugins |
| Delegated permissions (brukerkontekst) | ✅ Graph Actions | Kjører som signed-in user |

**Confidence:** Verified (microsoft-learn docs_search)

### Beslutningstre

```
Trenger du å berike Copilot med ekstern data?
├─ Ja, for søk og oppsummering → Copilot Connector
└─ Nei, trenger å utføre handlinger
   ├─ Handlinger i M365 (e-post, kalender, filer) → Graph Actions
   └─ Handlinger i eksterne systemer → API Plugin
      └─ Merk: Krever declarative agent
```

**Confidence:** Baseline (syntetisert fra verified sources)

---

## Integrasjon med Microsoft-stakken

### 1. Microsoft 365 Copilot

**Copilot Connectors:**
- Innhold dukker opp i Copilot-svar med **in-text citations** (hover for preview)
- **Reference links** nederst i responsen
- Krever **inline results** aktivert i Admin Center (Agents and connectors → Copilot)

**API Plugins:**
- Kun tilgjengelig som **actions i declarative agents** (ikke i business chat)

**Graph Actions:**
- Kun for **custom engine agents** (ikke M365 Copilot business chat)

**Confidence:** Verified (microsoft-learn docs_fetch)

### 2. Microsoft Search

**Copilot Connectors:**
- Samme index som Copilot → eksterne items er søkbare
- Støtter **verticals** (filtrering etter connector)

**Confidence:** Verified (microsoft-learn docs_fetch)

### 3. Context IQ & microsoft365.com

**Copilot Connectors:**
- Connector content tilgjengelig i Context IQ (recommendations)
- Vises på microsoft365.com (unified experience)

**Confidence:** Verified (microsoft-learn docs_search)

### 4. Teams

**Message Extensions:**
- Kan fungere som plugins for M365 Copilot
- Søk/handlinger i eksterne tjenester via Adaptive Cards
- Utvides med **Bot Framework** eller **Teams AI library**

**Confidence:** Verified (microsoft-learn docs_search)

### 5. Copilot Studio

**Low-code alternativ:**
- Power Platform Connectors (prebuilt + custom)
- Integrerer med både Microsoft data og ISV-data
- Kan bruke **Graph API** for M365-data

**Confidence:** Verified (microsoft-learn docs_search)

### 6. Microsoft Foundry & Semantic Kernel

**Graph Actions:**
- Semantic Kernel er **påkrevd** for Graph Actions
- Kiota CLI genererer plugins fra OpenAPI spec
- Støtter **C#, Python, TypeScript** SDKs

**SDK-pakker:**
- .NET: `Microsoft.Agent.M365Copilot` (v1.0), `Microsoft.Agent.M365Copilot.Beta`
- Python: `microsoft-agents-m365copilot`, `microsoft-agents-m365copilot-beta`
- TypeScript: `@microsoft/agents-m365copilot`, `@microsoft/agents-m365copilot-beta`

**Confidence:** Verified (microsoft-learn docs_search)

---

## Offentlig sektor (Norge)

### Compliance & Data Residency

| Aspekt | Copilot Connectors | API Plugins | Graph Actions |
|--------|-------------------|-------------|---------------|
| **Data location** | External items i Microsoft Graph (tenant region) | API-data forblir i eksternt system | M365-data i tenant region |
| **GCC/GCCH support** | ✅ Ja (ikke DoD) | ✅ Ja (via declarative agents) | ✅ Ja (via M365 Copilot) |
| **Data processing** | Microsoft Graph (EU Data Boundary for EU tenants) | Eksternt API (utenfor Microsoft) | Microsoft Graph |
| **Audit logging** | Microsoft 365 audit logs | API-side logging (eksternt) | M365 audit logs |

**Offentlig sektor Norge:**
- **Copilot Connectors** og **Graph Actions** innenfor Microsoft 365 boundary (OK for Skytjenesteavtalen/DPA)
- **API Plugins** krever databehandleravtale med API-leverandør hvis persondata sendes

**Confidence:** Baseline (ekstrapolert fra M365 compliance docs)

### Tilgangskontroll

**Copilot Connectors:**
- Støtter **External Groups** for ikke-Entra ID ACL (f.eks. Salesforce permission sets, ServiceNow local groups)
- **Active Directory sync** påkrevd for security trimming (SharePoint Server connector)
- Brukere ser kun content de har tilgang til

**API Plugins:**
- Brukerbekreftelse (**confirmation prompts**) før data sendes
- Autentisering via **token store** (OAuth2, API keys)

**Graph Actions:**
- **Delegated permissions** (kjører som signed-in user)
- Respekterer Entra ID roller og policies

**Confidence:** Verified (microsoft-learn docs_fetch + docs_search)

### Schrems II & Datatilsynet

**Vurderinger:**
- **Copilot Connectors:** Data i Microsoft Graph → samme risikovurdering som Microsoft 365
- **API Plugins:** Tredjepartsdata → egen risikovurdering per API-leverandør
- **Graph Actions:** M365-data → innenfor Microsoft 365 DPA

**Anbefaling:** Gjennomfør DPIA for Copilot Connectors med sensitive persondata (samme prosess som for Microsoft Search).

**Confidence:** Baseline (juridisk ekstrapolering)

---

## Kostnad og lisensiering

### Copilot Connectors

| Kostnadselement | Detaljer |
|-----------------|----------|
| **Item quota** | Items konsumerer quota (se [licensing requirements](https://learn.microsoft.com/en-us/microsoftsearch/licensing)) |
| **Graph API calls** | Standard Graph API pricing (ingest/update/delete operations) |
| **Connector SDK** | Gratis (open source) |
| **Prebuilt connectors** | Over 100 tilgjengelig fra Microsoft og partnere (noen krever partnerlisens) |
| **Custom connector hosting** | Egen infrastruktur (Azure Functions, VM, on-prem) |

**Lisenskrav:**
- **Microsoft 365 E5** eller **Office 365 E5** for full Copilot connector support
- **Microsoft Search** inkludert i E3/E5

**Confidence:** Verified (microsoft-learn docs_fetch)

### API Plugins

| Kostnadselement | Detaljer |
|-----------------|----------|
| **API calls** | Eksternt API pricing (varierer per leverandør) |
| **Token store** | Inkludert i M365 Copilot (ingen ekstra kostnad) |
| **Declarative agent** | Krever M365 Copilot lisens (ca. $30/user/month) |
| **Development** | Microsoft 365 Agents Toolkit (gratis i VS Code) |

**Confidence:** Baseline (basert på M365 Copilot lisensmodell)

### Graph Actions (Semantic Kernel)

| Kostnadselement | Detaljer |
|-----------------|----------|
| **Graph API calls** | Inkludert i M365-lisens (delegated permissions) |
| **Semantic Kernel SDK** | Gratis (open source) |
| **LLM costs** | Avhenger av valgt modell (Azure OpenAI, OpenAI, etc.) |
| **Hosting** | Custom engine agent hosting (Azure App Service, Container Apps, etc.) |

**Confidence:** Baseline (Semantic Kernel OSS + Azure OpenAI pricing)

### TCO-sammenligning (norsk offentlig sektor)

**Scenario:** Indeksere 50 000 dokumenter fra fagsystem + tillate opprettelse av saker

| Løsning | Setup-kostnad | Årlig drift | Lisenskrav |
|---------|--------------|-------------|------------|
| **Connector + Plugin** | Middels (utvikling) | Lav (Graph quota + API calls) | M365 E5 + Copilot |
| **Kun Plugin** | Lav (API mapping) | Lav (API calls) | M365 E5 + Copilot |
| **Kun Connector** | Middels (utvikling) | Lav (Graph quota) | M365 E5 (Search OK, Copilot anbefalt) |
| **Graph Actions** | Høy (custom agent) | Middels-høy (hosting + LLM) | M365 E5 + Azure OpenAI |

**Anbefaling for norsk offentlig sektor:**
- **Start med Copilot Connectors** for read-only data (lavest kompleksitet)
- **Legg til API Plugins** for handlinger når declarative agents er GA
- **Vurder Graph Actions** kun for avanserte custom agents med M365-integrasjon

**Confidence:** Baseline (syntetisert kostnadsvurdering)

---

## For arkitekten (Cosmo)

### Anbefalinger

1. **Start med Copilot Connectors for kunnskapsbase**
   - Lavest barrier to entry
   - Gjenbrukbar i Search, Context IQ, Copilot
   - Bruk **prebuilt connectors** der tilgjengelig (100+ fra Microsoft/partnere)
   - Custom connector kun når prebuilt ikke finnes

2. **API Plugins krever declarative agents**
   - **Viktig:** API Plugins fungerer IKKE standalone i M365 Copilot business chat
   - Må pakkes som actions i declarative agent
   - Vurder om message extension (Teams) er bedre match for read/write scenarios

3. **Graph Actions for avanserte custom agents**
   - Bruk **prebuilt plugins** (ContactsPlugin, MessagesPlugin, CalendarPlugin, DriveItemsPlugin, M365 Copilot Plugin)
   - Kombinér flere plugins for multi-step workflows
   - Vurder Copilot Studio som low-code alternativ før custom Semantic Kernel agent

4. **Semantic indexing er key for Copilot Connectors**
   - Title + Content properties er semantisk indeksert
   - Semantic labels påvirker **ikke** indexing (kun filtering)
   - Rik tekstuelt innhold i `content` property
   - Bruk semantic labels (`title`, `url`, `iconUrl`) for Copilot UI

5. **Sikkerhet og compliance først**
   - External groups for ikke-Entra ID ACL
   - Confirmation prompts for API Plugins
   - Delegated permissions for Graph Actions
   - DPIA for Copilot Connectors med persondata

6. **Optimaliser for relevans**
   - `urlToItemResolver` + user activities → høyere scoring
   - Rich descriptions i connections
   - Meaningful titles på external items
   - Flere activities (view, modify, comment) = høyere viktighet

### Røde flagg

| Situasjon | Problem | Løsning |
|-----------|---------|---------|
| "Vi vil bruke API Plugin standalone i Copilot" | ❌ Ikke støttet | Bruk declarative agent eller message extension |
| "Vi indekserer binærfiler uten tekst-extraction" | ❌ Dårlig Copilot-relevans | Extract text før ingest i `content` property |
| "Vi hopper over semantic labels" | ❌ Dårlig UI i Copilot | Bruk minst `title`, `url`, `iconUrl` |
| "Vi bruker application permissions for Graph Actions" | ❌ Sikkerhetsrisiko | Bruk delegated permissions (user context) |
| "Vi bygger custom connector for SharePoint" | ❌ Unødvendig | Bruk prebuilt SharePoint connector |
| "Vi forventer real-time ingest til Copilot Connector" | ❌ Feil forventning | Schema provisioning er async, ingest tar tid |

**Confidence:** Baseline (arkitektråd basert på verified docs)

### Spørsmål å stille kunden

1. **Omfang:**
   - Hvor mange eksterne datakilder skal integreres?
   - Estimert antall items/dokumenter?
   - Hvor ofte oppdateres dataene?

2. **Funksjonalitet:**
   - Kun lesing (search/summarize) eller også handlinger (create/update)?
   - Må brukere kunne trigge actions fra Copilot?
   - Trenger dere M365-data (e-post, kalender) i samme workflow?

3. **Sikkerhet:**
   - Bruker dere Entra ID for alle brukere?
   - Finnes ikke-Entra ID grupper i eksterne systemer (f.eks. Salesforce roles)?
   - Persondata i eksterne systemer?

4. **Teknisk kapasitet:**
   - Har dere utviklere med Graph API-erfaring?
   - Kan dere hoste custom connector (Azure/on-prem)?
   - Foretrekker dere low-code (Copilot Studio) eller pro-code?

5. **Lisensiering:**
   - Har brukerne M365 Copilot lisens?
   - E3 eller E5?
   - Budget for item quota (Copilot Connectors)?

**Confidence:** Baseline (discovery-spørsmål)

---

## Kilder og verifisering

### Microsoft Learn (MCP-verified, januar 2026)

1. **Microsoft 365 Copilot connectors overview**
   https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/overview-copilot-connector
   *Verified via microsoft_docs_fetch*

2. **Work with the Copilot connectors API**
   https://learn.microsoft.com/en-us/graph/connecting-external-content-connectors-api-overview
   *Verified via microsoft_docs_fetch*

3. **Invoke Microsoft Graph actions with Semantic Kernel**
   https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/graph-actions-semantic-kernel
   *Verified via microsoft_docs_search*

4. **Build API plugins from an existing API for Microsoft 365 Copilot**
   https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/build-api-plugins-existing-api
   *Verified via microsoft_docs_search*

5. **Extend Microsoft 365 Copilot**
   https://learn.microsoft.com/en-us/microsoftteams/platform/archive/how-to-extend-copilot
   *Verified via microsoft_docs_search*

6. **Microsoft 365 Copilot extensibility overview**
   https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/
   *Verified via microsoft_docs_search*

7. **Copilot connector experiences**
   https://learn.microsoft.com/en-us/graph/connecting-external-content-experiences
   *Verified via microsoft_docs_search*

8. **Use the Copilot connectors API**
   https://learn.microsoft.com/en-us/graph/api/resources/connectors-api-overview?view=graph-rest-1.0
   *Verified via microsoft_docs_search*

9. **Adopt, extend and build Copilot experiences across the Microsoft Cloud**
   https://learn.microsoft.com/en-us/microsoft-cloud/dev/copilot/overview
   *Verified via microsoft_docs_search*

10. **Microsoft 365 Copilot extensibility samples**
    https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/samples
    *Verified via microsoft_docs_search*

### Code Samples (MCP-verified)

11. **Microsoft 365 Copilot APIs client libraries**
    https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/sdks/api-libraries
    *C#, Python, TypeScript SDK samples*

### Baseline Knowledge (Model knowledge, jan 2025)

- Schrems II vurderinger for norsk offentlig sektor
- TCO-kostnadsmodeller
- Compliance-anbefalinger for Datatilsynet
- Arkitekturbeslutningstrær

**Total kilder:** 11 MCP-verified URLs, 4+ code samples
**MCP calls:** 7 (3x docs_search, 2x docs_fetch, 1x code_sample_search, 1x ToolSearch)