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
• Kjernekomponenter
• Declarative Agent Benefits
• Code-First Flexibility
• Migration Paths
• Hybrid Approaches
• Skill Abstraction Levels
• Norsk offentlig sektor
• Beslutningsrammeverk
• 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

// 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

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

# 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

# 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.