Prompts via de API¶

Het concept achter agents staat in Agents.

Op deze pagina sla je een promptsjabloon op met de API, voeg je versies toe en gebruik je de prompt in een verzoek. Met een opgeslagen prompt gebruik je dezelfde instructies bij meerdere aanroepen en werk je ze bij zonder je applicatie uit te rollen. Een verzoek kiest een vaste versie of de nieuwste, en het auditspoor legt de gebruikte versie vast.

Je sleutel heeft de capability prompts nodig. Hetzelfde doe je met de muis in Prompts in de console.

Een prompt maken¶

curl -s -X POST "$CORE_URL/prompts" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"name": "triage",
         "template": "Classificeer het ticket hieronder als facturatie, technisch of overig.\n\n{{ ticket }}",
         "input_schema": {"properties": {"ticket": {"type": "string"}}, "required": ["ticket"]},
         "role": "developer"}'

Een geslaagd verzoek geeft 201 en maakt de prompt met versie 1 aan.

Sjablonen ondersteunen alleen het invullen van plaatshouders. Voorwaarden, filters en includes worden niet ondersteund.

Het invoerschema¶

input_schema is een JSON Schema-object, zodat elk hulpmiddel dat JSON Schema leest er een formulier of een aanroep van kan maken. Elke property is één variabele:

required noemt de variabelen die een aanroep moet invullen. Een variabele met een standaard staat daar nooit in. Andere JSON Schema-sleutels, zoals pattern of geneste objecten, worden geweigerd: een waarde wordt altijd als tekst ingevoegd, dus er is niets voor ze om te beschrijven. Een getal wordt ingevoegd zoals je het stuurde, zoals 3 of 2.5, en een boolean als true of false.

Invulwaarden¶

Een {{ $naam }} is een invulwaarde: een waarde die je één keer vastlegt in install_values en die Core invult voordat het sjabloon wordt gelezen, zodat hij deel is van de instructies zelf. Een variabele vult de aanroeper bij elke aanroep in. Elke invulwaarde zegt wat hij is, net zoals een parameter van een gedeelde bundel:

{"bedrijf": {"type": "string", "value": "Acme"},
 "max_items": {"type": "number", "value": 5, "description": "hoeveel items te noemen"},
 "toon": {"type": "enum", "value": "formeel", "allowed": ["formeel", "informeel"]}}

type is string, number of enum; een enum noemt zijn toegestane waarden in allowed en zijn value is daar een van. Deel je de prompt via een publicatie, dan wordt elke invulwaarde een parameter van dat type met jouw waarde als standaard, en vult wie hem installeert zijn eigen waarde in (Delen). Elke {{ $naam }} heeft een waarde nodig, elke waarde moet worden gebruikt, een naam kan niet ook een variabele zijn, en een waarde mag geen {{ of }} bevatten.

metadata hoort bij de prompt, niet bij één versie: een nieuwe versie die het veld weglaat, houdt wat er staat, en {} wist het. Zet er neer wat je eigen applicatie nodig heeft — Core kijkt er nooit in.

Een versie toevoegen¶

curl -s -X POST "$CORE_URL/prompts/prm_5Nj2.../versions" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"template": "Classificeer het ticket hieronder als facturatie, technisch, beveiliging of overig.\n\n{{ ticket }}",
         "input_schema": {"properties": {"ticket": {"type": "string"}},
                          "required": ["ticket"]}}'

Versies worden genummerd vanaf 1 en kunnen na het aanmaken niet worden gewijzigd.

Een prompt kopiëren¶

Wil je een nieuwe prompt beginnen vanuit een die je al hebt, kopieer hem dan onder een nieuwe naam:

curl -s -X POST "$CORE_URL/prompts/prm_8Kd1.../copy" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"name": "greeting-formal"}'

Het antwoord is 201 met de nieuwe prompt, op zijn eigen versie 1. Noem een version om die te kopiëren in plaats van de laatste. De kopie neemt de template, het invoerschema, de rol en de invulwaarden van die versie over, en de labels en metadata van de prompt. Vanaf dan is het je eigen prompt: wat je eraan verandert, verandert het origineel niet. Een kopie die een publicatie verzegeld installeerde, en een kopie waarvan de publicatie losmaken niet toestaat ('fork': false), hem voor haar eigen agents houdt of hergebruik niet toestaat, kun je niet kopiëren: 403.

Een prompt gebruiken¶

{
  "model": "<een model-id>",
  "prompt": { "id": "triage", "variables": { "ticket": "Mijn kaart is twee keer belast." } }
}

Stel id in op de promptnaam of het prm_-id. Elke waarde in variables moet passen bij zijn property in het invoerschema: een number neemt een JSON-getal, niet de tekst "3", en een enum neemt een van zijn waarden. Laat version weg om de nieuwste versie op het moment van aanroepen te gebruiken. Geef een versienummer op om die versie te blijven gebruiken nadat er nieuwe zijn gepubliceerd.

Core plaatst de ingevulde prompt vóór de andere invoeritems. Opgeslagen gesprekken bewaren deze, zodat je in het gesprek kunt teruglezen welke instructies zijn gebruikt.

Een prompt invullen voor een tool¶

Een prompt kan ook de invoer van een tool zijn in plaats van die van een model. Zet een argument van een tool-alias vast op {"$prompt": {"id": "banner"}}; elke aanroep van de alias vult dan de prompt in met de tool_variables van de aanroeper en geeft de tekst door aan de tool, bijvoorbeeld een afbeeldingsmodel. Zie Een argument vastzetten op een opgeslagen prompt.

Templatevariabelen¶

Het sjabloon krijgt de autoriteit van de ingestelde rol. De waarde van een variabele krijgt het label onvertrouwd en wordt niet opnieuw verwerkt op placeholders: een waarde met {{ ticket }} blijft letterlijke tekst.

De waarde komt in de tekst van het sjabloon te staan, op de plek van de placeholder. Voor een sleutel met trust_envelope verpakt Core haar daar in <untrusted source="prompt-variable" name="...">, zodat het model te horen krijgt dat het gegevens zijn. Voor een sleutel zonder die capability staat de waarde als gewone tekst in de instructie, zoals in elk promptsjabloon, en kan het model haar niet onderscheiden van de woorden eromheen.

Gebruik variabelen voor inhoud van gebruikers en zet applicatie-instructies in het sjabloon.

Standaardwaarden voor variabelen¶

Een variabele kan een standaard hebben die Core invult als de beurt er geen waarde voor meestuurt. Geef in zijn property een van twee sleutels:

• default: een vaste waarde van het eigen type van de variabele; als tekst maximaal 4096 tekens.
• x-builtin: de naam van een waarde die Core zelf kent op het moment van de beurt, zoals date.

curl -s -X POST "$CORE_URL/prompts" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"name": "helpdesk",
         "template": "Vandaag is het {{ datum }}. Antwoord {{ toon }}.\n\n{{ vraag }}",
         "input_schema": {
           "properties": {"datum": {"type": "string", "x-builtin": "date"},
                          "toon": {"type": "string", "default": "kort en vriendelijk"},
                          "vraag": {"type": "string"}},
           "required": ["vraag"]}}'

Een beurt die alleen vraag meestuurt, levert het model Vandaag is het 2026-09-24. Antwoord kort en vriendelijk. gevolgd door de vraag. Per plaatshouder kiest Core de waarde in deze volgorde:

1. de waarde in prompt.variables van de beurt;
2. anders de default of x-builtin van de variabele;
3. anders niets: een verplichte variabele geeft dan 400, een optionele blijft leeg.

Laat de naam weg uit prompt.variables als je de standaard wilt. Een lege tekst is ook een waarde en gaat voor de standaard.

Een variabele heeft hoogstens één standaard, en een variabele met een standaard staat nooit in required. Een nieuwe versie declareert zijn variabelen op dezelfde manier. Elke leesroute geeft het invoerschema terug zoals je het schreef, aangevuld met "type": "object", "additionalProperties": false, en description als "" waar je die weggelaten had.

Wat een beurt niet heeft, blijft leeg; de beurt wordt er niet om geweigerd. Hoe je een persoon en zijn attributen meestuurt, staat in Bouwen voor personen.

De vier tijdwaarden worden gelezen in de eerste tijdzone die er is: timezone op het verzoek (Verzoekvelden), de timezone van de planning die de beurt afvuurt, de timezone van je organisatie (Tijdzone), en anders UTC.

Een standaard en wat Core zelf bepaalt — de tijdwaarden, agent_name, model, thread_id en run_id — krijgen het gewicht van het sjabloon. subject_id, subject_name en subject.<attribuut> komen van de aanroeper en worden behandeld als de waarde van een variabele, net als een waarde in prompt.variables (hierboven). Dat geldt ook voor organisation_name, omdat anderen dan de schrijver van het sjabloon die naam kunnen wijzigen.

Een agent die de prompt vastzet, gebruikt dezelfde standaarden: agent.variables hoeft een variabele met een standaard niet te noemen, en agent_name wordt de naam van die agent.

Fouten¶

Een weigering in een beurt -- een verzoek dat een prompt noemt -- komt binnen in het foutobject van OpenAI, met het veld in error.param; een weigering bij het schrijven naar /prompts is problem+json, met het veld in errors.

De gebruikte versie terugvinden¶

Elke keer dat een prompt wordt ingevuld, ontstaat een auditgebeurtenis prompt.rendered met het prompt-id, de naam en de versie. Bekijk deze bij onderzoek naar veranderd modelgedrag.