# System instructions in de Gemini API

[[TOC]]

## Wat zijn system instructions

System instructions zijn instructies die je als ontwikkelaar aan het model geeft voordat de gebruiker ook maar iets typt. Ze bepalen de persona, het gedragsdomein, de taalstijl, de veiligheidsregels en de beperkingen van je applicatie. De gebruiker ziet ze niet en kan ze niet zomaar overschrijven.

Dit is fundamenteel anders dan de user-prompt. Waar een user-prompt per beurt verandert, vormen system instructions de vaste "grondwet" van je AI-applicatie: ze blijven gelden over de gehele sessie.

:::info title="Nieuwe SDK en model"
De codevoorbeelden gebruiken de unified Google GenAI SDK (`google-genai`). De oude bibliotheek `google-generativeai` is sinds de Gemini 2.0-generatie afgeschaft en wordt niet meer onderhouden. Als model gebruiken we `gemini-3.5-flash`, in juni 2026 het algemeen beschikbare (GA) snelle model. Controleer altijd de actuele modellijst, want versies komen en gaan.
:::

## System instruction instellen

In de nieuwe SDK maak je eerst een `Client` aan en geef je de instructie mee via `GenerateContentConfig`.

```python
from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Hoe kan ik mijn bestelling retourneren?",
    config=types.GenerateContentConfig(
        system_instruction="""Je bent een klantenservice-medewerker voor CloudShop Nederland.
Je helpt klanten uitsluitend met vragen over bestellingen, leveringen en retouren.
Antwoord altijd in het Nederlands, vriendelijk en professioneel.
Gebruik de je-vorm, niet de u-vorm.
Als een vraag buiten je domein valt, verwijs je beleefd naar de juiste afdeling.
Noem nooit concurrenten bij naam.""",
    ),
)

print(response.text)
```

De client leest de API-sleutel standaard uit de omgevingsvariabele `GEMINI_API_KEY`. Zet die dus eerst in je omgeving in plaats van hem in code te plakken.

## Complexe system instructions structureren

Voor uitgebreide instructies gebruik je een Markdown-structuur. Definieer de instructie eenmaal als constante en hergebruik die.

```python
SYSTEM_INSTRUCTION = """
# Rol en identiteit
Je bent Max, een AI-assistent van TechSupport BV.
Je werkt uitsluitend voor zakelijke klanten met IT-abonnementen.

# Gedragsregels
- Antwoord altijd in de taal van de gebruiker
- Houd antwoorden beknopt (max 150 woorden) tenzij technische diepgang gevraagd wordt
- Vraag om verduidelijking als een probleem niet duidelijk is
- Escaleer naar menselijke support als je er niet uitkomt

# Kennisdomein
Je hebt expertise in:
- Windows Server 2019/2022
- Microsoft 365 beheer
- Microsoft Entra ID (voorheen Azure Active Directory)
- Netwerktroubleshooting

# Verboden onderwerpen
- Persoonlijke adviezen buiten IT
- Prijsonderhandelingen (verwijs naar de accountmanager)
- Concurrentievergelijkingen

# Toon
Professioneel maar toegankelijk. Gebruik vakjargon alleen als de gebruiker dat ook doet.
"""

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Mijn gebruikers kunnen niet inloggen op Microsoft 365.",
    config=types.GenerateContentConfig(system_instruction=SYSTEM_INSTRUCTION),
)
```

:::tip title="Structureer met kopjes"
Verdeel lange system instructions in duidelijke secties met kopjes. Gemini volgt gestructureerde instructies consequenter dan een lange aaneengesloten lap tekst.
:::

## Dynamische system instructions

In productieapplicaties wil je de system instruction aanpassen per gebruiker of context. Bouw de instructie op in een functie en geef hem per aanroep mee.

```python
def build_instruction(user_role: str, language: str, company_name: str) -> str:
    if user_role == "admin":
        access = "Je hebt toegang tot alle klantgegevens en kunt bestellingen annuleren."
    else:
        access = "Je kunt alleen publieke informatie geven, geen klantgegevens."

    return f"""Je bent een AI-assistent voor {company_name}.
Taal: {language}
Gebruikersrol: {user_role}

{access}

Houd je altijd aan het privacybeleid van {company_name}."""


def ask(user_role: str, language: str, company_name: str, prompt: str):
    instruction = build_instruction(user_role, language, company_name)
    return client.models.generate_content(
        model="gemini-3.5-flash",
        contents=prompt,
        config=types.GenerateContentConfig(system_instruction=instruction),
    )


admin_answer = ask("admin", "Nederlands", "Mijn Webshop", "Annuleer bestelling 1234.")
klant_answer = ask("klant", "Nederlands", "Mijn Webshop", "Wat is jullie retourbeleid?")
```

:::warn title="Vertrouw rollen niet op het model"
Bepaal de rol (admin of klant) altijd server-side op basis van een geverifieerde sessie. Gebruik de rol in de system instruction alleen om de toon en het gedrag te sturen, niet als enige beveiliging. Echte autorisatie hoort in je eigen code, niet in de prompt.
:::

## Persona's definiëren

Een system instruction is ideaal om een consistente persona neer te zetten.

```python
PERSONA = """Je bent Professor Van Dijk, een Nederlandse hoogleraar economie.
Je communiceert:
- Wetenschappelijk maar toegankelijk
- Met concrete Nederlandse voorbeelden
- Voorzichtig met stellige uitspraken (gebruik "onderzoek suggereert" in plaats van "het is bewezen")
- Politiek neutraal

Je verwelkomt elke vraag met oprechte interesse."""

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Wat veroorzaakt inflatie?",
    config=types.GenerateContentConfig(system_instruction=PERSONA),
)
```

## System instructions in de REST API

Roep je de API rechtstreeks aan, dan geef je `system_instruction` mee als apart veld naast `contents`.

```bash
curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "system_instruction": {
      "parts": [{"text": "Antwoord altijd als een vriendelijke en behulpzame assistent."}]
    },
    "contents": [
      {"role": "user", "parts": [{"text": "Hallo, wie ben je?"}]}
    ]
  }'
```

Geef de sleutel mee via de header `x-goog-api-key` in plaats van als querystring. Zo komt hij niet in serverlogs of browsergeschiedenis terecht.

## Veiligheidsregels via system instructions

Je kunt gedragsgrenzen vastleggen in de instructie. Besef wel dat dit gedrag stuurt, geen harde garantie biedt.

```python
TUTOR = """Je bent een AI-tutor voor middelbare scholieren.

Veiligheidsregels:
- Beantwoord nooit vragen die op huiswerkfraude lijken
- Geef aanwijzingen in plaats van complete antwoorden
- Deel nooit persoonlijke informatie van gebruikers
- Vermijd alle inhoud die ongepast is voor de leeftijdsgroep 12 tot 18

Bij twijfel: geef een helpend antwoord dat de leerling aanzet tot zelf nadenken."""

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Kun je mijn wiskundehuiswerk voor me maken?",
    config=types.GenerateContentConfig(system_instruction=TUTOR),
)
```

## System instructions en chatsessies

Gebruik je een chat-object, dan zet je de instructie eenmaal bij het aanmaken van de chat. Hij geldt dan voor alle beurten in die sessie.

```python
chat = client.chats.create(
    model="gemini-3.5-flash",
    config=types.GenerateContentConfig(
        system_instruction="Je bent een beknopte reisassistent. Antwoord in maximaal drie zinnen."
    ),
)

print(chat.send_message("Wat is een goede tijd om Lissabon te bezoeken?").text)
print(chat.send_message("En het weer in de zomer?").text)
```

Wil je de instructie midden in een gesprek veranderen, dan maak je een nieuwe chat of een nieuwe aanroep met een andere config aan. Een lopende sessie houdt zijn oorspronkelijke instructie vast.

:::faq
### Kan een gebruiker de system instruction overschrijven via een jailbreak?
Gemini is redelijk robuust tegen prompt injection in de user-beurt, maar niet onfeilbaar. Voeg expliciete grenzen toe, zoals een regel dat het model zijn rol niet mag wijzigen, en test actief op jailbreak-pogingen in jouw domein. Leun voor echte autorisatie nooit alleen op de prompt.

### Hoeveel tokens kan een system instruction bevatten?
Er is geen apart hard maximum los van de contextlimiet van het model. In de praktijk werken instructies van 500 tot 2000 woorden goed. Langere instructies verhogen de tokenkosten per aanroep, omdat ze bij elke call worden meegestuurd.

### Verandert de system instruction de safety settings?
Nee, safety settings zijn een aparte laag. De system instruction stuurt gedrag, maar de ingebouwde safety-filters van Google blijven actief, ook als je het model instrueert ze te negeren.

### Kan ik de system instruction per bericht aanpassen in een chatsessie?
Niet binnen dezelfde sessie. De instructie ligt vast voor de levensduur van de chat of de aanroep. Wil je van context wisselen, maak dan een nieuwe chat of een nieuwe generate_content-aanroep met een aangepaste config.

### Werkt de oude code met GenerativeModel nog?
De oude bibliotheek `google-generativeai` met het `GenerativeModel`-object is afgeschaft. Migreer naar de unified `google-genai` SDK met het `Client`-object en geef de instructie mee via `GenerateContentConfig`. De officiële migratiegids beschrijft de stappen.

### Welk model gebruik ik in juni 2026?
`gemini-3.5-flash` is op dat moment het algemeen beschikbare snelle model. De Gemini 2.5-modellen worden medio 2026 afgeschaft. Controleer de actuele modellijst en kies een GA-versie voor productie.
:::