ms-ai-architect/skills/ms-ai-advisor/references/prompt-engineering/function-calling-and-tool-use.md

# Function Calling and Tool Use Patterns

**Last updated:** 2026-06-24
**Status:** GA
**Category:** Prompt Engineering & LLM Optimization

---

## Introduksjon

Function calling er en nøkkelfunksjonalitet i Azure OpenAI som gjør det mulig for språkmodeller å samhandle med eksterne systemer, API-er og databaser på en strukturert måte. I stedet for at modellen forsøker å "gjette" hvordan den skal kalle en funksjon, definerer du funksjonsskjemaer i JSON, og modellen returnerer strukturerte kall med argumenter som din applikasjon kan validere og utføre.

Dette skaper en klar separasjon mellom modellens intelligens og faktiske systemhandlinger — modellen bestemmer *hva* som skal gjøres og med *hvilke argumenter*, mens din kode utfører kallet og kontrollerer tilgangen. Function calling er kritisk for å bygge pålitelige AI-agenter, chatboter med eksterne integrasjoner, og workflow automation i virksomhetssystemer.

Fra API version `2023-12-01-preview` har Microsoft erstattet de utdaterte `functions` og `function_call` parameterne med `tools` og `tool_choice` for bedre fleksibilitet og støtte for parallelle funksjonskall. Moderne GPT-4o og GPT-4.1-modeller støtter parallell function calling, som reduserer antall API-kall og latency betydelig.

## Kjernekomponenter

| Komponent | Beskrivelse | Eksempel |
|-----------|-------------|----------|
| **tools** | Array av funksjonsskjemaer (JSON Schema format) | `[{"type": "function", "function": {...}}]` |
| **tool_choice** | Styrer modellens valg: `"auto"`, `"none"`, eller spesifikt funksjonsnavn | `"auto"` (standard) eller `{"type": "function", "function": {"name": "get_weather"}}` |
| **tool_calls** | Array av funksjonskall i modellens respons | `[{"id": "call_abc", "type": "function", "function": {"name": "get_weather", "arguments": "{...}"}}]` |
| **tool_call_id** | Unik ID for å matche funksjonsresultat med opprinnelig kall | `"call_abc"` |
| **function.parameters** | JSON Schema som definerer parameterstruktur (type, properties, required) | `{"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}` |

### Typisk request-struktur

```python
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "Get the current weather in a given location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city name, e.g. San Francisco"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"]
                    }
                },
                "required": ["location"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What's the weather in Oslo?"}],
    tools=tools,
    tool_choice="auto"
)
```

### Response-struktur

```json
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": {
          "name": "get_current_weather",
          "arguments": "{\"location\": \"Oslo\", \"unit\": \"celsius\"}"
        }
      }]
    }
  }]
}
```

### Three-step pattern

1. **Send initial request** — inkluder `tools` og brukerens spørsmål
2. **Execute function calls** — parse `tool_calls`, valider argumenter, kjør funksjonene
3. **Send results back** — legg til funksjonsresultater som nye meldinger med `role: "tool"` og `tool_call_id`

## Arkitekturmønstre

### 1. Single Function Call (enkel interaksjon)

**Bruk når:** Ett enkelt API-kall gir svaret (f.eks. "Hva er været i Bergen?")

**Fordeler:**
- Enkel feilhåndtering
- Lav latency (2 API-kall totalt)
- Lett å debugge

**Ulemper:**
- Støtter ikke komplekse multi-step workflows
- Ineffektivt hvis flere datapunkter trengs

**Eksempel:**
```python
# Request 1: User asks for weather
messages = [{"role": "user", "content": "What's the weather in Bergen?"}]
response = client.chat.completions.create(model="gpt-4o", messages=messages, tools=tools)

# Model responds with tool_call
tool_call = response.choices[0].message.tool_calls[0]
weather_data = get_weather(json.loads(tool_call.function.arguments)["location"])

# Request 2: Send result back
messages.append(response.choices[0].message)
messages.append({"role": "tool", "tool_call_id": tool_call.id, "content": weather_data})
final_response = client.chat.completions.create(model="gpt-4o", messages=messages)
```

### 2. Parallel Function Calling (effektiv batch-operasjon)

**Bruk når:** Flere uavhengige datapunkter trengs samtidig (f.eks. "Sammenlign været i Oslo, Bergen og Trondheim")

**Fordeler:**
- Reduserer antall API-kall (fra 2N+1 til 3 requests for N funksjoner)
- Lavere total latency
- Bedre brukeropplevelse (raskere svar)

**Ulemper:**
- Krever modeller med parallell support (GPT-4o, GPT-4.1+)
- Mer kompleks feilhåndtering (noen kall kan feile)
- Høyere token-forbruk per request

**Støttede modeller:**
- GPT-4o (`2024-05-13`, `2024-08-06`, `2024-11-20`)
- GPT-4.1 (`2025-04-14`)
- GPT-4.1-mini (`2025-04-14`)
- O3-mini (`2025-01-31`) — nå med `tool_choice` support

**Eksempel:**
```python
# Model returns multiple tool_calls in one response
tool_calls = response.choices[0].message.tool_calls  # 3 calls for Oslo, Bergen, Trondheim

# Execute all in parallel (or sequentially)
for tool_call in tool_calls:
    args = json.loads(tool_call.function.arguments)
    result = get_weather(args["location"])
    messages.append({
        "role": "tool",
        "tool_call_id": tool_call.id,
        "name": tool_call.function.name,
        "content": result
    })

# Single final request with all results
final_response = client.chat.completions.create(model="gpt-4o", messages=messages)
```

### 3. Multi-turn Function Loop (agentic workflow)

**Bruk når:** Oppgaven krever flere steg der hvert steg avhenger av forrige (f.eks. "Finn værdata, beregn snitt, lagre i database")

**Fordeler:**
- Støtter komplekse workflows
- Modellen kan "resonnere" mellom steg
- Håndterer usikkerhet (modellen kan be om mer info)

**Ulemper:**
- Høyere token-kostnad (mange meldinger i context)
- Høyere latency (flere round-trips)
- Risiko for loops hvis modellen ikke konvergerer

**Implementasjonsmønster:**
```python
max_iterations = 10
iteration = 0

while iteration < max_iterations:
    response = client.chat.completions.create(model="gpt-4o", messages=messages, tools=tools)
    message = response.choices[0].message

    if not message.tool_calls:
        # Model responded with final answer
        return message.content

    # Execute tool calls
    messages.append(message)
    for tool_call in message.tool_calls:
        result = execute_function(tool_call.function.name, tool_call.function.arguments)
        messages.append({"role": "tool", "tool_call_id": tool_call.id, "content": result})

    iteration += 1

raise Exception("Max iterations reached without final answer")
```

## Beslutningsveiledning

### Når bruke function calling vs. andre metoder

| Scenario | Anbefaling | Begrunnelse |
|----------|-----------|-------------|
| Strukturert data extraction | Function calling | JSON Schema validation sikrer konsistente outputs |
| Sanntids-data (vær, aksjekurser) | Function calling | Modellen har ikke oppdatert info, må hente eksternt |
| Database queries | Function calling | Sikker tilgangskontroll, validering av parametere |
| Enkel Q&A uten external data | Ingen tools | Unødvendig kompleksitet og kostnad |
| Retrieval-Augmented Generation (RAG) | Kombiner med RAG | Function calling kan hente data, RAG gir context |
| Long-running tasks (batch processing) | Async patterns eller Agents API | Chat Completions er ikke designet for lang ventetid |

### Tool_choice strategier

| Verdi | Oppførsel | Bruk når |
|-------|----------|----------|
| `"auto"` | Modellen velger selv om den kaller funksjoner | Standard, anbefales for de fleste use cases |
| `"none"` | Tvinger modellen til å svare uten funksjonskall | Du vil ha direkte svar eller modellen kaller feil funksjoner |
| `{"type": "function", "function": {"name": "X"}}` | Tvinger kall til spesifikk funksjon | Du vet nøyaktig hvilken funksjon som trengs (f.eks. "Lagre data" etter en samtale) |

### Vanlige feil

| Feil | Symptom | Løsning |
|------|---------|---------|
| Modellen kaller funksjoner som ikke eksisterer | `tool_calls` inneholder ukjente funksjonsnavn | Legg til i system message: "Only use the functions you have been provided with." |
| Ugyldig JSON i `arguments` | JSON parsing feiler | Legg til error handling, be modellen prøve igjen med korrekt format |
| Modellen antar parameterverdier | Feil data sendes til funksjoner | System message: "Don't make assumptions about what values to use with functions. Ask for clarification if a user request is ambiguous." |
| Token limit overskredet | API returnerer feil | Reduser antall funksjoner eller forkort descriptions |
| Modellen kaller ikke funksjoner når den burde | Returnerer "I don't have access to..." | Forbedre function `description`, vurder prompt engineering eller finetuning |

### Røde flagg (sikkerhet)

- **Manglende validering:** Aldri send `arguments` direkte til funksjoner uten validering
- **Over-privileged functions:** En function calling-basert chatbot skal ikke ha skrivetilgang til produksjonsdatabaser
- **Untrusted function outputs:** Funksjonsresultater kan brukes til prompt injection hvis ikke sanitized
- **Manglende rate limiting:** En løkke-bug kan generere tusenvis av API-kall
- **Ingen user confirmation:** High-impact actions (sletting, betaling) skal kreve menneske-godkjenning

## Integrasjon med Microsoft-stakken

### Microsoft Foundry

Function calling integreres sømløst med:
- **Azure AI Search:** Bruk function calling til å bygge queries basert på brukerintent
- **Prompt Flow:** Orkestrere function calls som del av større workflows
- **Semantic Kernel:** Auto-genererer `tools` parameter fra C#/Python function decorators

### Azure OpenAI Assistants API

Assistants API støtter function calling som en native tool type:
```python
assistant = client.beta.assistants.create(
    name="Weather Assistant",
    instructions="You help users check weather.",
    model="gpt-4o",
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather for a location",
            "parameters": {...}
        }
    }]
)
```

**Viktig forskjell:** I Assistants API håndterer systemet tool execution loop automatisk. Du må submitte tool outputs via `runs.submit_tool_outputs()` innen 10 minutter.

### Power Platform & Copilot Studio

**Copilot Studio:** Kan eksponere Power Automate flows som "Actions" (bygget på function calling under panseret)

**Power Automate:** Trigger flows fra function calls ved å kalle HTTP endpoints med `arguments` som payload

### Azure Logic Apps

[Azure Logic Apps kan integreres](https://learn.microsoft.com/en-us/azure/foundry-classic/openai/how-to/assistants-logic-apps) med Assistants API for å håndtere function execution.

### On Your Data (Azure AI Search + OpenAI)

**Viktig begrensning:** `tools` og `data_sources` kan ikke brukes sammen i samme request med `tool_choice: auto`. Microsoft anbefaler:
- Hvis `tool_choice: "none"` — kun data sources brukes
- Hvis `tool_choice: "auto"` eller spesifikt funksjonsnavn — data sources ignoreres

For kombinert bruk, bruk **Prompt Flow** eller **Semantic Kernel** til orkestrering.

## Offentlig sektor (Norge)

### GDPR og datasuverenitet

| Aspekt | Relevans for function calling | Anbefaling |
|--------|-------------------------------|------------|
| **Personopplysninger i function arguments** | `arguments` sendes til Azure OpenAI og logges | Anonymiser eller pseudonymiser før sending, bruk `data_residency` settings |
| **Function outputs med sensitive data** | Returneres til modellen og kan påvirke fremtidige svar | Valider at outputs ikke inneholder PII før de sendes tilbake |
| **Logging og audit** | Function calls må spores for compliance | Implementer audit logging av alle `tool_calls` og `tool_call_id` |
| **Databehandleravtale** | Microsoft er databehandler for Azure OpenAI | Sikre at function calls dekkes av DPA |

### Schrems II (data transfers)

**Standard deployment (US/EU West):** Function arguments sendes til OpenAI-infrastruktur som kan involvere USA.

**EU Data Boundary:** Velg EU-regioner (West Europe, North Europe) for deployment, men vær obs på at OpenAI-modellene kjører i Microsoft-kontrollerte datasentre.

**Anbefaling:** For høy-sensitiv data, vurder:
- Azure OpenAI i norske datasentre (Norway East/West) når tilgjengelig
- Self-hosted models (Phi-3, Llama) med function calling via ONNX Runtime

### AI Act (EU)

| Risikoklasse | Eksempel use case | Krav til function calling |
|--------------|-------------------|---------------------------|
| **Høyrisiko** | Automatisk saksbehandling, scoring av borgere | Full audit trail, human-in-the-loop før funksjoner utføres, eksplanerbarhet |
| **Begrenset risiko** | Chatbot for publikumsinformasjon | Transparent om at det er AI, warnings ved høy-impact actions |
| **Minimal risiko** | Intern værdata-agent | Ingen spesielle krav |

### Forvaltningsloven

**§ 11b (automatiserte avgjørelser):** Hvis function calling brukes til å fatte vedtak, må det være mulig å:
1. Forstå hvorfor modellen valgte å kalle funksjonen
2. Overstyre beslutningen manuelt
3. Kreve manuell saksbehandling

**Anbefaling:** Implementer "explain" function som logger modellens reasoning før eksekveringen.

## Kostnad og lisensiering

### Prismodell

Function calling påvirker kostnaden på flere måter:

| Kostnadsfaktor | Beskrivelse | Estimat |
|----------------|-------------|---------|
| **Function definitions i system message** | Tools-array injiseres i system message, teller som input tokens | 100-500 tokens per funksjon (avhenger av description lengde) |
| **Arguments i tool_calls** | Output tokens øker | 20-100 tokens per funksjonskall |
| **Tool results i conversation** | Funksjonsresultater legges til som nye messages | Varierer (JSON data kan være stort) |
| **Multi-turn loops** | Flere round-trips = flere requests | 3-10x kostnad vs. enkel completion |

### Eksempel kostnadsberegning (GPT-4o standard pricing)

**Scenario:** Væragent med 3 funksjoner, parallelt kall til 3 byer

1. **Request 1:**
   - Input: 500 tokens (system + tools + user message)
   - Output: 150 tokens (3 tool_calls)
   - Kostnad: `(500 * $0.0025 + 150 * $0.01) / 1000 = $0.00275`

2. **Request 2:**
   - Input: 1200 tokens (alle messages + tool results)
   - Output: 200 tokens (final answer)
   - Kostnad: `(1200 * $0.0025 + 200 * $0.01) / 1000 = $0.005`

**Total:** ~$0.0078 per samtale

### Optimaliseringstips

1. **Reduser function descriptions:** Bruk korte, presise descriptions (< 100 tegn per parameter)
2. **Limit funksjoner per request:** Send kun relevante funksjoner (dynamisk tools array)
3. **Cache system messages:** Bruk prompt caching (50% rabatt på cached tokens)
4. **Batch parallelle kall:** Unngå N+1 problem — bruk parallel calling
5. **Tool_choice strategisk:** Bruk `"none"` hvis du vet at bruker bare chatter

### Lisensiering

| Lisens | Azure OpenAI tilgang | Function calling support |
|--------|---------------------|-------------------------|
| **Microsoft 365 E3/E5** | Ikke inkludert | N/A (må kjøpe separat) |
| **Azure subscription** | Pay-as-you-go | Full support (alle modeller) |
| **Copilot Studio (standalone)** | Begrenset via Actions | Indirekte (via Copilot Studio abstraksjon) |
| **Microsoft Foundry** | Inkludert | Full support + Prompt Flow orkestrering |

**Viktig:** Azure OpenAI krever godkjenning (application form). Offentlig sektor i Norge har vanligvis raskere godkjenning.

## For arkitekten (Cosmo)

### Spørsmål å stille kunden

1. **Hva er use casen?**
   - "Skal modellen bare svare på spørsmål, eller også utføre handlinger (f.eks. oppdatere database)?"
   - Avgjør om function calling i det hele tatt trengs, eller om RAG er nok

2. **Hvilke systemer skal modellen integrere med?**
   - "Er det interne API-er, tredjepartstjenester, eller databaser?"
   - Mapping: Interne API-er = Azure Functions som wrapper, Tredjepartstjenester = vurder latency

3. **Hva er risikoen ved feil funksjonskall?**
   - "Hva skjer hvis modellen kaller feil funksjon eller med feil argumenter?"
   - Høy risiko → krever user confirmation, lav risiko → automatisk utførelse OK

4. **Hva er token-budsjettet?**
   - "Hvor mange funksjoner må defineres samtidig? Hvor stort er context window-behovet?"
   - Mange funksjoner (>10) → vurder function routing (modellen velger kategori først, deretter spesifikk funksjon)

5. **Er det behov for parallelle kall?**
   - "Trenger brukeren svar som krever data fra flere kilder samtidig?"
   - Ja → bruk GPT-4o med parallel calling, Nei → GPT-4o-mini for kostnadsbesparing

6. **Hva er latency-kravet?**
   - "Må svaret komme innen sekunder, eller er minutter OK?"
   - Lavt latency → parallel calling + caching, Høyt latency → asynkron Assistants API

7. **Hvordan skal feil håndteres?**
   - "Hva skal skje hvis en API-kall feiler? Skal modellen prøve igjen eller gi feilmelding?"
   - Design for retry logic og graceful degradation

8. **Er det compliance-krav?**
   - "Håndterer funksjoner personopplysninger eller kritiske beslutninger?"
   - GDPR/AI Act → krever audit logging og menneske-i-loop

### Fallgruver

| Fallgruve | Hvorfor det skjer | Hvordan unngå |
|-----------|-------------------|---------------|
| **Token cost explosion** | Mange funksjoner + multi-turn loops | Start med få funksjoner, ekspander gradvis. Monitorér token-bruk |
| **Infinite loops** | Modellen kaller funksjoner i sirkel | Implementer `max_iterations` guard, logg reasoning patterns |
| **Hallucinated arguments** | Modellen fyller inn data den ikke har | Valider alle argumenter mot JSON Schema, bruk `required` fields |
| **Security vulnerabilities** | Funksjoner har for bred tilgang | Principle of least privilege — dedicated service accounts per funksjon |
| **Fragile prompts** | System message ikke spesifikk nok | Test med adversarial prompts, bruk few-shot examples |
| **Version drift** | API-endringer bryter function schemas | Pin API versions, bruk schema validation i CI/CD |

### Anbefalinger per modenhetsnivå

**Nybegynner (første gang med function calling):**
- Start med én enkel funksjon (f.eks. `get_current_time`)
- Bruk `tool_choice: "auto"` og observer modellens oppførsel
- Implementer robust error handling før produksjon
- Les Microsoft's [responsible AI guidelines](https://learn.microsoft.com/en-us/azure/foundry/responsible-ai/openai/overview)

**Viderekomne (har bygget noen agenter):**
- Implementer parallel function calling for bedre performance
- Bygg en function router (modellen velger kategori, deretter spesifikke funksjoner)
- Eksperimenter med `tool_choice` for å styre modellens oppførsel
- Vurder Semantic Kernel for bedre orkestrering

**Ekspert (produksjonssystemer i drift):**
- Finetuning for å forbedre function calling accuracy (spesielt for domene-spesifikke funksjoner)
- Implementer dynamisk tool loading (kun relevante funksjoner sendes basert på context)
- Bygg monitoring for function call success rates og failure patterns
- Vurder hybrid approach (function calling + RAG + structured outputs)

## Kilder og verifisering

**Verified (fra Microsoft Learn MCP-research):**

1. [How to use function calling with Azure OpenAI](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/function-calling) — **Konfidensnivå: Høy** (offisiell dokumentasjon, oppdatert januar 2026)
2. [Understand OpenAI function calling](https://learn.microsoft.com/en-us/dotnet/ai/conceptual/understanding-openai-functions) — **Konfidensnivå: Høy** (konseptuell guide med Semantic Kernel-eksempler)
3. [Azure OpenAI Assistants function calling](https://learn.microsoft.com/en-us/azure/foundry-classic/openai/how-to/assistant-functions) — **Konfidensnivå: Høy** (Assistants API-spesifikk dokumentasjon)
4. [Fine-tuning functions](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/fine-tuning-functions) — **Konfidensnivå: Høy** (for advanced use cases)
5. [Structured outputs](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/structured-outputs) — **Konfidensnivå: Høy** (komplementær teknikk til function calling)

**Baseline (fra modellkunnskap januar 2025):**

- JSON Schema validation best practices
- Security principles (least privilege, validation)
- Cost optimization strategies
- GDPR/Schrems II/AI Act compliance principles

**Confidence markers per seksjon:**

| Seksjon | Konfidens | Kilde |
|---------|-----------|-------|
| Kjernekomponenter | **Verified** | Microsoft Learn API reference |
| Arkitekturmønstre | **Verified** | Microsoft Learn examples + code samples |
| Beslutningsveiledning | **Baseline** | Best practices fra dokumentasjon |
| Integrasjon med Microsoft-stakken | **Verified** | Microsoft Learn cross-references |
| Offentlig sektor (Norge) | **Baseline** | Standard compliance-krav (generelt, ikke Azure-spesifikt) |
| Kostnad og lisensiering | **Verified** | Azure pricing + Microsoft Learn token counting |
| For arkitekten (Cosmo) | **Baseline** | Syntese av dokumentasjon + praktisk erfaring |

**Siste verifikasjon:** 2026-02-04 via MCP microsoft-learn server