# Declarative Agents - Design and Implementation

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

---

## Introduksjon

Declarative agents er konfigurasjonsbaserte utvidelser av Microsoft 365 Copilot som lar organisasjoner tilpasse Copilot til spesifikke forretningsscenarier uten å skrive custom code. De kjører på samme orkestrator, foundation models og AI-tjenester som Microsoft 365 Copilot, og arver automatisk sikkerhets-, compliance- og styringsrammeverket fra Microsoft 365-økosystemet.

**Verified:** Declarative agents er GA (Generally Available) og støttes i Microsoft 365 Copilot, Teams, Word og PowerPoint. Begrenset støtte finnes for Government Community Cloud (GCC) tenants.

En declarative agent defineres gjennom tre hovedkomponenter:
- **Instructions** — Tilpassede instruksjoner som styrer agentens oppførsel og tone
- **Knowledge** — Tilkobling til enterprise-data (SharePoint, OneDrive, Microsoft 365 Copilot connectors)
- **Actions** — API plugins som integrerer med eksterne systemer i sanntid

Typiske bruksområder inkluderer:
- Employee IT self-help med kunnskapsbase fra SharePoint
- Customer support med integrasjon til order management systemer
- Team onboarding med organisasjonsspesifikk dokumentasjon
- Dokumentasjonsassistenter med tilgang til tekniske databaser

**Baseline:** Declarative agents egner seg best for scenarioer med enkel til moderat kompleksitet der oppgaven kan løses i én eller to grounding-operasjoner. De er ikke egnet for komplekse multi-step workflows eller scenarier som krever iterativ resonnering.

---

## Kjernekomponenter

### App Package Structure

En declarative agent pakkes som en Microsoft 365-app med følgende obligatoriske komponenter:

| Komponent | Beskrivelse | Schema |
|-----------|-------------|--------|
| **App manifest** | Microsoft 365 app manifest med `copilotAgents` node | [M365 app schema](https://learn.microsoft.com/en-us/microsoft-365/extensibility/schema) |
| **Declarative agent manifest** | JSON-fil med instructions, capabilities, conversation starters | [Schema v1.6](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.6) |
| **App icons** | Color og outline icon (obligatorisk) | PNG format |
| **API plugin manifest** (valgfritt) | OpenAPI-basert beskrivelse av actions | [API plugin schema 2.4](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/api-plugin-manifest-2.4) |

**Verified:** App manifest refererer til declarative agent manifest via `copilotAgents.declarativeAgents` array:

```json
"copilotAgents": {
  "declarativeAgents": [
    {
      "id": "MyAgent",
      "file": "declarativeAgent.json"
    }
  ]
}
```

### Declarative Agent Manifest

Minimumseksempel på declarative agent manifest (schema v1.5):

```json
{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json",
  "version": "v1.5",
  "name": "IT Support Assistant",
  "description": "Hjelper ansatte med IT-problemer basert på intern dokumentasjon",
  "instructions": "Du er en IT-support-spesialist. Hjelp brukere med tekniske problemer ved å søke i SharePoint-dokumentasjonen først. Hold en profesjonell og hjelpsom tone.",
  "conversation_starters": [
    {
      "title": "Hvordan resette passord",
      "text": "Hvordan resetter jeg passordet mitt?"
    }
  ],
  "capabilities": [
    {
      "name": "OneDriveAndSharePoint",
      "items_by_url": [
        {
          "url": "https://contoso.sharepoint.com/sites/ITSupport"
        }
      ]
    }
  ]
}
```

**Verified:** Nøkkelfelter i manifest:
- `name` og `description` — Brukes av både brukere og connected agents for å finne agenten
- `instructions` — Systemmelding som styrer agentens oppførsel (støtter markdown)
- `conversation_starters` — Forhåndsdefinerte prompts som hjelper brukere i gang
- `capabilities` — Array av capabilities (SharePoint, OneDrive, GraphConnectors, CodeInterpreter, etc.)
- `actions` — Referanser til API plugin manifests

### Capabilities

**Verified:** Tilgjengelige capabilities (schema v1.6):

| Capability | Beskrivelse | Bruksområde |
|------------|-------------|-------------|
| **OneDriveAndSharePoint** | Grounding mot SharePoint sites/folders | Intern dokumentasjon, policies |
| **GraphConnectors** | Microsoft 365 Copilot connectors | Eksterne datakilder (ServiceNow, Salesforce) |
| **WebSearch** | Bing web search | Offentlig informasjon |
| **CodeInterpreter** | Python code execution | Data analysis, visualisering |
| **People** | Org chart og people data | Finn eksperter, rapporteringslinjer |
| **TeamsMessages** | Teams chat og channel messages | Historisk kommunikasjon |

**Baseline:** Alle capabilities arver Microsoft 365's sikkerhetsmodell — brukeren ser kun data de har tilgang til.

### Actions (API Plugins)

Actions defineres i separate API plugin manifest-filer og refereres fra declarative agent manifest:

```json
"actions": [
  {
    "id": "OrderManagementPlugin",
    "file": "order-plugin.json"
  }
]
```

**Verified:** API plugin manifest beskriver:
- **Functions** — Operasjoner agenten kan utføre (OpenAPI-basert)
- **Authentication** — OAuth2, API key, eller None
- **Runtimes** — Hvor API-et kjører (REST endpoint eller Office Add-in)
- **Adaptive cards** — Strukturert visning av resultater (valgfritt)

**Baseline:** Declarative agents kan bruke flere plugins samtidig. Plugins kan også deles på tvers av flere agenter.

---

## Arkitekturmønstre

### Configuration-Based Architecture

Declarative agents bruker en konfigurasjonsdrevet tilnærming i stedet for custom code:

```
┌─────────────────────────────────────────┐
│   Microsoft 365 Copilot (User-facing)   │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│      Declarative Agent Manifest         │
│  • Instructions                         │
│  • Conversation Starters                │
│  • Capabilities                         │
│  • Actions                              │
└─────────────────┬───────────────────────┘
                  │
        ┌─────────┴──────────┐
        │                    │
┌───────▼─────┐    ┌────────▼────────┐
│ Capabilities │    │  API Plugins    │
│ • SharePoint │    │ • OpenAPI spec  │
│ • OneDrive   │    │ • Auth config   │
│ • Connectors │    │ • Functions     │
└──────────────┘    └─────────────────┘
        │                    │
┌───────▼────────────────────▼───────┐
│   Microsoft 365 Orchestrator       │
│   • Foundation Models (GPT-4)      │
│   • Grounding Pipeline             │
│   • Security & Compliance          │
└────────────────────────────────────┘
```

**Verified:** Utviklere kontrollerer kun instructions, knowledge sources og actions. Microsoft styrer orkestrering, modellvalg og sikkerhet.

### Data Flow Pattern

**Verified:** Declarative agents følger en sekvensiell dataflyt:

1. **User prompt** → Brukerens spørsmål mottas
2. **Instructions processing** → Custom instructions tilføyes som system context
3. **Grounding** → Søk i configured capabilities (SharePoint, connectors, etc.)
4. **Tool calling** → Kall til API plugins (hvis relevant)
5. **Response generation** → LLM genererer svar basert på grounded data
6. **Response delivery** → Svar presenteres i Copilot UI

**Viktig begrensning (Verified):** Grounding og tool calling skjer **sekvensielt**, ikke parallelt. Dette betyr:
- Agenten kan ikke iterere mellom grounding og actions
- Komplekse multi-step workflows støttes ikke
- Looped operations eller chained API calls er ikke mulig

### Technical Limits

**Verified:** Kjente tekniske begrensninger (schema v1.6):

| Limit Type | Value | Impact |
|------------|-------|--------|
| **Grounding record limit** | 50 items | Maks antall dokumenter/records fra capabilities |
| **Plugin response limit** | 25 items | Maks items fra API plugin responses |
| **Token limit** | ~4096 tokens* | Total context window inkl. instructions + data |
| **Timeout** | ~45 sekunder* | Inkluderer network latency + processing |

*Inkluderer Microsoft service overhead — design for ~66% av grensen.

**Baseline:** Disse begrensningene gjør declarative agents uegnet for:
- Full-document processing (store PDF-er, lange rapporter)
- Large dataset analysis
- Long-running workflows (over 30 sekunder)
- Paginering av API-resultater

---

## Beslutningsveiledning

### Når bruke Declarative Agents?

**Optimal fit (Verified):**
- **Information retrieval** — Søk og oppsummering fra SharePoint/connectors
- **Simple workflows** — 1-2 steg operasjoner (søk → svar, eller søk → API call → svar)
- **Productivity enhancement** — Hjelp til daglige oppgaver (onboarding, IT support, dokumentasjon)
- **Microsoft 365-sentrerte use cases** — Organisasjoner som allerede bruker M365 ecosystem

**Poor fit (Verified):**
- **Complex decision trees** — Multi-step workflows med conditional branching
- **Large data processing** — Analyse av store datasett eller hele dokumenter
- **Custom AI models** — Scenarier som krever spesialiserte modeller eller fine-tuning
- **Real-time streaming** — API-er som krever streaming responses
- **On-premises integration** — Systemer uten cloud-tilgjengelige API-er

### Decision Tree: Declarative vs. Custom Engine Agent

```
Trenger du kontroll over orchestration?
├─ JA → Custom Engine Agent (Azure Bot Framework)
└─ NEI
    └─ Trenger du mer enn 2-3 steg i workflow?
        ├─ JA → Custom Engine Agent
        └─ NEI
            └─ Bruker du primært M365-data?
                ├─ JA → Declarative Agent ✓
                └─ NEI
                    └─ Trenger du custom model/training?
                        ├─ JA → Custom Engine Agent
                        └─ NEI → Declarative Agent ✓
```

### Comparison: Declarative vs. Custom Engine Agents

| Aspekt | Declarative Agent | Custom Engine Agent |
|--------|-------------------|---------------------|
| **Utviklingsmodell** | Configuration (JSON) | Code (C#, Python, TypeScript) |
| **Orchestrator** | Microsoft-styrt | Developer-styrt |
| **Model** | GPT-4 (Microsoft-valgt) | Valgfri (inkl. custom) |
| **Hosting** | Microsoft 365 infrastructure | Azure Bot Service (kundestyrt) |
| **Kompleksitet** | Lav — ingen code | Høy — full kode-kontroll |
| **Time-to-market** | Dager-uker | Uker-måneder |
| **Maintenance** | Minimal (config changes) | Høy (code updates, deployment) |
| **Egnet for** | Business users, citizen developers | Professional developers |
| **Lisenskrav** | M365 Copilot eller Copilot Chat | M365 Copilot |

**Baseline:** Declarative agents er lavest barriere for entry, men også mest begrenset i funksjonalitet.

---

## Integrasjon med Microsoft-stakken

### Development Tools

**Verified:** Fire offisielle verktøy for å bygge declarative agents:

| Tool | Målgruppe | Approach | Styrker |
|------|-----------|----------|---------|
| **Microsoft 365 Agents Toolkit** (VS Code) | Pro developers | Pro-code | CI/CD, source control, TypeSpec support |
| **Copilot Studio** | Business users / low-code devs | Low-code | Power Platform integration, GUI-based |
| **Agent Builder** (M365 Copilot) | End users | No-code | Naturlig språk, raskest setup |
| **SharePoint** | Content managers | No-code | SharePoint-fokusert, enkel publisering |

**Verified:** Microsoft 365 Agents Toolkit støtter **TypeSpec** — et deklarativt språk som genererer manifests automatisk:

```typescript
@agent(
  "IT Support Assistant",
  "Hjelper ansatte med IT-problemer"
)
@instructions("""
  Du er en IT-support-spesialist.
  Søk alltid i SharePoint-dokumentasjonen først.
""")
@conversationStarter(#{
  title: "Passord reset",
  text: "Hvordan resetter jeg passordet?"
})
namespace ITSupportAgent {
  op sharepoint is AgentCapabilities.OneDriveAndSharePoint<
    ItemsByUrl = [{ url: "https://contoso.sharepoint.com/sites/IT" }]
  >;
}
```

**Baseline:** TypeSpec reduserer risiko for manifest-feil og gjør kode mer vedlikeholdbar, men krever VS Code + toolkit.

### Deployment & Distribution

**Verified:** Declarative agents distribueres via Microsoft 365 admin center:

1. **Package** — Generer `.zip` med app manifest, agent manifest, icons, plugin manifests
2. **Upload** — Last opp til M365 admin center (Integrated Apps)
3. **Approval** — Admin godkjenner agent (inkludert Responsible AI validation)
4. **Distribution** — Publish til:
   - **Personal** — Kun utvikler (testing)
   - **Group** — Spesifikke brukere/grupper
   - **Organization-wide** — Alle i tenant

**Verified:** Responsible AI (RAI) validation kjøres automatisk ved upload. Agents som feiler RAI må revideres (typisk instructions som bryter retningslinjer).

### Security & Compliance

**Verified:** Declarative agents arver automatisk:
- **Microsoft Entra ID** — Autentisering og identitet
- **Data Loss Prevention (DLP)** — M365 DLP policies
- **Information Protection** — Sensitivity labels, retention
- **Audit logging** — Alle agent-interaksjoner logges
- **Conditional Access** — Device compliance, location-based access

**Baseline:** Utviklere kan **ikke** disable disse kontrollene — de er innebygd i plattformen.

**Verified:** User data boundaries:
- Agenten ser kun data brukeren har tilgang til (SharePoint permissions respekteres)
- GraphConnector data følger connector-spesifikke ACLs
- API plugin calls gjøres med user's identity (delegated permissions) eller app identity (application permissions)

---

## Offentlig sektor (Norge)

### Databehandling og GDPR

**Baseline:** Declarative agents prosesserer data i Microsoft 365 cloud:
- **Data residency** — Bruk Microsoft 365 Multi-Geo for å sikre data forblir i EU/Norge-region
- **GDPR compliance** — Microsoft 365 er GDPR-compliant, men organisasjonen må fortsatt:
  - Dokumentere databehandlingsavtale (DPA) med Microsoft
  - Gjennomføre DPIA (Data Protection Impact Assessment) for agents med sensitive data
  - Informere brukere om at Copilot prosesserer personopplysninger

**Baseline:** Microsoft Commercial Data Protection Addendum (DPA) dekker Copilot/agents, men sjekk med juridisk avdeling for offentlig sektor-spesifikke krav.

### Integrasjon med offentlige fagsystemer

**Verified:** API plugins kan integrere med:
- **Cloud-baserte API-er** — Offentlig tilgjengelige REST APIs (egnet for SaaS fagsystemer)
- **On-premises systemer** — Krever Azure API Management eller Application Gateway som mellomlag

**Baseline:** Mange norske offentlige systemer (Altinn, Folkeregisteret, osv.) har ikke moderne REST API-er. Vurder:
- **Modernisering** — Wrap legacy systemer i REST API (Azure Functions, API Management)
- **Alternative arkitekturer** — Bruk Power Automate som mellomlag (cloud flows kan kalle on-prem data gateways)

### GCC Tenant Support

**Verified:** Begrenset støtte for declarative agents i Government Community Cloud (GCC):
- **GCC** — Støttet (begrenset funksjonalitet)
- **GCC High / DoD** — Ikke støttet (per feb 2026)

**Baseline:** Norske offentlige virksomheter bruker typisk commercial M365, ikke GCC. Dette er ikke en blocker, men vær oppmerksom på at noen features kan rulle ut senere til GCC.

### Anbefalinger for offentlig sektor

| Scenario | Anbefaling |
|----------|------------|
| **Borgertjenester** | Unngå lagring av sensitive personopplysninger i agent instructions/knowledge. Bruk API plugins med dynamic data fetch. |
| **Saksbehandling** | Kombiner declarative agent med Power Automate for komplekse workflows (agent → trigger flow → fagsystem). |
| **Intern IT-support** | Lavt risikonivå — egnet for declarative agents med SharePoint knowledge base. |
| **Dokumentasjonssøk** | Ideell use case — bruk OneDriveAndSharePoint capability med site-spesifikke permissions. |

---

## Kostnad og lisensiering

### License Requirements

**Verified:** Declarative agents krever én av følgende lisenser:

| Lisens | Pris (ca. NOK/mnd/user) | Capabilities | Target User |
|--------|-------------------------|--------------|-------------|
| **Microsoft 365 Copilot** | ~3500 NOK | Full funksjonalitet (all capabilities, API plugins) | Knowledge workers |
| **Microsoft 365 Copilot Chat** | Gratis* | Begrenset (no GraphConnectors, no CodeInterpreter) | Alle M365-brukere |

*Copilot Chat er inkludert i M365 E3/E5 uten ekstrakostnad (fra 2024).

**Baseline:** For offentlig sektor: Vurder om alle brukere trenger full Copilot-lisens, eller om mange kan bruke Copilot Chat-baserte agents.

### Cost Components

**Verified:** Kostnadskomponenter for declarative agents:

| Komponent | Kostnad | Modell |
|-----------|---------|--------|
| **Microsoft 365 Copilot license** | ~3500 NOK/mnd/user | Per-user subscription |
| **Microsoft 365 Copilot Chat** | Inkludert i M365 E3/E5 | No extra cost |
| **API plugin hosting** | Varierer | Azure consumption (Functions, API Management) |
| **GraphConnector data** | Varierer | Connector-spesifikk (ServiceNow, Salesforce, etc.) |
| **Storage (SharePoint)** | Inkludert i M365 | No extra cost (innenfor tenant quota) |

**Baseline:** Den største kostnaden er Copilot-lisenser. API plugin hosting er typisk minimal (Azure Functions consumption er billig for lav-moderate volumer).

### ROI Considerations

**Baseline:** ROI-beregning for declarative agents:

**Gevinster:**
- **Tidsbesparelse** — Ansatte finner informasjon raskere (estimat: 5-10% produktivitetsøkning)
- **Redusert support load** — Selvbetjening via agent reduserer tickets til IT/HR
- **Raskere onboarding** — Nye ansatte finner svar selv

**Kostnader:**
- **Lisensiering** — M365 Copilot lisens per user
- **Utvikling** — Lavt for no-code/low-code, høyere for pro-code med API plugins
- **Vedlikehold** — Minimal (config updates, knowledge base refresh)

**Anbefaling:** Start med pilot (10-50 brukere) for å måle faktisk tidsbesparelse før full utrulling.

---

## For arkitekten (Cosmo)

### Assessment Framework

Når en kunde spør om declarative agents, vurder disse dimensjonene:

**1. Workflow Complexity**
- ✅ **Lavt** — Single-step retrieval (søk i SharePoint → svar)
- ✅ **Moderat** — Two-step (søk → API call → svar)
- ⚠️ **Høyt** — Multi-step med conditional logic → Vurder Custom Engine Agent

**2. Data Sources**
- ✅ **M365-native** — SharePoint, OneDrive, Teams → Perfekt fit
- ✅ **Cloud APIs** — REST APIs med OpenAPI spec → Bruk API plugins
- ⚠️ **On-premises** — Legacy systemer → Krever modernisering/gateway
- ❌ **Custom corpus** — Egne embeddings/vector DB → Bruk Copilot Studio med custom knowledge

**3. User Base**
- ✅ **M365 Copilot licensed** — Full funksjonalitet
- ⚠️ **Mixed licensing** — Noen brukere har kun Copilot Chat → Design for laveste felles nevner
- ❌ **External users** — Declarative agents støtter ikke B2C scenarios

**4. Development Maturity**
- ✅ **Citizen developers** — Bruk Agent Builder eller Copilot Studio
- ✅ **Pro developers** — Bruk Agents Toolkit + TypeSpec
- ⚠️ **Complex requirements** — Vurder om declarative er tilstrekkelig, eller om Custom Engine Agent trengs

### Common Pitfalls

**Verified:** Vanlige feil ved implementering:

| Feil | Symptom | Løsning |
|------|---------|---------|
| **For generiske instructions** | Agent gir irrelevante svar | Bruk spesifikke, scenario-fokuserte instructions med eksempler |
| **For mange capabilities** | Agent er treg, gir for brede svar | Begrens til 2-3 capabilities som er nødvendige |
| **Manglende conversation starters** | Brukere vet ikke hva agenten kan | Legg til 3-5 representative starters |
| **API plugin timeouts** | Agent feiler med 45-sek timeout | Optimaliser API for raskere response (<30 sek) |
| **Overveldende grounding data** | Agent overskrider 50-item limit | Pre-filter data i API plugin, eller bruk mer spesifikke SharePoint-paths |

### Testing Strategy

**Baseline:** Anbefalte testfaser:

1. **Developer testing** — Personal deployment, test med egen bruker
2. **Pilot testing** — 5-10 testbrukere, samle feedback på nøyaktighet og brukervennlighet
3. **Limited rollout** — 50-100 brukere, monitor for RAI violations og performance issues
4. **Full deployment** — Organization-wide, med kontinuerlig monitoring

**Verified:** Bruk developer mode i Copilot for debugging:
- Skriv `debug on` i Copilot chat for å se agent title ID og grounding sources
- Nyttig for å verifisere at riktig SharePoint-site er i scope

### Integration Patterns

**Baseline:** Vanlige integrasjonsmønstre:

**Pattern 1: SharePoint Knowledge Base**
```
User → Declarative Agent → SharePoint capability → Grounding → Response
```
Bruk når: Intern dokumentasjon, policies, FAQ

**Pattern 2: API Plugin for Real-Time Data**
```
User → Declarative Agent → API Plugin → External API → Response
```
Bruk når: Live data (order status, ticket status, inventory)

**Pattern 3: Hybrid (Knowledge + Action)**
```
User → Agent → SharePoint grounding → Context
                ↓
             API Plugin → External system → Enriched response
```
Bruk når: Trenger både statisk knowledge og live data (f.eks. "finn policy + sjekk om bruker har tilgang")

**Pattern 4: Power Automate Bridge**
```
User → Agent → API Plugin → Power Automate HTTP trigger → Complex workflow → Response
```
Bruk når: Declarative agent trenger multi-step workflow (workaround for sekvensiell begrensning)

### Governance Checklist

**Baseline:** Før production deployment:

- [ ] **Responsible AI validation** passert
- [ ] **Security review** — Verifiser at agent ikke eksponerer sensitive data
- [ ] **DPA/DPIA** — Dokumenter databehandling (hvis personopplysninger)
- [ ] **User training** — Informer brukere om hva agenten kan/ikke kan gjøre
- [ ] **Naming convention** — Bruk tydelige, beskrivende navn (ikke generiske som "AI Assistant")
- [ ] **Monitoring plan** — Definer KPIer (bruk, tilfredshet, tidsbesparelse)
- [ ] **Update cadence** — Plan for hvordan knowledge base oppdateres (SharePoint content refresh)

---

## Kilder og verifisering

**Verified sources (MCP microsoft-learn):**
- [Declarative agents for Microsoft 365 Copilot — Overview](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/overview-declarative-agent)
- [Declarative agent architecture](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/declarative-agent-architecture)
- [Declarative agent manifest schema 1.6](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/declarative-agent-manifest-1.6)
- [Build declarative agents using Microsoft 365 Agents Toolkit](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/build-declarative-agents)
- [Choose the right tool to build your declarative agent](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/declarative-agent-tool-comparison)
- [Agents for Microsoft 365 Copilot](https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/agents-overview)

**Baseline (modellkunnskap):**
- Cost estimates (Microsoft publiserer ikke offisielle priser — estimater fra offentlige sources)
- ROI-beregninger (bransjestandarder)
- Offentlig sektor-anbefalinger (basert på generell kunnskap om norsk forvaltning)

**Sist verifisert:** 2026-02-04
