# Declarative Agents - Design and Implementation **Last updated:** 2026-06-19 | Verified: MCP 2026-06-19 **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.6): ```json { "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.6/schema.json", "version": "v1.6", "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. **Verified:** ISV store submission krav (Microsoft 365 validation guidelines): - Minst 3 prompt starters (conversation_starters) — Must fix - App manifest versjon 1.13 eller nyere — Must fix (seneste GA-versjon: 1.28, mai 2026; v1.29 dokumentert juni 2026) (Verified 2026-06) - Navn (`name`) MÅ være identisk i manifest.json, declarativeAgent.json og plugin.json — Must fix - Responstid ≤9 sekunder (99 percentil) — Must fix - Alle serverkall med HTTPS + TLS 1.2+ — Must fix **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-06-19