ms-ai-architect/skills/ms-ai-advisor/references/copilot-extensibility/custom-engine-agents-development.md

# Custom Engine Agents - Advanced Configuration

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

---

## Introduksjon

Custom engine agents representerer det mest avanserte nivået av Copilot-utvidelse. Mens declarative agents bruker Microsofts innebygde orkestrator og modeller, gir custom engine agents utviklere **full kontroll** over AI-stack, orkestreringslogikk og dataintegrasjoner.

Dette er den eneste typen agent som tillater:
- Egne AI-modeller (foundation, fine-tuned, small language models, industry-specific)
- Custom orkestreringslogikk (Semantic Kernel, LangChain, egenutviklet)
- Proaktiv automatisering og agent-til-agent-kommunikasjon
- Multi-kanal deployment (M365 Copilot, Teams, egne applikasjoner)

**Viktig:** Custom engine agents krever **egen hosting** (typisk Azure), noe som påvirker både kostnader og arkitektur.

---

## Kjernekomponenter

### 1. Arkitekturell frihet

Custom engine agents kombinerer Microsofts infrastruktur med utviklerkontrollerte komponenter:

| Komponent | Kontroll | Beskrivelse |
|-----------|----------|-------------|
| **Klientgrensesnitt** | Microsoft | M365 Copilot, Teams, Outlook, Word, Excel |
| **Agent-katalog** | Microsoft | Publikasjon og oppdagelse via M365 Agent Store |
| **Orkestrering** | Utvikler | Full kontroll over workflow-logikk og AI routing |
| **AI-modeller** | Utvikler | Valgfritt: Azure OpenAI, OpenAI, egne modeller |
| **API-integrasjoner** | Utvikler | Eksterne datasystemer og tjenester |
| **Hosting** | Utvikler | Azure App Service, Container Apps, eller andre plattformer |

### 2. Tre kjerneegenskaper (Verified)

1. **Custom Orchestration**
   - Definer skreddersydde workflows
   - Koble til eksterne systemer
   - Integrer én eller flere språkmodeller
   - Implementer kompleks beslutningslogikk

2. **Flexible AI Models**
   - Foundation models (GPT-4, GPT-4o, Claude, osv.)
   - Small language models (Phi, osv.)
   - Fine-tuned models for domene-spesifikke bruksområder
   - Industry-specific AI (healthcare, legal, finance)

3. **Proactive Automation**
   - Programmatisk oppstart av workflows
   - Agent-til-agent-kommunikasjon (A2A)
   - Asynkrone meldinger og langtidsprosesser
   - Proaktive notifikasjoner basert på triggers

### 3. Nøkkelkarakteristikker (Verified)

| Aspekt | Detaljer |
|--------|----------|
| **Hosting** | Krever egen hosting (Azure, AWS, GCP, on-prem) med ekstra kostnader |
| **Tooling** | Low-code (Copilot Studio) eller pro-code (Visual Studio/VS Code + Agents Toolkit) |
| **Kanaler** | M365 Copilot, Teams, Word, Excel, Outlook + eksterne apps og websider |
| **Språk** | C#, JavaScript/TypeScript, Python (avhenger av SDK-valg) |
| **Samarbeid** | Støtter agent-til-agent-kommunikasjon og task delegation |
| **Manifest** | Krever app manifest versjon 1.21 eller nyere |

---

## Arkitekturmønstre

### Utviklingstilnærminger

Microsoft tilbyr **fire hovedveier** for å bygge custom engine agents:

#### 1. Copilot Studio (Low-code)

**Når:** Rask utvikling uten store utviklerressurser

| Fordel | Ulempe |
|--------|--------|
| Fully managed SaaS-plattform | Begrenset kontroll over orkestrering |
| Innebygd compliance via Power Platform | Ikke ideelt for komplekse workflows |
| Prebuilt templates og connectors | Lavere fleksibilitet på AI-modellvalg |
| Ingen infrastruktur-setup | - |

**Best for:** HR-assistenter, FAQs, standard workflows med M365-data

#### 2. Microsoft 365 Agents SDK (Pro-code)

**Når:** Full kontroll, multi-kanal, kompleks orkestrering

| Egenskap | Verdi |
|----------|-------|
| **Framework** | Full-stack, multi-channel framework |
| **Orkestrator** | Bring your own (Semantic Kernel, LangChain, custom) |
| **AI-modeller** | Hvilken som helst (Azure OpenAI, OpenAI, egne) |
| **Kanaler** | M365 Copilot, Teams, partner apps, custom apps, websites |
| **Språk** | C#, JavaScript, Python |
| **Tooling** | Visual Studio / VS Code med Agents Toolkit |

**Templates tilgjengelig:**
- Echo Agent / Empty Agent (minimal baseline)
- Weather Agent (med Azure Foundry/OpenAI pre-configured)

**Best for:** ISVs, enterprise scenarios med multi-kanal krav, avanserte workflows

**Verified Code Pattern:**
```javascript
import { AgentApplication, MessageFactory } from '@microsoft/agents-hosting'

const agent = new AgentApplication()

agent.onMessage(async (context) => {
    const replyText = `Echo: ${context.activity.text}`
    await context.sendActivity(MessageFactory.text(replyText))
})
```

#### 3. Teams SDK (Pro-code)

**Når:** Teams-sentrisk, group collaboration scenarios

| Egenskap | Verdi |
|----------|-------|
| **Framework** | Teams-centric interface |
| **Orkestrator** | Built-in Action Planner |
| **AI-modeller** | GPT-based models (Azure OpenAI, OpenAI) |
| **Kanaler** | M365 Copilot, Microsoft Teams |
| **Språk** | C#, TypeScript, JavaScript, Python |
| **Ny funksjonalitet (v2)** | Agent2Agent (A2A), Model Context Protocol (MCP) |

**Best for:** Collaborative agents i Teams channels/meetings, real-time brukerinteraksjon

#### 4. Microsoft Foundry Integration

**Når:** Eksisterende AI-logikk i Foundry som skal gjøres tilgjengelig i M365

To integrasjonsveier:

| Via Foundry Portal | Via Agents Toolkit |
|-------------------|-------------------|
| Publiser direkte fra Foundry | Koble via proxy-app |
| Auto-provision Azure Bot Service + Entra ID | Avansert customization, debugging, multi-env |
| Minimal code changes | Støtte for SSO, managed infrastructure |
| Rask deployment og testing | Full utviklerkontroll |

**Best for:** Organisasjoner som allerede bruker Foundry for AI-utvikling

---

## Beslutningsveiledning

### Verktøysammenligning (Verified)

| Feature | Copilot Studio | Teams AI | Agents SDK | Foundry |
|---------|---------------|----------|------------|---------|
| **Dev approach** | Low-code | Pro-code | Pro-code | Low/Pro-code |
| **Publishing** | Org only | Org + ISV/store | Org + ISV/store + 10+ kanaler | Org + ISV/store |
| **Channels** | M365, Teams, partner apps, mobile, web | M365, Teams | M365, Teams, partner, mobile, web | M365, Teams (andre via custom) |
| **Productivity** | Individual | Group | Group | Individual |
| **Orchestrator** | Copilot Studio | Teams AI Action Planner | BYO (SK, LC) | BYO (SK, LC) |
| **AI Models** | Copilot Studio | Valgfritt | Valgfritt | Foundry OpenAI/custom |
| **Språk** | N/A | C#, TS, JS, Python | C#, JS, Python | Python, C# |

### Scenariobasert valg (Verified)

| Scenario | Beskrivelse | Anbefalt tilnærming |
|----------|-------------|---------------------|
| **Legal case analysis** | Advokatfirma med custom-trained LLM for case law + eksterne juridiske databaser. Agenten brukes i case management system, men skal også være tilgjengelig i M365 Copilot med tilgang til SharePoint. | **Foundry** — Oppretthold custom AI-logikk i Foundry, publiser til M365 via Foundry portal eller Agents Toolkit |
| **Surgical planning** | Sykehus som bygger agent for kirurgiske team (leger, sykepleiere, admin). Agenten integreres med pasientinfo og scheduling, fasiliterer samarbeid om planlegging, avtaler, konflikter, påminnelser. | **Teams SDK** — Multi-user collaborative environment i Teams channels/meetings. Built-in Action Planner kobler til scheduling/pasient-systemer |
| **Employee onboarding** | Lightweight AI-assistent for nye ansatte til HR FAQs, dokumentfullføring, intern ressurs-navigasjon. Mesteparten av prosesser og dokumentasjon finnes i M365. | **Copilot Studio** — Rask low-code deployment. Built-in M365 knowledge og connectors. Enkle workflows uten custom AI-modeller |

### Nøkkelkriterier for valg

1. **Publishing scope**
   - Kun Teams SDK, M365 Agents SDK og Foundry kan publiseres til Microsoft Commercial Store

2. **Group productivity**
   - For multi-user scenarios i Teams: Velg Teams SDK (built-in collaborative support)

3. **Customization needs**
   - Full kontroll over AI-modeller/orkestrering: M365 Agents SDK eller Foundry via Toolkit

4. **Knowledge source access**
   - Copilot Studio: Native tilgang til M365 og Copilot connector content
   - Pro-code agents: Tilgang via Microsoft Graph APIs og Retrieval API

---

## Integrasjon med Microsoft-stakken

### 1. Datakilder og Knowledge Access

| Tilnærming | Metode |
|-----------|--------|
| **Copilot Studio** | Native tilgang til M365, Copilot connectors |
| **Pro-code (Agents SDK, Teams SDK, Foundry)** | Microsoft Graph API, Retrieval API for grounding i M365-data |

**Verified: SharePoint Integration Pattern (TypeSpec):**
```typescript
namespace MyAgent {
  op od_sp is AgentCapabilities.OneDriveAndSharePoint<ItemsByUrl = [
    {
      url: "https://contoso.sharepoint.com/sites/ProductSupport"
    }
  ]>;
}
```

### 2. Asynchronous Patterns (Verified)

Custom engine agents støtter tre typer asynkrone mønstre:

| Mønster | Beskrivelse | Use Case |
|---------|-------------|----------|
| **Follow-up messages** | Varsle bruker om status på request/job | IT-agent oppdaterer bruker når laptop-kjøp er godkjent |
| **Long-running tasks** | Prosesser som tar lang tid; bruker kan fortsette å chatte | Document management agent prosesserer batch av kontrakter |
| **Proactive messages** | Agent-initierte meldinger basert på triggers | Påminnelser, alerts, scheduled notifications |

**Viktig:** Copilot Studio-agents støtter IKKE asynkrone meldinger (Baseline knowledge).

**Verified Pattern (Teams SDK):**
```javascript
// Use SendActivity/SendActivityAsync in async/await pattern
await context.sendActivity('Processing started...')
// long-running process
await context.sendActivity('Processing complete!')
```

### 3. Streaming Behavior (Verified)

For å opprettholde konsistent meldingsrekkefølge:

1. **Bruk én streaming sequence per user turn**
   Opprett én `StreamingResponse`-objekt, finaliser med `endStream()` før nye meldinger

2. **Attach media inne i stream**
   Bruk `setAttachments()` i stedet for separate non-streaming activities

3. **Ikke start ny stream før forrige er finalisert**
   Multiple streams kan produsere uforutsigbar rekkefølge

4. **Serialiser utgående meldinger**
   Unngå parallelle meldinger fra flere threads

5. **Ikke send streaming updates etter `endStream()`**
   Bruk `replyToId` for follow-up meldinger

### 4. Observability & Telemetri (Verified)

Microsoft tilbyr observability SDK for custom engine agents:

**Installation:**
```bash
# .NET
dotnet add package Microsoft.Agents.A365.Observability
dotnet add package Microsoft.Agents.A365.Observability.Runtime

# JavaScript/TypeScript
npm install @microsoft/agents-a365-observability
npm install @microsoft/agents-a365-runtime
```

**Verified Pattern (TypeScript):**
```typescript
import {
  InferenceOperationType,
  InferenceScope,
  ObservabilityManager
} from '@microsoft/agents-a365-observability';

const sdk = ObservabilityManager.configure(b =>
  b.withService('<service-name>', '<version>')
);

sdk.start();

async invokeAgentWithScope(prompt: string) {
  const scope = InferenceScope.start(
    {
      operationName: InferenceOperationType.CHAT,
      model: '<llm-name>'
    },
    {
      agentId: '<agent-id>',
      agentName: '<agent-name>',
      conversationId: '<conv-id>'
    },
    { tenantId: '<tenant-id>' }
  );

  const response = await this.invokeAgent(prompt);
  scope?.recordInputMessages([prompt]);
  scope?.recordOutputMessages([response]);
  scope?.recordResponseId(`resp-${Date.now()}`);
  return response;
}
```

### 5. Notifications (Verified)

Agents kan sende proaktive notifikasjoner:

**C# Import:**
```csharp
using Microsoft.Agents.Hosting;
using Microsoft.Agents.A365.Notifications;
using Microsoft.Agents.A365.Notifications.Extensions;
using Microsoft.Agents.A365.Notifications.Models;
```

**JavaScript Import:**
```javascript
import { AgentApplication, TurnContext, TurnState } from '@microsoft/agents-hosting';
import { ActivityTypes } from '@microsoft/agents-activity';
import {
  AgentNotificationActivity,
  NotificationType
} from '@microsoft/agents-a365-notifications';
```

---

## Offentlig sektor (Norge)

### Compliance & Governance

| Aspekt | Copilot Studio | Pro-code (Agents SDK/Teams SDK/Foundry) |
|--------|---------------|----------------------------------------|
| **Datalagring** | Power Platform compliance (europeiske datasentre) | Azure Norway East/West (full kontroll) |
| **Audit logging** | Built-in via Power Platform Admin Center | Microsoft Purview, Content Search |
| **GDPR** | Automatisk compliance via Power Platform | Utviklers ansvar via Azure-konfigurasjon |
| **Responsible AI** | Built-in RAI policies | Må implementeres manuelt (Azure AI Content Safety) |

### Anbefalinger for offentlig sektor

1. **Datasuverenitet:**
   - Bruk Azure Norway East/West for hosting
   - Konfigurer data residency policies i M365 tenant
   - Verifiser at AI-modeller kjører i EU-region (Azure OpenAI Norway East støttes)

2. **Transparency krav:**
   - Implementer observability SDK for full audit trail
   - Logg alle AI-interaksjoner med metadata (bruker, tenant, timestamp)
   - Bruk Microsoft Purview for data governance

3. **Sikkerhet:**
   - Entra ID for autentisering
   - Conditional Access policies for agent-tilgang
   - Azure Key Vault for secrets management
   - Vurder Customer Lockbox for sensitive data

4. **Testing & Validering:**
   - Bruk Microsoft 365 Agents Playground for lokal testing:
   ```bash
   npm install -g @microsoft/teams-app-test-tool
   teamsapptester
   ```
   - Implementer systematisk testing av RAI-policies før produksjon

---

## Kostnad og lisensiering

### Hosting-kostnader

Custom engine agents krever **egen hosting** — dette er den største kostnadsforskjellen fra declarative agents:

| Hosting-alternativ | Estimert kostnad (NOK/måned) | Use Case |
|-------------------|------------------------------|----------|
| **Azure App Service (Basic B1)** | ~400 NOK | Testing, low-traffic agents |
| **Azure App Service (Standard S1)** | ~600 NOK | Production, moderate traffic |
| **Azure Container Apps (Consumption)** | Fra ~200 NOK | Serverless, variabel trafikk |
| **Azure Kubernetes Service (AKS)** | Fra ~2500 NOK | Enterprise-scale, multi-agent |

**Merknad:** Kostnader varierer basert på region (Norway East typisk 5-10% høyere enn West Europe).

### AI-modell-kostnader

| Modell | Input (NOK/1M tokens) | Output (NOK/1M tokens) |
|--------|----------------------|------------------------|
| **GPT-4o (Azure OpenAI)** | ~55 NOK | ~165 NOK |
| **GPT-4o-mini** | ~1.7 NOK | ~6.6 NOK |
| **GPT-4 Turbo** | ~110 NOK | ~330 NOK |

**Estimert bruk:** En typisk enterprise-agent med 1000 brukere, 5 interaksjoner/dag, 500 tokens per interaksjon:
- GPT-4o-mini: ~8000 NOK/måned
- GPT-4o: ~55 000 NOK/måned

### Lisensiering

| Komponent | Krav |
|-----------|------|
| **Utviklere** | Visual Studio subscription (Professional/Enterprise) for pro-code |
| **Sluttbrukere** | M365 Copilot-lisens (3990 NOK/bruker/år) for tilgang i M365 Copilot |
| **Teams-only agents** | Teams-lisens tilstrekkelig (inkludert i M365 E3/E5) |
| **Azure-ressurser** | Azure subscription (ingen spesifikk M365-binding) |

### Total Cost of Ownership (TCO) eksempel

**Scenario:** Enterprise-agent for 500 brukere, moderate workflows, Azure Norway East hosting

| Komponent | Kostnad/måned |
|-----------|--------------|
| Azure App Service (S1) | 600 NOK |
| Azure OpenAI (GPT-4o-mini) | 4000 NOK |
| Azure Storage | 50 NOK |
| Azure Application Insights | 200 NOK |
| **Total** | **~4850 NOK/måned** |

**Copilot Studio-alternativ:** ~0 NOK ekstra hosting (SaaS), men høyere AI-consumption charges (Baseline knowledge).

---

## For arkitekten

### Når anbefale custom engine agents?

✅ **JA** hvis kunden trenger:
- Custom AI-modeller (fine-tuned, industry-specific, small language models)
- Kompleks orkestreringslogikk (multi-step workflows, conditional routing)
- Proaktive agents med automatisert triggering
- Multi-kanal deployment (M365 + eksterne apps/websites)
- Agent-til-agent-kommunikasjon (A2A patterns)
- Full kontroll over dataflyt og hosting (compliance-krav)

❌ **NEI** hvis kunden har:
- Enkle Q&A scenarios (bruk declarative agents)
- Begrensede utviklerressurser (bruk Copilot Studio)
- Kun M365-data som knowledge source (declarative agents holder)
- Tight budget uten rom for hosting-kostnader

### Nøkkelspørsmål å stille

1. **Teknisk kapasitet:**
   - Har dere utviklere med erfaring i C#/JavaScript/Python?
   - Kan dere drifte Azure-infrastruktur?

2. **Funksjonelle krav:**
   - Trenger dere custom AI-modeller eller holder Azure OpenAI?
   - Skal agenten trigges automatisk eller kun reagere på bruker?
   - Skal agenten kommunisere med andre agents?

3. **Compliance & Sikkerhet:**
   - Må data lagres i Norge/EU?
   - Kreves full audit trail av AI-interaksjoner?
   - Har dere krav om Customer Lockbox?

4. **Kostnad:**
   - Hva er budsjett for hosting + AI-consumption?
   - Er det rom for variable kostnader basert på bruk?

### Migration Paths

**Fra declarative agent til custom engine:**
1. Oppdater app manifest fra `declarativeAgents` til `customEngineAgents` node
2. Legg til `bots` node med bot ID
3. Bump app manifest versjon til 1.21+
4. Deploy custom engine logic til Azure
5. Test i M365 Agents Playground før produksjon

**Fra Teams bot til custom engine agent:**
- Bruk Microsoft 365 Agents SDK migration guide (Bot Framework → Agents SDK)
- **Verified:** Simplify server setup med `startServer()`:
  ```javascript
  const { EchoBot } = require('./bot');
  const { startServer } = require('@microsoft/agents-hosting-express')
  startServer(new EchoBot());
  ```

### Design Patterns å kjenne til

1. **State Management Pattern (Verified):**
   ```javascript
   import { AgentApplication, MemoryStorage } from '@microsoft/agents-hosting'

   const agent = new AgentApplication({
       storage: new MemoryStorage()
   })

   agent.onMessage('/count', async (context, state) => {
       const count = state.conversation.count ?? 0
       state.conversation.count = count + 1
       await context.sendActivity(`Count: ${state.conversation.count}`)
   })
   ```

2. **Authentication Pattern (Verified):**
   ```javascript
   import { authorizeJWT, loadAuthConfigFromEnv } from '@microsoft/agents-hosting'

   const authConfig = loadAuthConfigFromEnv()
   server.use(authorizeJWT(authConfig))
   ```

3. **Observability Pattern (Verified):**
   - Bruk `BaggageBuilder` for å tagge spans med tenant/agent/correlation IDs
   - Registrer token cache for observability authentication
   - Logg errors med structured logging (ILogger i .NET)

### Risikofaktorer

| Risiko | Mitigering |
|--------|-----------|
| **Hosting complexity** | Bruk Azure App Service i stedet for IaaS. Vurder Copilot Studio hvis low-code holder. |
| **Ukontrollerte AI-kostnader** | Implementer rate limiting, bruk GPT-4o-mini hvor mulig, monitor med Cost Management. |
| **RAI-brudd** | Implementer Azure AI Content Safety, test systematisk, bruk Responsible AI policies. |
| **Message ordering issues** | Følg streaming best practices (én stream per turn, attach media i stream). |
| **Multi-tenant complexity** | Bruk Entra ID multi-tenant app registration, isoler data per tenant. |

### Quickstart for POC

**Raskeste vei til proof-of-concept:**

1. **Installer Microsoft 365 Agents Toolkit** (VS Code extension)
2. **Opprett nytt prosjekt:**
   - Velg "Echo Agent" template (JavaScript/C#/Python)
3. **Test lokalt:**
   ```bash
   npm install -g @microsoft/teams-app-test-tool
   teamsapptester
   ```
4. **Deploy til Azure:** Bruk Agents Toolkit deployment wizard
5. **Publiser til M365:** Via Teams Admin Center eller M365 Agent Store

**Tidsestimat:** 2-4 timer fra null til fungerende POC.

---

## Kilder og verifisering

### Verified (MCP microsoft-learn)

Følgende informasjon er hentet direkte fra Microsoft Learn dokumentasjon via MCP (2026-02):

- Custom engine agent architecture og key characteristics
- Development approaches: Copilot Studio, M365 Agents SDK, Teams SDK, Foundry
- Agent development tool comparison table
- Scenario examples (legal, healthcare, onboarding)
- Design considerations: streaming behavior, message ordering
- Asynchronous patterns (follow-up, long-running, proactive)
- Code samples: AgentApplication, state management, authentication, observability
- SDK installation og packages
- Microsoft 365 Agents Playground setup

**Primærkilder:**
- https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/overview-custom-engine-agent
- https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/create-deploy-agents-sdk
- https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/agents-overview
- https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/ux-custom-engine-agent
- https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/ (diverse quickstarts og samples)

### Baseline (Modellkunnskap)

Følgende informasjon er basert på generell kunnskap om Microsoft-plattformen (ikke MCP-verifisert):

- Kostnadsestimater for Azure-tjenester i NOK (basert på offentlige Azure pricing, januar 2025)
- TCO-eksempel for 500-bruker scenario
- Offentlig sektor anbefalinger for Norge (data residency, compliance)
- GDPR og Responsible AI vurderinger
- Copilot Studio async limitation (requires verification via testing)

**Merk:** Kostnader kan variere. Verifiser alltid med Azure Pricing Calculator for eksakte estimater.

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