ms-ai-architect/skills/ms-ai-engineering/references/agent-orchestration/declarative-vs-imperative-agent-design.md

# Declarative vs Imperative Agent Design Tradeoffs

**Last updated:** 2026-02
**Status:** GA
**Category:** Agent Orchestration & Automation
**Type:** reference

---

## Innhold

- [Introduksjon](#introduksjon)
- [Kjernekomponenter](#kjernekomponenter)
- [Declarative Agent Benefits](#declarative-agent-benefits)
- [Code-First Flexibility](#code-first-flexibility)
- [Migration Paths](#migration-paths)
- [Hybrid Approaches](#hybrid-approaches)
- [Skill Abstraction Levels](#skill-abstraction-levels)
- [Norsk offentlig sektor](#norsk-offentlig-sektor)
- [Beslutningsrammeverk](#beslutningsrammeverk)
- [For Cosmo](#for-cosmo)

## Introduksjon

Valget mellom deklarativ og imperativ agentdesign er en av de mest grunnleggende arkitekturbeslutningene for AI-agenter i Microsoft-økosystemet. Deklarative agenter konfigurerer atferd gjennom manifest-filer, instruksjoner og kunnskapskilder -- orkestratoren håndterer resonnering og utførelse. Imperative (code-first) agenter gir full kontroll over prompt engineering, orkestrering, verktøybruk og feilhåndtering gjennom eksplisitt kode.

Microsoft tilbyr et spektrum fra helt deklarativ (Copilot Studio declarative agents for M365) via low-code (Copilot Studio custom agents) til helt code-first (Semantic Kernel, Azure AI Agent Service, Microsoft Agent Framework). Hvert punkt på spekteret har ulike styrker, begrensninger og egnethet for forskjellige organisatoriske moduser og tekniske krav.

For mange organisasjoner er svaret ikke enten-eller, men en hybrid tilnærming der enkle scenarier håndteres deklarativt og komplekse scenarier implementeres med kode. Semantic Kernel Agent Framework støtter dette eksplisitt gjennom declarative YAML specs for agentdefinisjon kombinert med programmatisk orkestrering.

## Kjernekomponenter

| Komponent | Deklarativ | Imperativ |
|-----------|-----------|-----------|
| Definisjon | JSON/YAML manifest | C#/Python kode |
| Orkestrering | Copilot orchestrator | Semantic Kernel, custom |
| Modellvalg | Platform-bestemt | Utvikler-kontrollert |
| Verktøy | Connectors, plugins | Custom functions, API-kall |
| Deployment | M365 admin center | Azure-infrastruktur |
| Testing | Copilot Studio test agent | Unit tests, integration tests |

## Declarative Agent Benefits

### Rask time-to-value

```json
// Komplett declarative agent definisjon
{
    "name": "IT-Helpdesk",
    "description": "Hjelper ansatte med IT-problemer",
    "instructions": "Du er en IT-helpdesk-assistent for Direktoratet for digital tjenesteutvikling. Svar på spørsmål om tilganger, programvare og nettverksproblemer. Referer alltid til relevante KB-artikler. Eskalér til ServiceDesk hvis du ikke kan løse problemet.",
    "capabilities": [
        {"name": "WebSearch", "disabled": true},
        {"name": "CodeInterpreter", "disabled": false}
    ],
    "knowledge": {
        "sharepoint_sites": [
            "https://ddt.sharepoint.com/sites/IT-KB"
        ],
        "graph_connectors": ["servicenow-connector"]
    },
    "actions": [
        {
            "type": "connector",
            "connector": "ServiceNow",
            "operations": ["createIncident", "getIncidentStatus"]
        }
    ],
    "conversation_starters": [
        {"text": "Jeg trenger tilgang til..."},
        {"text": "Programmet mitt krasjer..."}
    ]
}
```

### Fordeler med deklarativ tilnærming

| Fordel | Beskrivelse | Konsekvens |
|--------|------------|------------|
| Ingen infrastruktur | Kjører på Copilots orkestrator | Null hosting-kostnad, null vedlikehold |
| Innebygd compliance | Arver M365 RAI og sikkerhet | Ingen separat sikkerhetsgjennomgang |
| Rask iterasjon | Endre instruksjoner uten kode-deploy | Minutter fra endring til produksjon |
| Bred distribusjon | Teams, Outlook, Word, Excel | Tilgjengelig der brukerne er |
| Citizen developer | Forretningsbrukere kan bygge og vedlikeholde | Redusert IT-avhengighet |

### Begrensninger

| Begrensning | Implikasjon |
|------------|------------|
| Begrenset orkestrererskontroll | Kan ikke styre resonneringslooper |
| Sekvensiell prosessering | Grounding og tool-calling er sekvensielt |
| Ingen egne modeller | Bundet til Copilots foundation model |
| Begrenset formatering | Adaptive Cards har begrensninger |
| Ingen CI/CD | Ingen native source control-støtte |

## Code-First Flexibility

### Semantic Kernel imperative agent

```python
from semantic_kernel import Kernel
from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
from semantic_kernel.functions import kernel_function

# Full kontroll over agentens oppførsel
kernel = Kernel()

# Velg eksakt modell
kernel.add_service(AzureChatCompletion(
    deployment_name="gpt-4o",
    endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_key=os.environ["AZURE_OPENAI_KEY"]
))

# Definer custom verktøy med full kontroll
class ITHelpDeskPlugin:
    @kernel_function(
        name="search_knowledge_base",
        description="Søk i IT-kunnskapsbasen"
    )
    async def search_kb(self, query: str) -> str:
        # Custom retrieval-logikk med re-ranking
        results = await self.search_client.search(
            query,
            filter=f"department eq 'IT'",
            semantic_configuration="kb-semantic-config",
            query_type="semantic"
        )
        # Custom re-ranking basert på brukerens rolle
        reranked = self.rerank_for_user(results, self.current_user)
        return self.format_results(reranked)

    @kernel_function(
        name="create_incident",
        description="Opprett sak i ServiceNow"
    )
    async def create_incident(
        self, title: str, description: str, priority: int
    ) -> str:
        # Custom validering og forretningslogikk
        if priority == 1 and not self._is_office_hours():
            await self._notify_on_call_team(title)

        incident = await self.servicenow_client.create(
            title=title,
            description=description,
            priority=priority,
            category="IT",
            assigned_group=self._determine_group(title)
        )
        return f"Sak {incident.number} opprettet"

kernel.add_plugin(ITHelpDeskPlugin(), "helpdesk")

# Opprett agent med full instruksjonskontroll
agent = ChatCompletionAgent(
    name="IT-HelpDesk-Agent",
    instructions="""...""",  # Detaljerte instruksjoner
    kernel=kernel,
    execution_settings=PromptExecutionSettings(
        temperature=0.1,  # Kontrollert kreativitet
        max_tokens=800,
        function_choice_behavior=FunctionChoiceBehavior.Auto()
    )
)
```

### Fordeler med code-first

| Fordel | Beskrivelse | Konsekvens |
|--------|------------|------------|
| Full orkestreringskontroll | Custom resonneringslooper | Komplekse multi-step workflows |
| Modellfleksibilitet | Velg modell per oppgave | Kostnadsoptimalisering |
| Custom verktøy | Hvilken som helst API/funksjon | Ubegrenset integrasjonsevne |
| Testbarhet | Unit tests, integration tests | Høyere kvalitetssikring |
| CI/CD | Standard DevOps-pipelines | Kontrollert deployment |
| Ytelsestuning | Token-optimalisering, caching | Bedre skaleringsevne |

## Migration Paths

### Fra deklarativ til imperativ

```
Steg 1: Start med declarative agent i Copilot Studio
        → Rask validering av brukerbehovet

Steg 2: Identifiser begrensninger
        → "Vi trenger custom retrieval-logikk"
        → "Vi trenger egen modell for sensitive data"
        → "Vi trenger kompleks orkestrering"

Steg 3: Migrer til code-first
        → Overfør instruksjoner til Semantic Kernel agent
        → Implementer custom verktøy som SK plugins
        → Behold Copilot Studio for enkle scenarier
```

### Fra imperativ til deklarativ

```
Steg 1: Identifiser agenter som er over-engineered
        → Agenten bruker kun standard RAG + enkle verktøy
        → Ingen custom orkestrering nødvendig

Steg 2: Konverter til declarative manifest
        → Instruksjoner → declarative instructions
        → SK plugins → Copilot connectors/API plugins
        → Custom RAG → SharePoint + Graph connectors

Steg 3: Reduser operasjonell overhead
        → Fjern hosting-infrastruktur
        → Overføre vedlikehold til forretningsteam
```

## Hybrid Approaches

### Semantic Kernel Declarative Spec

```yaml
# Hybrid: Deklarativ definisjon med programmatisk utførelse
type: chat_completion_agent
name: HybridHelpDesk
description: IT Helpdesk med deklarativ konfig og custom plugins
instructions: |
  Du er en IT-helpdesk-assistent.
  Bruk search_knowledge_base for å finne relevante KB-artikler.
  Opprett ServiceNow-sak ved eskalering.
model:
  id: gpt-4o
  connection:
    type: azure_openai
tools:
  - id: helpdesk.search_knowledge_base
  - id: helpdesk.create_incident
settings:
  temperature: 0.1
  max_tokens: 800
```

```python
# Last agent fra YAML
from semantic_kernel.agents import AgentRegistry

agent = await AgentRegistry.create_from_yaml(
    kernel=kernel,
    yaml_str=open("agent-spec.yaml").read()
)

# Kombinerer deklarativ konfigurasjon med programmatiske plugins
```

### Multi-tier arkitektur

```
┌─────────────────────────────────────────────────┐
│                Hybrid Architecture               │
│                                                  │
│  Tier 1: Declarative (Copilot Studio)           │
│  ├── FAQ-bots                                    │
│  ├── Informasjonsagenter                         │
│  └── Enkle workflow-agenter                      │
│                                                  │
│  Tier 2: Low-code (Copilot Studio + Power Auto) │
│  ├── Agenter med connector-integrasjoner         │
│  ├── Approval workflows                          │
│  └── Agenter med moderate krav                   │
│                                                  │
│  Tier 3: Code-first (Semantic Kernel / Foundry) │
│  ├── Multi-agent orkestrering                    │
│  ├── Custom modeller og RAG-pipelines            │
│  └── Høy-sikkerhets agenter                      │
└─────────────────────────────────────────────────┘
```

## Skill Abstraction Levels

| Abstraksjonsnivå | Verktøy | Målgruppe | Kontroll |
|-------------------|---------|-----------|----------|
| L0: No-code | Agent Builder i M365 Copilot | Sluttbrukere | Minimal |
| L1: Low-code | Copilot Studio | Citizen developers | Begrenset |
| L2: Low-code+ | Copilot Studio + connectors | Power users | Moderat |
| L3: Pro-code (deklarativ) | Agents Toolkit + YAML specs | Utviklere | Høy |
| L4: Pro-code (imperativ) | Semantic Kernel + custom code | Senior utviklere | Full |

## Norsk offentlig sektor

| Aspekt | Deklarativ | Imperativ |
|--------|-----------|-----------|
| Anskaffelse | Copilot-lisens | Azure-abonnement + utvikling |
| Kompetansekrav | Lav (forretningsbrukere) | Høy (utviklere) |
| Time-to-value | Dager | Uker |
| Compliance | Arvet fra M365 | Eget ansvar |
| Datalokalitet | EU Data Boundary | Azure Norway East |
| Vedlikehold | Forretningsteam | IT-avdeling |

### Anbefaling for offentlig sektor

```
Beslutningstre:

1. Er det et M365-sentrert scenario?
   → JA: Start med declarative agent
   → NEI: Gå til 2

2. Kreves custom modeller eller orkestrering?
   → JA: Code-first med Semantic Kernel
   → NEI: Gå til 3

3. Kreves integrasjon med virksomhetssystemer?
   → Enkel integrasjon: Copilot Studio + connectors
   → Kompleks integrasjon: Code-first

4. Hvem skal vedlikeholde?
   → Forretningsteam: Deklarativ
   → IT-avdeling: Code-first
```

## Beslutningsrammeverk

| Scenario | Anbefaling | Begrunnelse |
|----------|------------|-------------|
| FAQ-bot med M365-data | Declarative agent | Raskest, billigst, lavest risiko |
| Kundestøtte med CRM-integrasjon | Copilot Studio custom agent | Connectors + moderate tilpasninger |
| Multi-agent analyse-pipeline | Code-first Semantic Kernel | Krever full orkestreringskontroll |
| Intern IT-helpdesk | Hybrid: Declarative + code-first eskalering | Enkel start, eskalér ved behov |
| Regulatorisk rapportering | Code-first | Custom validering og compliance-krav |
| Pilot/POC | Declarative | Valider behov før investering i kode |

## For Cosmo

- **Start alltid deklarativt** med mindre kravene eksplisitt tilsier noe annet -- det er raskere, billigere og lettere å iterere. Konverter til code-first kun ved reelle begrensninger.
- **Hybrid er normalstilstanden** for enterprise -- enkle agenter i Copilot Studio, komplekse i Semantic Kernel. Design arkitekturen for at begge kan sameksistere.
- **Semantic Kernel YAML specs** er broen mellom deklarativ og imperativ -- definér agenten deklarativt, men utfør med programmatiske plugins. Gir det beste fra begge verdener.
- **Vurder vedlikeholdsmodell like mye som teknisk kapabilitet** -- hvem skal endre agentens oppførsel over tid? Forretningsbrukere trenger deklarativ, utviklere kan håndtere kode.
- **For norsk offentlig sektor**: Declarative agents med Copilot-lisens er kostnadseffektivt for informasjonsagenter. Code-first for saksbehandling og sensitive prosesser der kontroll og compliance er kritisk.