System instructions in de Gemini API

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.

System instruction instellen

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

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.

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),
)

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.

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?")

Persona's definiëren

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

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.

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.

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.

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.