Je eigen helper bouwen¶

Een helper is een functie van je product die één ding schrijft vanuit een beschrijving: een samenvatting van een supportticket, een antwoord op een e-mail, een zoekopdracht uit een vraag in gewone taal. Je bouwt er een op POST /responses, met je eigen instructies en, waar je code het antwoord leest, je eigen JSON Schema. Noem de helper in het veld helper, dan meet en traceert Core elke aanroep als werk van die helper, zodat je ziet wat elke helper kost. Laat je model weg, dan draait de beurt op het hulpmodel van je organisatie.

Verder is een helperbeurt een gewone beurt. Alles op Een modelaanroep doen geldt; deze pagina beschrijft wat helper toevoegt.

De helper een naam geven¶

helper is een uitbreiding van Core op het verzoek: een naam die je zelf kiest en die Core meegeeft aan alles wat de beurt verbruikt. Core houdt geen lijst van je helpers bij en toetst een naam alleen aan deze regels:

• twee tot vier delen, gescheiden door punten, dus altijd minstens één punt;
• elk deel begint met een kleine letter, gevolgd door kleine letters, cijfers of _;
• hoogstens 64 tekens;
• niet beginnend met assist., dat is gereserveerd voor de helpers van Core zelf.

Zet je product of bedrijf in het eerste deel, zodat de naam zegt van wie de helper is: acme.summary, acme.ticket_triage, acme.mail.reply. Een naam die een regel breekt, zoals summary, Acme.Summary of assist.summary, wordt geweigerd met 400 en helper in error.param.

Gebruik één naam per helper en houd hem vast. Op die naam filter je later het verbruik, dus een helper die halverwege de maand een andere naam krijgt, verschijnt als twee.

Het hulpmodel van de organisatie gebruiken¶

Je organisatie kan een hulpmodel kiezen: het model dat voor helpers schrijft, ook voor Beschrijf wat je nodig hebt in de console. Een beheerder stelt het in bij de instellingen van de organisatie, en een sleutel met management stelt het in als assist_model met PATCH /organisation (Organisaties beheren via de API). Heeft de organisatie zelf niets gekozen, dan gebruikt ze de standaard van de deployment.

Laat je model weg op een beurt die een helper noemt, dan draait de beurt op dat hulpmodel. Je code hoeft dan niet te weten welk model de organisatie koos, en een beheerder kan van model wisselen zonder dat je product verandert.

Is er geen hulpmodel beschikbaar, dan wordt de beurt geweigerd met 409, voordat er een model wordt aangeroepen:

Een sleutel met de capability assist kan dit vooraf nagaan met GET /assist. Dat antwoordt {"model": ..., "source": ...}: het hulpmodel dat geldt en of de organisation of de deployment het koos, of voor beide null als er geen is. Een helperbeurt zelf heeft geen capability nodig naast wat elke beurt nodig heeft.

Een helperbeurt sturen¶

Deze helper schrijft een korte samenvatting van een supportticket en geeft het een prioriteit. Het antwoord volgt een JSON Schema, zodat je code velden leest in plaats van tekst te ontleden (Gestructureerde uitvoer). Met store: false bewaart Core niets van de beurt: zo'n samenvatting wordt één keer getoond en nooit voortgezet.

curl -s "$CORE_URL/responses" \
  -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
  -d '{
    "helper": "acme.summary",
    "instructions": "Vat het supportticket samen in hoogstens twee zinnen en geef de prioriteit.",
    "input": "Sinds vanochtend kan geen enkele klant inloggen op het portaal. We krijgen fout 502.",
    "store": false,
    "text": {
      "format": {
        "type": "json_schema",
        "name": "ticket_summary",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "summary": { "type": "string" },
            "priority": { "type": "string", "enum": ["low", "normal", "high"] }
          },
          "required": ["summary", "priority"],
          "additionalProperties": false
        }
      }
    }
  }'

Het antwoord is een gewoon response-object. output_text bevat de JSON die je schema beschrijft, en model noemt het hulpmodel dat antwoordde. Het antwoord herhaalt helper niet: dit antwoord noch GET /responses/{id} bevat het. Past het antwoord van het model niet bij het schema, dan mislukt de beurt met invalid_structured_output en krijg je geen half antwoord.

De OpenAI Python SDK kent helper niet, dus geef het mee via extra_body:

import json
from openai import OpenAI

client = OpenAI(base_url="https://<your-deployment>/api/v1", api_key="ack_...")

response = client.responses.create(
    instructions="Vat het supportticket samen in hoogstens twee zinnen en geef de prioriteit.",
    input="Sinds vanochtend kan geen enkele klant inloggen op het portaal. We krijgen fout 502.",
    store=False,
    text={
        "format": {
            "type": "json_schema",
            "name": "ticket_summary",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "priority": {"type": "string", "enum": ["low", "normal", "high"]},
                },
                "required": ["summary", "priority"],
                "additionalProperties": False,
            },
        }
    },
    extra_body={"helper": "acme.summary"},
)
ticket = json.loads(response.output_text)

helper bestaat alleen op POST /responses. POST /messages heeft zo'n veld niet.

De beurt bewaren of niet¶

store werkt zoals op elke beurt (Opslaginstellingen). Voor een eenmalige helper, zoals een samenvatting, een vertaling of een concept dat je gebruiker in je eigen product verder bewerkt, stuur je store: false: de aanroep antwoordt 200 en Core bewaart geen gesprek. Laat store zoals het is als je de beurt wilt teruglezen of voortzetten, bijvoorbeeld bij een helper die je gebruiker het nog eens kan laten proberen. Het verbruik wordt in beide gevallen gemeten.

Regels die gelden als bij elke beurt¶

Een helper noemen versoepelt niets. De beurt is de eigen beurt van je sleutel, onder je eigen instructies:

• Policy. De policy van je sleutel beslist of het hulpmodel, of het model dat je noemde, gebruikt mag worden en waar het mag draaien. Een model dat de policy weigert, krijgt 403, zoals bij elke beurt.
• Limieten. De maandlimieten van je sleutel en je organisatie laten de beurt toe. Is een limiet bereikt, dan volgt 429.
• Persoonsgegevens. Heeft je sleutel pseudonymisation, dan worden persoonsgegevens in de beschrijving voor het model verborgen, zoals bij elke beurt (Persoonsgegevens verbergen).
• Tools, terugvallen en streamen werken als bij elke beurt. Een helperbeurt mag tools aanroepen, valt terug langs de terugvalketen van het model en kan streamen.

Helpers voorbij één aanroep¶

De helpernaam blijft bij het werk, waar de beurt het ook heen brengt:

• Een achtergrondrun ("background": true, Een beurt op de achtergrond draaien) houdt de helper vast voor elke ronde.
• Een taak die een agent vanuit een helperbeurt start, is ook werk van de helper: de run van de taak en wat die verbruikt, dragen dezelfde helpernaam.
• Een agent die als tool wordt aangeroepen tijdens een helperbeurt, verbruikt ook voor de helper. Zijn verbruiksrijen noemen zowel de agent als de helper.
• Een planning bewaart helper bij het verzoek dat ze afvuurt, maar dat verzoek moet een model noemen, of een agentversie die er een vastlegt. Core controleert het verzoek van een planning als je haar schrijft, en het hulpmodel wordt pas opgezocht als een beurt begint. Een verzoek met een helper en zonder model wordt daarom geweigerd met 422 op request.model: Name a model, or an agent version that fixes one. (Planningen).

Zien wat een helper kost¶

Elke verbruiksrij die de beurt schrijft, draagt de naam van de helper in helper: de modelaanroepen, de tools die ze uitvoerde en de beurten van agents die ze aanriep. De helpers van Core zelf staan naast de jouwe onder hun eigen naam, zoals assist.json_schema voor het JSON Schema-concept in de console.

• GET /usage?helper=acme.summary toont de rijen van één helper. De naam moet precies kloppen, een begin is niet genoeg: acme vindt acme.summary niet.
• GET /usage/summary splitst elke groep per helper, dus elk totaal draagt helper naast model en agent. Rijen die geen helper schreef, vormen groepen met helper: null.
• In de sectie Gebruik van de console staat op het tabblad Kosten de kaart Per helper: één regel per helper met wat zijn werk in de gekozen periode kostte (Gebruik in de console).
• In de sectie Traces van de console vul je onder Meer filters de naam van de helper in bij Klussoort om alleen de modelaanroepen van die helper te zien (Een trace lezen). Dit filter bestaat alleen in de console; geen tracelijst die een sleutel leest, kent het.

curl -s "$CORE_URL/usage?helper=acme.summary&from=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $CORE_KEY"

Meer over de verbruiksroutes staat in Gebruik en audit via de API.