feat(ultraplan-local): v1.6.0 — /ultraresearch-local deep research command

Add /ultraresearch-local for structured research combining local codebase analysis with external knowledge via parallel agent swarms. Produces research briefs with triangulation, confidence ratings, and source quality assessment. New command: /ultraresearch-local with modes --quick, --local, --external, --fg. New agents: research-orchestrator (opus), docs-researcher, community-researcher, security-researcher, contrarian-researcher, gemini-bridge (all sonnet). New template: research-brief-template.md. Integration: --research flag in /ultraplan-local accepts pre-built research briefs (up to 3), enriches the interview and exploration phases. Planning orchestrator cross-references brief findings during synthesis. Design principle: Context Engineering — right information to right agent at right time. Research briefs are structured artifacts in the pipeline: ultraresearch → brief → ultraplan --research → plan → ultraexecute. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-08 08:58:35 +02:00 · 2026-04-08 08:58:35 +02:00 · baa2d0220b
commit baa2d0220b
488 changed files with 213221 additions and 0 deletions
--- a/skills/ms-ai-engineering/references/agent-orchestration/tool-use-and-function-calling-patterns.md
+++ b/skills/ms-ai-engineering/references/agent-orchestration/tool-use-and-function-calling-patterns.md
@ -0,0 +1,431 @@
+# Tool Use and Function Calling - Advanced Patterns
+
+**Last updated:** 2026-02
+**Status:** GA
+**Category:** Agent Orchestration & Automation
+
+---
+
+## Introduksjon
+
+Function calling og tool use er fundamentale mekanismer som lar AI-agenter utvide sine kapabiliteter utover ren språkgenerering. Ved å kalle predefinerte funksjoner kan agenter hente data fra eksterne kilder, utføre beregninger, oppdatere databaser, og samhandle med andre systemer — alt på en kontrollert og sikker måte.
+
+I Microsoft-stakken støttes function calling på tvers av Azure OpenAI, Semantic Kernel, Microsoft Agent Framework, og Foundry Agent Service. Disse plattformene tilbyr ulike grader av abstraksjon, automatisering og enterprise-funksjoner, men deler samme grunnleggende konsept: modellen genererer strukturert JSON som beskriver funksjonsanrop, mens utvikleren kontrollerer når og hvordan funksjonen faktisk kjøres.
+
+Avanserte mønstre for tool use inkluderer parallelle funksjonsanrop, hierarkisk agentkomposisjon (agent-as-tool), dynamisk toolvalg, og human-in-the-loop approval workflows. Disse mønstrene gjør det mulig å bygge robuste, skalerbare og ansvarlige AI-løsninger som balanserer autonomi med kontroll.
+
+---
+
+## Kjernekomponenter
+
+| Komponent | Beskrivelse | Tilgjengelig i |
+|-----------|-------------|----------------|
+| **Function Definition** | JSON Schema som beskriver funksjonsnavn, parametere og beskrivelse | Azure OpenAI, SK, Agent Framework |
+| **Tool Choice** | Kontroll over hvorvidt modellen må, kan eller ikke skal kalle funksjoner (`auto`, `required`, `none`, spesifikk funksjon) | Azure OpenAI API (2023-12-01+) |
+| **Parallel Function Calling** | Modellen kan kalle flere funksjoner samtidig i én respons | GPT-4, GPT-4o, GPT-5-serien, o1/o3-mini |
+| **Automatic Invocation** | Agentframework utfører funksjonskall automatisk uten ekstra kode | Semantic Kernel (FunctionChoiceBehavior.Auto), Agent Framework |
+| **Structured Outputs** | Pydantic-basert skjemavalidering for funksjonsargumenter | Azure OpenAI (gpt-4o 2024-08-06+) |
+| **Agent-as-Tool** | Én agent kan eksponeres som funksjon til en annen agent | Agent Framework (`AsAIFunction()`, `as_tool()`) |
+| **Human-in-the-Loop** | Approval-workflows før funksjoner kjøres | AG-UI middleware, custom logic |
+
+### Eksempel: Enkel funksjonsdefinisjon (Azure OpenAI)
+
+```python
+tools = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_weather",
+            "description": "Get the current weather for a location",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "location": {"type": "string", "description": "City name, e.g. Oslo"},
+                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
+                },
+                "required": ["location"]
+            }
+        }
+    }
+]
+```
+
+### Parallelle funksjonsanrop
+
+```python
+# Én request, flere funksjonsanrop
+messages = [{"role": "user", "content": "What's the weather in Oslo, Paris, and Tokyo?"}]
+response = client.chat.completions.create(model="gpt-4o", messages=messages, tools=tools)
+
+# response.choices[0].message.tool_calls inneholder nå 3 funksjonsanrop
+for tool_call in response.choices[0].message.tool_calls:
+    function_name = tool_call.function.name
+    args = json.loads(tool_call.function.arguments)
+    # Kjør funksjon og legg til resultat i messages
+```
+
+---
+
+## Arkitekturmønstre
+
+### 1. Basic Function Calling (Request-Response)
+
+**Beskrivelse:** Utvikleren definerer funksjoner, sender dem til modellen sammen med brukerforespørselen, og behandler funksjonsanrop manuelt.
+
+**Fordeler:**
+- Full kontroll over eksekveringslogikk
+- Fungerer med alle støttede modeller
+- Enkel feilhåndtering og logging
+
+**Ulemper:**
+- Krever manuell håndtering av funksjonsanrop
+- Må håndtere multi-turn conversations selv
+
+**Bruksområder:** Enkel datainnhenting, prototype-utvikling, tilpasset sikkerhetslogikk.
+
+**Kodeeksempel (Python, Azure OpenAI):**
+
+```python
+import json
+from openai import OpenAI
+
+client = OpenAI(base_url="https://RESOURCE.openai.azure.com/openai/v1/", api_key="KEY")
+
+def get_weather(location: str) -> str:
+    # Simulert funksjon
+    return json.dumps({"location": location, "temperature": "15°C"})
+
+messages = [{"role": "user", "content": "What's the weather in Oslo?"}]
+response = client.chat.completions.create(
+    model="gpt-4o",
+    messages=messages,
+    tools=tools,
+    tool_choice="auto"
+)
+
+# Behandle tool_calls
+if response.choices[0].message.tool_calls:
+    for tool_call in response.choices[0].message.tool_calls:
+        result = get_weather(**json.loads(tool_call.function.arguments))
+        messages.append({
+            "tool_call_id": tool_call.id,
+            "role": "tool",
+            "name": "get_weather",
+            "content": result
+        })
+    # Send tilbake til modellen for final response
+    final = client.chat.completions.create(model="gpt-4o", messages=messages)
+```
+
+---
+
+### 2. Automatic Function Invocation (Semantic Kernel / Agent Framework)
+
+**Beskrivelse:** Agentframeworket håndterer tool calls automatisk. Utvikleren definerer funksjoner med dekoratorer eller plugin-klasser, og agenten kaller dem automatisk når nødvendig.
+
+**Fordeler:**
+- Minimal boilerplate-kode
+- Automatisk retry og feilhåndtering
+- Integrert med Semantic Kernel plugins
+
+**Ulemper:**
+- Mindre kontroll over eksekveringsflyt
+- Krever forståelse av framework-spesifikke konsepter (Kernel, Plugins, FunctionChoiceBehavior)
+
+**Bruksområder:** Multi-turn conversations, komplekse agentic workflows, hurtig prototyping.
+
+**Kodeeksempel (Python, Agent Framework):**
+
+```python
+from agent_framework import ChatAgent, tool
+from agent_framework.azure import AzureChatCompletion
+
+@tool
+def get_weather(location: str) -> str:
+    return f"The weather in {location} is 15°C."
+
+agent = ChatAgent(
+    chat_client=AzureChatCompletion(),
+    instructions="You are a helpful assistant.",
+    tools=[get_weather]
+)
+
+response = await agent.run("What's the weather in Oslo?")
+# get_weather kalles automatisk av agenten
+```
+
+---
+
+### 3. Agent-as-Tool (Hierarchical Agent Composition)
+
+**Beskrivelse:** Én agent eksponeres som en funksjon til en annen agent. Dette skaper hierarkier av spesialiserte agenter.
+
+**Fordeler:**
+- Modulær arkitektur med spesialiserte agenter
+- Enklere testing og vedlikehold
+- Hver agent kan ha egne modeller, instructions og tools
+
+**Ulemper:**
+- Økt kompleksitet i debugging
+- Potensielt høyere token-forbruk
+
+**Bruksområder:** Multi-domain assistenter, delegering til ekspertagenter, composable workflows.
+
+**Kodeeksempel (C#, Agent Framework):**
+
+```csharp
+// Spesialisert agent med egen funksjon
+var weatherAgent = new ChatClientAgent(chatClient, instructions: "You answer weather questions.", tools: [WeatherTool]);
+
+// Hovedagent som bruker weatherAgent som tool
+var mainAgent = new ChatClientAgent(
+    chatClient,
+    instructions: "You are a helpful assistant who responds in Norwegian.",
+    tools: [weatherAgent.AsAIFunction()]
+);
+
+// mainAgent kan nå "kalle" weatherAgent som et verktøy
+var result = await mainAgent.RunAsync("Hvordan er været i Oslo?");
+```
+
+---
+
+### 4. Human-in-the-Loop Approval
+
+**Beskrivelse:** Før funksjonskall utføres, spør systemet bruker om godkjenning. Dette er kritisk for handlinger med reell konsekvens (f.eks. slette data, sende e-post).
+
+**Fordeler:**
+- Økt kontroll og ansvarlig AI
+- Redusert risiko for uønskede handlinger
+- Compliance med AI Act og GDPR (transparens, brukermedvirkning)
+
+**Ulemper:**
+- Krever brukerinteraksjon (ikke fullt automatisert)
+- Kan redusere opplevd "intelligens"
+
+**Bruksområder:** Finansielle transaksjoner, administrative handlinger, dataredigering.
+
+**Implementering (AG-UI + Agent Framework):**
+
+```python
+# AG-UI middleware for approval
+def approval_middleware(tool_call):
+    if tool_call.name in ["delete_record", "send_email"]:
+        user_response = input(f"Approve {tool_call.name}? (yes/no): ")
+        return user_response.lower() == "yes"
+    return True  # Auto-approve andre funksjoner
+
+# Agent med approval-workflow
+agent = ChatAgent(chat_client=client, tools=[delete_record, send_email])
+# Koble approval_middleware til agent runtime
+```
+
+---
+
+## Beslutningsveiledning
+
+### Velg riktig mønster
+
+| Scenario | Anbefalt mønster | Hvorfor |
+|----------|------------------|---------|
+| Enkel datahenting (API-kall, DB-spørring) | Basic Function Calling | Full kontroll, minimal overhead |
+| Multi-turn konversasjon med flere funksjoner | Automatic Invocation (SK/Agent Framework) | Automatisk orkestrering, mindre kode |
+| Spesialiserte subagenter (f.eks. HR-agent, IT-agent) | Agent-as-Tool | Modulær arkitektur, enklere vedlikehold |
+| Kritiske handlinger (slette data, godkjenne betalinger) | Human-in-the-Loop | Compliance, ansvarlig AI |
+| Real-time streaming UI | AG-UI backend tools | SSE-streaming, UX-optimalisert |
+
+### Vanlige feil
+
+| Feil | Konsekvens | Løsning |
+|------|-----------|---------|
+| Manglende eller vag `description` | Modellen kaller feil funksjoner | Inkluder detaljerte beskrivelser med eksempler |
+| Ingen validering av funksjonsargumenter | Runtime errors, sikkerhetshull | Bruk Pydantic-modeller for structured outputs (gpt-4o 2024-08-06+) |
+| For mange funksjoner i én request (>20) | Token-forbruk, dårlig presisjon | Bruk dynamisk toolvalg eller agentkomposisjon |
+| Ikke håndtere parallelle anrop | Race conditions, inkonsistent state | Kjør parallelle kall asynkront, isoler state |
+| Hardkodet tool_choice="required" | Modellen kan ikke gi vanlige svar | Bruk `auto` og la modellen velge |
+
+### Røde flagg
+
+- **Funksjonen har side-effects (sletter data, sender meldinger) uten approval-workflow** → Implementer human-in-the-loop.
+- **Funksjoner kalles fra upålitelig brukerinput uten validering** → Risiko for prompt injection. Valider all input.
+- **Sensitivt data returneres fra funksjoner uten tilgangskontroll** → Bruk least-privilege prinsipper, valider brukeridentitet.
+- **Token-forbruk eksploderer pga. for mange funksjonsdefinisjoner** → Reduser antall tools, bruk agentkomposisjon.
+
+---
+
+## Integrasjon med Microsoft-stakken
+
+| Plattform | Function Calling Support | Auto-invocation | Agent-as-Tool | Parallel Calls | Structured Outputs |
+|-----------|--------------------------|-----------------|---------------|----------------|-------------------|
+| **Azure OpenAI** | ✅ (API 2023-12-01+) | ❌ (manuell) | ❌ | ✅ (gpt-4o+) | ✅ (gpt-4o 2024-08-06+) |
+| **Semantic Kernel** | ✅ (Plugins) | ✅ (FunctionChoiceBehavior.Auto) | ✅ (KernelPlugin) | ✅ | ✅ (Pydantic via SK) |
+| **Agent Framework** | ✅ (ChatAgent, tools=[]) | ✅ (default) | ✅ (AsAIFunction, as_tool) | ✅ | ✅ |
+| **Foundry Agent Service** | ✅ (via OpenAPI endpoints) | ✅ (managed service) | ⚠️ (via tool composition) | ✅ | ✅ |
+| **Copilot Studio** | ✅ (Actions, Plugins) | ✅ (automatic) | ⚠️ (via topic routing) | ⚠️ (begrensninger) | ❌ |
+
+### Eksempel: Semantic Kernel Plugin
+
+```csharp
+public class WeatherPlugin
+{
+    [KernelFunction, Description("Get weather for a location")]
+    public string GetWeather([Description("City name")] string location)
+    {
+        return $"Weather in {location}: 15°C";
+    }
+}
+
+// Legg til plugin i kernel
+kernel.ImportPluginFromType<WeatherPlugin>();
+
+// ChatCompletionAgent med auto-invocation
+var agent = new ChatCompletionAgent
+{
+    Kernel = kernel,
+    Arguments = new KernelArguments(
+        new OpenAIPromptExecutionSettings
+        {
+            FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
+        }
+    )
+};
+```
+
+---
+
+## Offentlig sektor (Norge)
+
+### Compliance-krav
+
+| Regelverk | Krav | Implikasjon for function calling |
+|-----------|------|----------------------------------|
+| **GDPR** | Transparens, data minimization | Logg alle funksjonsanrop som behandler personopplysninger; ikke hent mer data enn nødvendig |
+| **AI Act (EU)** | Risikovurdering for høyrisiko-AI | Funksjoner som påvirker rettigheter krever human oversight (HITL) |
+| **Forvaltningsloven** | Enkeltvedtak må være etterprøvbare | Logg input/output for alle funksjoner som bidrar til beslutninger |
+| **NSM Grunnprinsipper** | Least privilege, logging | Funksjoner skal kun ha tilgang til data/APIer de faktisk trenger |
+| **Schrems II** | Datasuverenitet (EU-EEA) | Funksjoner som kaller eksterne APIer må validere dataplassering |
+
+### Ansvarlig AI-praksis
+
+**Spørsmål arkitekten bør stille:**
+1. Har vi approval-workflow for funksjoner som påvirker brukerrettigheter?
+2. Logger vi alle funksjonsanrop med input/output for revidering?
+3. Har vi validert at funksjoner ikke lekker PII til modellen?
+4. Er funksjoner begrenset til minimum nødvendige privilegier?
+5. Har vi testet for prompt injection-angrep på funksjonsargumenter?
+
+**Eksempel: Logging for etterprøvbarhet**
+
+```python
+import logging
+
+@tool
+def update_citizen_record(ssn: str, field: str, value: str) -> str:
+    # Log før utførelse
+    logging.info(f"Function call: update_citizen_record(ssn={ssn[:4]}****, field={field}, value=REDACTED)")
+
+    # Valider input
+    if not is_valid_ssn(ssn):
+        raise ValueError("Invalid SSN")
+
+    # Utfør handling
+    result = db.update(ssn, field, value)
+
+    # Log resultat
+    logging.info(f"Function result: success={result['success']}")
+    return f"Record updated: {result['success']}"
+```
+
+---
+
+## Kostnad og lisensiering
+
+### Token-forbruk
+
+**Function definitions forbruker input-tokens:**
+- Hver funksjon: ~50-150 tokens (avhengig av kompleksitet)
+- 10 funksjoner: ~500-1500 tokens per request
+- Parallelle anrop: Én request, men flere funksjoner kjøres
+
+**Optimaliseringstips:**
+1. Bruk korte, presise beskrivelser
+2. Reducer antall funksjoner per request (dynamisk toolvalg)
+3. Bruk agent-as-tool for å isolere funksjoner til subagenter
+4. Cache funksjonsresultater når mulig (Azure OpenAI caching)
+
+### Lisenskrav
+
+| Plattform | Funksjonalitet | Lisenskrav |
+|-----------|----------------|------------|
+| **Azure OpenAI** | Function calling | Azure-abonnement + OpenAI deployment |
+| **Semantic Kernel** | Plugins, auto-invocation | Open source (MIT), krever AI-modell |
+| **Agent Framework** | ChatAgent, tools | Open source, krever AI-modell |
+| **Foundry Agent Service** | Managed agents, built-in tools | Azure AI Foundry-lisens |
+| **Copilot Studio** | Actions, Plugins | Power Apps/Power Automate Premium eller Copilot Studio-lisens |
+
+**Kostnadsestimat (NOK, Azure OpenAI gpt-4o):**
+- Input: ~0.25 kr / 1M tokens
+- Output: ~1.00 kr / 1M tokens
+- 100 requests/dag med 10 funksjoner (1000 tokens input): ~250 kr/måned
+- Parallelle anrop reduserer antall requests (besparelse ~30-50%)
+
+---
+
+## For arkitekten (Cosmo)
+
+### Spørsmål å stille klienten
+
+1. **Hvilke handlinger skal agenten kunne utføre?** (Les data, skriv data, kall eksterne APIer, slett?)
+2. **Krever noen funksjoner godkjenning fra bruker?** (Finansielle transaksjoner, sletting, GDPR-påvirkning)
+3. **Hvor mange ulike funksjoner trenger agenten?** (<5: Basic, 5-15: Auto-invocation, 15+: Agent-as-tool)
+4. **Er det spesialiserte domener?** (HR, IT, Finance → vurder agent-as-tool)
+5. **Har dere krav til logging/revidering?** (Forvaltningsloven, ISO 27001)
+6. **Hvilke data skal funksjoner ha tilgang til?** (PII, forretningskritisk → vurder least privilege)
+7. **Skal agenten streame svar i real-time?** (AG-UI backend tools)
+8. **Hva er budsjettet for token-forbruk?** (Vurder PTU for høyt volum)
+
+### Fallgruver
+
+| Fallgruve | Hvorfor det skjer | Hvordan unngå |
+|-----------|-------------------|---------------|
+| **For mange funksjoner i én agent** | Ønsker "alt i ett" | Bruk agent-as-tool, del opp i subagenter |
+| **Funksjoner uten validering** | Stoler på at modellen alltid gir korrekt JSON | Bruk Pydantic structured outputs, valider alle argumenter |
+| **Ingen logging av funksjonsanrop** | Glemmer compliance-krav | Implementer logging fra starten |
+| **Hardkodet tool_choice="required"** | Misforstår at modellen må kalle funksjoner | Bruk `auto`, la modellen velge |
+| **Funksjoner med høy latency blokkerer agent** | Synkrone API-kall | Bruk async/await, AG-UI async tools |
+
+### Anbefalinger per modenhetsnivå
+
+| Modenhetsnivå | Anbefalt tilnærming | Plattform |
+|---------------|---------------------|-----------|
+| **Pilot (PoC)** | Basic function calling, 1-3 funksjoner | Azure OpenAI + Python |
+| **Produksjon (lav kompleksitet)** | Automatic invocation (Agent Framework), <10 funksjoner | Agent Framework + Azure OpenAI |
+| **Produksjon (høy kompleksitet)** | Agent-as-tool, HITL for kritiske funksjoner | Agent Framework + AG-UI |
+| **Enterprise (multi-domain)** | Foundry Agent Service med managed tools | Foundry Agent Service + M365 integrasjon |
+
+---
+
+## Kilder og verifisering
+
+### Microsoft Learn-kilder (Verified via MCP)
+
+1. [Azure OpenAI Function Calling](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/function-calling) — **Verified 2026-02**
+2. [Semantic Kernel Agent Functions](https://learn.microsoft.com/en-us/semantic-kernel/frameworks/agent/agent-functions) — **Verified 2026-02**
+3. [Agent Framework - Agent as Function Tool](https://learn.microsoft.com/en-us/agent-framework/tutorials/agents/agent-as-function-tool) — **Verified 2026-02**
+4. [AG-UI Backend Tool Rendering](https://learn.microsoft.com/en-us/agent-framework/integrations/ag-ui/backend-tool-rendering) — **Verified 2026-02**
+5. [Azure OpenAI Assistants Function Calling](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/assistant-functions) — **Verified 2026-02**
+6. [Structured Outputs](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/structured-outputs) — **Verified 2026-02**
+
+### Konfidensnivå per seksjon
+
+| Seksjon | Konfidens | Kilde |
+|---------|-----------|-------|
+| Kjernekomponenter | **Verified** | Microsoft Learn MCP-search (6 kilder) |
+| Arkitekturmønstre | **Verified** | Azure OpenAI docs, Agent Framework docs |
+| Integrasjon med Microsoft-stakken | **Verified** | Semantic Kernel docs, Foundry docs |
+| Offentlig sektor | **Baseline** | Modellkunnskap + norsk lovverk (GDPR, Forvaltningsloven) |
+| Kostnad og lisensiering | **Baseline** | Azure pricing (2026-02), modellkunnskap |
+
+---
+
+**For Cosmo:** Dette dokumentet dekker både grunnleggende og avanserte mønstre for function calling. Bruk det til å velge riktig tilnærming basert på klientens behov (antall funksjoner, kompleksitet, compliance-krav). Husk alltid: **Start enkelt (Basic), skalér til Auto-invocation, og bygg modulært med Agent-as-Tool når kompleksiteten vokser.**