ms-ai-architect/skills/ms-ai-advisor/references/development/agent-framework.md

# Microsoft Agent Framework - Knowledge Base

**Last updated:** 2026-06-24
**Status:** Generelt tilgjengelig (kjerne-SDK). Multi-agent workflows/orkestrering er under aktiv utvikling — deler er i preview/experimental.
**Category:** Microsoft AI Platforms

> **Verifisert 2026-06-24 mot Microsoft Learn (`learn.microsoft.com/agent-framework/`).** Hele API-flaten er korrigert: tidligere utgaver av denne filen brukte oppdiktede imports (`azure.ai.agent`, `azure.ai.foundry.FoundryClient/FoundryTools`, `Swarm`/`Handoff`, `Memory`, `@checkpoint`, `enable_tracing`). Det korrekte SDK-et er pakken `agent-framework` (Python) / `Microsoft.Agents.AI` (.NET).

---

## Hva er Microsoft Agent Framework?

Microsoft Agent Framework (MAF) er Microsofts åpne SDK for å bygge AI-agenter i kode. Det er den **direkte etterfølgeren til BÅDE Semantic Kernel OG AutoGen** — laget av de samme teamene. MAF kombinerer AutoGens enkle agent-abstraksjoner (single- og multi-agent) med Semantic Kernels enterprise-funksjoner (session-basert state, type-sikkerhet, middleware/filtre, telemetri, bred modell-/embedding-støtte), og legger til **graf-baserte Workflows** for eksplisitt kontroll over multi-agent-eksekvering.

**Nøkkelegenskaper:**
- Enhetlig agent-abstraksjon (`Agent` / `ChatClientAgent`) på tvers av modell-leverandører
- Tool/function calling med automatisk skjema-generering
- Session-basert samtalehistorikk (stateless agent som default)
- Streaming og async
- Graf-baserte Workflows for multi-agent-orkestrering
- Innebygd OpenTelemetry-observability
- Native Microsoft Foundry-integrasjon

**Språk:** Python (`agent-framework`), .NET/C# (`Microsoft.Agents.AI`). En .NET-pakke bygger på `Microsoft.Extensions.AI` for kjerne-meldings- og innholdstyper.

**Installasjon (Python):**

```bash
pip install agent-framework
```

Meta-pakken installerer kjernen (`agent-framework-core`) pluss de vanligste leverandørpakkene. Når du vet hva du trenger, kan du installere kun delene du bruker, f.eks. `pip install agent-framework-foundry agent-framework-mem0` (kjernen er en avhengighet og følger med). Andre provider-pakker: `agent-framework-openai`, `agent-framework-copilotstudio`.

---

## Forhold til Semantic Kernel og AutoGen

MAF er ikke et namespace inni Semantic Kernel — det er et eget SDK som erstatter begge forløperne. **Det finnes ikke noe `Kernel`-objekt** i Agent Framework.

| Aspekt | Semantic Kernel | AutoGen | Microsoft Agent Framework |
|--------|-----------------|---------|---------------------------|
| **Rolle** | Forløper (vedlikeholdes) | Forløper (vedlikeholdes) | Direkte etterfølger til begge |
| **Kjerneobjekt** | `Kernel` + `ChatCompletionAgent` | `AssistantAgent` | `Agent` / `ChatClientAgent` (ingen `Kernel`) |
| **Multi-agent** | Orchestration (preview) | GroupChat / Magentic | Graf-baserte Workflows + orkestrering |
| **State** | `ChatHistoryAgentThread` | Innebygd i agent | `AgentSession`/thread (stateless default) |
| **Verktøy** | `@kernel_function` + plugin + Kernel | `FunctionTool` | `@tool` / vanlig funksjon, registreres direkte |

**Anbefaling:** Bruk Microsoft Agent Framework for nye prosjekter. Eksisterende Semantic Kernel-kode kan migreres gradvis — og `KernelFunction`-instanser kan gjenbrukes direkte som MAF-verktøy via `.as_agent_framework_tool` (krever `semantic-kernel` ≥ 1.38), se [Migrasjon fra Semantic Kernel](#migrasjon-fra-semantic-kernel).

Offisielle migrasjonsguider: [fra Semantic Kernel](https://learn.microsoft.com/agent-framework/migration-guide/from-semantic-kernel/) · [fra AutoGen](https://learn.microsoft.com/agent-framework/migration-guide/from-autogen/).

---

## Kjernekomponenter

### Agent

En agent settes sammen av tre kjerneelementer: en **client** (modell-backend), **instructions** (systemprompt) og **tools** (kapabiliteter utover tekstgenerering). Agenten opprettes direkte med klienten:

```python
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(
        project_endpoint="https://<project>.services.ai.azure.com",
        model="gpt-4o",
        credential=AzureCliCredential(),
    ),
    name="ResearchAgent",
    instructions="Du er en forskningsassistent som finner fakta.",
    tools=[search_web, read_file],
)

response = await agent.run("Finn de nyeste tallene for norsk kraftproduksjon.")
print(response.text)
```

Du kan også bruke klientens convenience-metode `as_agent()` (kaller `Agent(...)` internt med et subsett av parametre):

```python
agent = FoundryChatClient(
    project_endpoint="https://<project>.services.ai.azure.com",
    model="gpt-4o",
    credential=AzureCliCredential(),
).as_agent(instructions="Du er en hjelpsom assistent.")
```

Samme mønster fungerer mot andre backends — f.eks. `from agent_framework.openai import OpenAIChatClient` for Azure OpenAI / OpenAI.

### Tools

Et verktøy er bare en Python-funksjon. Funksjonsnavnet blir verktøynavnet og docstring-en blir beskrivelsen. Du registrerer det direkte i `tools`-parameteren — det finnes ingen plugin-/Kernel-innpakning:

```python
from typing import Annotated
from agent_framework import tool

@tool
def search_web(
    query: Annotated[str, "Søketekst"]
) -> str:
    """Søk på nettet etter informasjon."""
    # Implementasjon
    return results

# Dekoratøren er valgfri — en ren funksjon med docstring fungerer også:
def read_file(path: Annotated[str, "Sti til filen"]) -> str:
    """Les innholdet i en fil."""
    return content
```

`@tool` brukes når du vil overstyre navn/beskrivelse eller sette egenskaper som godkjenningskrav (se [Human-in-the-Loop](#pattern-3-human-in-the-loop)). `tools`-parameteren finnes både ved agent-opprettelse og på `run()`.

### Memory / samtalehistorikk

En agent er **stateless som default** — hvert `agent.run(...)`-kall starter uten historikk. For flertur-samtaler ber du agenten lage en tråd og gjenbruker den:

```python
agent = Agent(client=client, instructions="...")

thread = agent.get_new_thread()

await agent.run("Mitt navn er Kari.", thread)
response = await agent.run("Hva heter jeg?", thread)  # husker konteksten
print(response.text)
```

Tråden lagres in-memory som default. For leverandører med tjenestesidig tråd (f.eks. Foundry Agents) holdes historikken på tjenestesiden. For persistent eller eksternt minne brukes provider-pakker som `agent-framework-mem0`, eller du dytter trådhistorikken inn i Redis / Cosmos DB i produksjon.

### Multi-Agent Orchestration (Workflows)

MAF orkestrerer flere agenter via **graf-baserte Workflows**. Du bygger grafen med `WorkflowBuilder` (eksplisitte noder/kanter) eller med høynivå-byggere som `SequentialBuilder`:

```python
from agent_framework import WorkflowBuilder

researcher = client.as_agent(name="Researcher", instructions="Finn fakta...")
writer = client.as_agent(name="Writer", instructions="Skriv innhold...")

# Eksplisitt graf: output flyter fra researcher til writer
workflow = (
    WorkflowBuilder(start_executor=researcher)
    .add_edge(researcher, writer)
    .build()
)

events = await workflow.run("Skriv en rapport om AI-trender")
outputs = events.get_outputs()
if outputs:
    print(outputs[0].text)
```

For en rein pipeline finnes `SequentialBuilder`, som også kan begrense hva hver agent ser av historikken (`chain_only_agent_responses=True`):

```python
from agent_framework.orchestrations import SequentialBuilder

workflow = SequentialBuilder(
    participants=[writer, translator, reviewer],
    chain_only_agent_responses=True,
).build()
```

Andre innebygde orkestreringsmønstre: **concurrent** (parallell), **handoff** (agenter overfører full kontroll seg imellom) og **Magentic** (manager-ledet, etterfølger til AutoGens MagenticOneGroupChat). Se [Workflows-dokumentasjonen](https://learn.microsoft.com/agent-framework/workflows/).

---

## Microsoft Foundry-integrasjon

MAF er native integrert med **Microsoft Foundry Agent Service**. `FoundryChatClient` peker mot et Foundry-prosjekt og lar agenten bruke prosjektets modeller og verktøy:

```python
import os
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

agent = Agent(
    client=FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["FOUNDRY_MODEL"],
        credential=AzureCliCredential(),
    ),
    instructions="Du er en hjelpsom assistent.",
)
```

Foundry Agent Service kan **hoste** agenter på tjenestesiden (persistente agenter med tjenestesidig tråd) — i motsetning til lokalt kjørte agenter. Hosting, skalering og livssyklus styres av Foundry Agent Service, ikke av en klientside-`deploy()`-metode.

### Foundry-verktøykatalog

Foundry Agent Service tilbyr en katalog av innebygde verktøy som kan kobles på agenten i prosjektet:

| Kategori | Verktøy |
|----------|---------|
| **Kunnskap (privat)** | Azure AI Search, File Search, SharePoint, Microsoft Fabric (Fabric Data Agent) |
| **Kunnskap (web)** | Grounding with Bing Search, Web Search |
| **Handling/automatisering** | Azure Logic Apps, Azure Functions, OpenAPI, MCP, Computer Use, Browser Automation |
| **Generering/kjøring** | Code Interpreter, Image Generation |
| **Agent-til-agent** | Agent2Agent (A2A) |

Verktøystøtte varierer per modell og region — se den autoritative matrisen i [Tool best practices for Foundry Agent Service](https://learn.microsoft.com/azure/foundry/agents/concepts/tool-best-practice). **Azure Logic Apps-verktøyet** gir agenten tilgang til Logic Apps' connector-økosystem (SharePoint, e-post, linjeforretningssystemer m.m.).

---

## Patterns

### Pattern 1: RAG Agent

```python
from typing import Annotated
from agent_framework import Agent, tool
from azure.search.documents import SearchClient

search_client = SearchClient(...)

@tool
def search_documents(
    query: Annotated[str, "Søketekst mot kunnskapsbasen"]
) -> str:
    """Søk i kunnskapsbasen og returner relevante utdrag."""
    results = search_client.search(query, top=5)
    return "\n".join(r["content"] for r in results)

rag_agent = Agent(
    client=client,
    name="KnowledgeAgent",
    instructions=(
        "Du er en kunnskapsassistent. Bruk search_documents for å finne "
        "relevant informasjon før du svarer. Siter alltid kilder."
    ),
    tools=[search_documents],
)
```

> For Foundry-hostede agenter kan du i stedet bruke det innebygde **Azure AI Search**-verktøyet fra verktøykatalogen i stedet for et egendefinert tool.

### Pattern 2: Supervisor-Worker (orkestrering)

Bygg spesialiserte agenter og koordiner dem i en workflow:

```python
from agent_framework import WorkflowBuilder

researcher = client.as_agent(name="Researcher", instructions="Finn fakta...")
writer = client.as_agent(name="Writer", instructions="Skriv innhold...")
reviewer = client.as_agent(name="Reviewer", instructions="Kvalitetssjekk...")

workflow = (
    WorkflowBuilder(start_executor=researcher)
    .add_edge(researcher, writer)
    .add_edge(writer, reviewer)
    .build()
)

events = await workflow.run("Lag et faktanotat om AI Act for offentlig sektor.")
```

For en manager-ledet variant (en koordinator som dynamisk velger neste agent) brukes **Magentic**-orkestrering.

### Pattern 3: Human-in-the-Loop (tool-godkjenning)

Marker verktøy som krever menneskelig godkjenning med `approval_mode`. Når agenten forsøker å kalle verktøyet, pauser workflowen og emitter en `request_info`-hendelse du håndterer eksternt:

```python
from agent_framework import tool, Agent
from agent_framework.orchestrations import SequentialBuilder

@tool(approval_mode="always_require")
def execute_database_query(query: str) -> str:
    """Kjør en database-spørring (krever godkjenning)."""
    return f"Spørring utført: {query}"

database_agent = Agent(
    client=client,
    name="DatabaseAgent",
    instructions="Du er en database-assistent.",
    tools=[execute_database_query],
)

workflow = SequentialBuilder(participants=[database_agent]).build()
# Workflowen pauser på request_info-hendelsen og venter på godkjenning.
```

### Pattern 4: Streaming Response

```python
agent = Agent(client=client, instructions="...")

# Streaming for responsivt UI
async for update in agent.run("Forklar kvantefysikk", stream=True):
    if update.text:
        print(update.text, end="", flush=True)
```

---

## Observability

MAF integrerer med **OpenTelemetry** og emitterer traces, logs og metrics etter [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). `opentelemetry-api`/`-sdk` følger med; **exportere installeres separat** (for å unngå unødvendige avhengigheter).

### Foundry + Azure Monitor

For Foundry-prosjekter konfigureres observability direkte fra `FoundryChatClient`:

```bash
pip install azure-monitor-opentelemetry
```

```python
# Krever at Foundry-prosjektet er koblet til en Application Insights-ressurs
client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["FOUNDRY_MODEL"],
    credential=AzureCliCredential(),
)
client.configure_azure_monitor()  # setter connection string + resource automatisk
```

Traces vises i Foundry-portalen under **Observability → Traces** (typisk 2–5 min etterslep), og i den koblede Application Insights-ressursen.

### Lokal utvikling (Aspire Dashboard)

For lokal utvikling uten Azure kan du sende telemetri til [Aspire Dashboard](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/standalone) via OTLP:

```bash
export ENABLE_INSTRUMENTATION=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
```

For andre backends (Jaeger, Zipkin, Datadog, Grafana, New Relic) installeres en OTLP-exporter, f.eks. `opentelemetry-exporter-otlp-proto-grpc`.

---

## Security

### Managed Identity

```python
from azure.identity import DefaultAzureCredential

client = FoundryChatClient(
    project_endpoint="https://<project>.services.ai.azure.com",
    model="gpt-4o",
    credential=DefaultAzureCredential(),  # ingen secrets i koden
)
```

> `DefaultAzureCredential` er praktisk i utvikling, men i produksjon bør du bruke en spesifikk credential (f.eks. `ManagedIdentityCredential`) for å unngå latens, utilsiktet credential-probing og sikkerhetsrisiko fra fallback-kjeden. (Microsofts egen anbefaling i migrasjonsguiden.)

### Content Safety

Innholdsfiltrering kan gjøres via Azure AI Content Safety (eget SDK) eller via Foundry-prosjektets innebygde guardrails:

```python
from azure.ai.contentsafety import ContentSafetyClient
from azure.ai.contentsafety.models import AnalyzeTextOptions

safety = ContentSafetyClient(endpoint, credential)

@tool
def safe_generate(prompt: Annotated[str, "Brukerprompt"]) -> str:
    """Generer svar med innholdssjekk på input og output."""
    result = safety.analyze_text(AnalyzeTextOptions(text=prompt))
    if any(c.severity > 2 for c in result.categories_analysis):
        raise ValueError("Skadelig input oppdaget")
    # ... generer og sjekk output tilsvarende
    return response
```

### Tool-godkjenning (scoping)

Sensitive verktøy markeres med godkjenningskrav i stedet for å kjøres automatisk:

```python
@tool(approval_mode="always_require")
def read_sensitive_file(path: str) -> str:
    """Les en sensitiv fil — krever menneskelig godkjenning før kjøring."""
    ...
```

---

## Migrasjon fra Semantic Kernel

De viktigste endringene fra Semantic Kernel til Agent Framework (Python). Merk: **ingen `Kernel`** lenger.

### Pakke og import

```python
# Semantic Kernel
from semantic_kernel import Kernel
from semantic_kernel.agents import ChatCompletionAgent

# Agent Framework
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
```

### Agent-opprettelse (Kernel → client)

```python
# Semantic Kernel — hver agent avhenger av et Kernel
agent = ChatCompletionAgent(
    service=OpenAIChatCompletion(),
    name="Support",
    instructions="Svar i én setning.",
)

# Agent Framework — ingen Kernel; klienten gis direkte
agent = Agent(
    client=FoundryChatClient(credential=AzureCliCredential()),
    instructions="Svar i én setning.",
)
```

### Plugins → Tools

```python
# Semantic Kernel — @kernel_function + plugin-klasse + Kernel
from semantic_kernel.functions import kernel_function

class SpecialsPlugin:
    @kernel_function(name="specials", description="List dagens retter")
    def specials(self) -> str:
        return "Fiskesuppe, Cæsarsalat"

# Agent Framework — funksjon registreres direkte
from agent_framework import tool

@tool(name="specials", description="List dagens retter")
def specials() -> str:
    return "Fiskesuppe, Cæsarsalat"

agent = client.as_agent(instructions="...", tools=[specials])
```

### Invocation (`invoke` → `run`)

```python
# Semantic Kernel — async-iterator
async for response in agent.invoke(messages=user_input, thread=thread):
    print(response)

# Agent Framework — ett AgentResponse
response = await agent.run(user_input, thread)
print(response.text)
```

### Kompatibilitet: gjenbruk `KernelFunction` som MAF-verktøy

Eksisterende `KernelFunction`-instanser (fra prompt-maler eller metoder, inkl. VectorStore `create_search_function`) kan konverteres til Agent Framework-verktøy med `.as_agent_framework_tool` — en gradvis migrasjonsbro:

```python
# Krever semantic-kernel >= 1.38
agent_tool = kernel_function.as_agent_framework_tool(kernel=kernel)
agent = OpenAIChatClient(model="gpt-4o").as_agent(tools=agent_tool)
```

### .NET-ekvivalent

```csharp
using Microsoft.Extensions.AI;
using Microsoft.Agents.AI;

// Ingen Kernel — base-typen er AIAgent, konsolidert i ChatClientAgent
AIAgent agent = chatClient.AsAIAgent(
    instructions: "Svar i én setning.",
    tools: [AIFunctionFactory.Create(GetWeather)]);

AgentResponse response = await agent.RunAsync(userInput, session);
Console.WriteLine(response.Text);
```

---

## Beslutningsveiledning

### Når anbefale Agent Framework

1. **Utviklerteam** som bygger AI-applikasjoner i kode (Python/.NET)
2. **Multi-agent systemer** med kompleks orkestrering (Workflows)
3. **Tight Azure-integrasjon** via Foundry Agent Service
4. **Custom logic** som krever kode
5. **Produksjonskrav** (observability, sessions, sikkerhet, type-sikkerhet)

### Når anbefale Copilot Studio i stedet

1. **Citizen developers** uten kodeerfaring
2. **Rask prototyping** av chatbots
3. **Standard scenarioer** (Q&A, IT-helpdesk)
4. **Power Platform-økosystem** allerede i bruk

### Når anbefale direkte Azure OpenAI i stedet

1. **Enkle API-kall** uten orkestrering
2. **Minimal kompleksitet** påkrevd
3. **Eksisterende SDK-integrasjon** (OpenAI SDK)

### Spørsmål å stille kunden

1. "Har dere utviklere som kan skrive Python eller C#?"
2. "Trenger dere at flere agenter samarbeider?"
3. "Hvilke systemer må agenten integrere med?"
4. "Hva er kravene til observability og logging?"
5. "Skal løsningen kjøre i Azure, on-prem, eller hybrid?"

> **Eksisterende Semantic Kernel- eller AutoGen-kode?** MAF er den offisielle etterfølgeren til begge. Migrasjon kan skje gradvis — SK-`KernelFunction`-er kan gjenbrukes direkte via `.as_agent_framework_tool`.

---

## Ressurser

- [Agent Framework — oversikt](https://learn.microsoft.com/agent-framework/overview/)
- [Kom i gang: din første agent](https://learn.microsoft.com/agent-framework/get-started/your-first-agent)
- [Workflows (multi-agent-orkestrering)](https://learn.microsoft.com/agent-framework/workflows/)
- [Observability](https://learn.microsoft.com/agent-framework/agents/observability)
- [Migrasjonsguide fra Semantic Kernel](https://learn.microsoft.com/agent-framework/migration-guide/from-semantic-kernel/)
- [Migrasjonsguide fra AutoGen](https://learn.microsoft.com/agent-framework/migration-guide/from-autogen/)
- [Microsoft Foundry Agent Service](https://learn.microsoft.com/azure/foundry/agents/overview)
- [GitHub: microsoft/agent-framework](https://github.com/microsoft/agent-framework)

---

*Sist oppdatert: Juni 2026 (API re-verifisert mot Microsoft Learn 2026-06-24)*