ms-ai-architect/skills/ms-ai-advisor/references/copilot-extensibility/declarative-agents-fundamentals.md

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
Declarative agent manifest	JSON-fil med instructions, capabilities, conversation starters	Schema v1.6
App icons	Color og outline icon (obligatorisk)	PNG format
API plugin manifest (valgfritt)	OpenAPI-basert beskrivelse av actions	API plugin schema 2.4

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

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

Declarative Agent Manifest

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

{
  "$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:

"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:

@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
• Declarative agent architecture
• Declarative agent manifest schema 1.6
• Build declarative agents using Microsoft 365 Agents Toolkit
• Choose the right tool to build your declarative agent
• Agents for Microsoft 365 Copilot

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