Verbeteringen via de API¶

Het concept achter verbeteranalyses staat in Inzicht.

Met de routes onder /improvements zet je verbeteranalyses aan, lees je de voorstellen die ze schrijven, beslis je erover en pas je ze toe, vanuit je eigen backend. Een beheerder doet hetzelfde in Verbeteringen in de console. De velden van elk verzoek en antwoord staan in de API-referentie; deze pagina legt uit wat je ermee doet.

Wat je nodig hebt¶

• De installatie draait verbeteranalyses. Je operator zet ze aan voor de hele installatie (CORE_IMPROVEMENTS_ENABLED); standaard staan ze uit. Tot dan antwoordt elke route hier 404.
• De capability improvements in het plafond van je organisatie en op je sleutel (Capabilities). Met alleen improvements lees je de instellingen en de analyses, beslis je over voorstellen en start je een analyse.
• Ook management om de instellingen te wijzigen, omdat analyses aanzetten geld van de organisatie uitgeeft. Houdt de organisatie erboven het sleutelbeheer bij zich, dan krijgt die wijziging 403 (Voorbehouden sleutelbeheer).
• agents, prompts of skills om een voorstel over een agent, prompt of skill toe te passen, zoals de routes van die agent, prompt of skill dat zelf ook vragen.

Een analyse is van de organisatie, niet van één persoon. Een subjecttoken krijgt geen toegang tot deze routes, en een verzoek met de header X-Core-Subject krijgt 403.

Elke route hier is ook een tool op het MCP-endpoint van je sleutel (Beheren via MCP).

Analyses aanzetten en instellen¶

GET /improvements/settings geeft de instellingen van je organisatie: of analyses aanstaan, de klok, de periode, elke controle met haar drempels, de pseudonimisering, het maximum aan modelaanroepen, wanneer de volgende analyse draait (next_run_at) en wat de analyses van vorige maand deden (last_month).

Zet analyses aan met PATCH /improvements/settings. Je stuurt alleen wat verandert:

curl -s -X PATCH "$CORE_URL/improvements/settings" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"enabled": true, "cron": "0 3 * * 1-5", "timezone": "Europe/Amsterdam"}'

Aanzetten is de toestemming van je organisatie: vanaf dan leest het analysemodel haar gesprekken, gepseudonimiseerd, en kost elke analyse modelaanroepen die meetellen voor de maandlimiet.

De controles in checks, met hun standaarddrempel:

curl -s -X PATCH "$CORE_URL/improvements/settings" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"checks": {"off_purpose_agent": {"enabled": false}, "missing_tool": {"threshold": 0.3}}}'

Gesprekken lezen kan alleen als traces aanstaan voor je organisatie (tracing_enabled, Je eigen organisatie). Staan ze uit, dan berekenen missing_tool, failing_skill en off_purpose_agent alleen de cijfers, en slaan repeated_first_call, shared_procedure en evaluation_drafts zich helemaal over: die schrijven dan niets (skipped_no_tracing). unused_skill, instruction_procedure en leaner_agent lezen geen traces.

Het analysemodel¶

GET /improvements/model zegt welk model analyses nu gebruiken:

{"object": "improvement_model", "model": "claude-sonnet-5", "source": "deployment"}

source is organisation als je organisatie zelf een model koos, deployment als ze de standaard van de installatie volgt, en null als er geen model is. Zonder model leveren missing_tool, failing_skill en off_purpose_agent alleen cijfers, zonder uitleg en zonder voorgestelde wijziging, en stellen shared_fact en episode_patterns niets voor; repeated_first_call leest zonder model en stelt nog steeds een instructions_addition voor. Core valt nooit terug op het hulpmodel (assist_model).

Kies een model met analysis_model op PATCH /organisation, met management en onder dezelfde regels als assist_model: een chatmodel uit de catalogus van je organisatie, geen router. null volgt weer de standaard van de installatie (Je eigen organisatie).

Voorstellen lezen¶

curl -s "$CORE_URL/improvements/proposals?status=open&check=failing_skill" \
    -H "Authorization: Bearer $CORE_KEY"

GET /improvements/proposals is een lijst met cursor, te filteren op status, check, target_kind (agent, prompt, skill, evaluation of memory_store) en target_id. GET /improvements/proposals/{id} geeft één voorstel met evidence: de beurten waar de bevinding op rust, hoogstens twintig, de nieuwste eerst. Elk bewijsstuk is alleen ids (response_id, thread_id, subject_id) en een tijdstip; met response_id lees je de trace van die beurt, onder de gewone regels voor traces. Een voorstel van de controle shared_fact of episode_patterns rust in plaats daarvan op geheugenrecords: daar is memory_id gevuld en response_id leeg (null), en je leest het record met GET /memory/{memory_id}.

{
  "object": "improvement_proposal",
  "id": "prop_01M4…",
  "check": "repeated_first_call",
  "kind": "agent_version",
  "status": "open",
  "target_kind": "agent",
  "target_id": "agt_01M2…",
  "target_name": "support-agent",
  "target_version": 3,
  "title": "support-agent begint bijna elk gesprek met get_opening_hours",
  "summary": "…",
  "rationale": "…",
  "figures": {"tool": "get_opening_hours", "share": 0.86, "turns": 412,
              "calls_saved_per_month": 1650, "tokens_saved_per_month": 2900000},
  "change": {"instructions_addition": "…"},
  "has_placeholders": false,
  "evidence": [{"response_id": "resp_01M4…", "memory_id": null, "thread_id": null, "subject_id": "cust-118",
                "observed_at": "2026-10-11T08:14:03Z"}]
}

Een sleutel ziet alleen voorstellen over wat hij zelf bereikt: noemen de regels van je sleutel alleen bepaalde agents, prompts of skills (Sleutels, capabilities en policy), dan ziet hij geen voorstel over een andere, en is zo'n voorstel 404.

Wat change bevat¶

kind zegt wat voor wijziging het voorstel draagt. change is null als het voorstel alleen cijfers heeft, bijvoorbeeld omdat er geen analysemodel was.

Een opgesteld scenario is title, steps (elk een input-bericht met zijn checks) en variables. Het noemt geen persoon, beurt of gesprek, dus een persoon wissen raakt het niet. Een skill_create die shared_procedure schrijft komt met een agent_version voor elke agent in wiens beurten de werkwijze te zien was (Een skill geleerd uit sessies werkt net zo).

Tekst die het model schreef, kan plaatshouders bevatten zoals <PERSON_1>, omdat het alleen gepseudonimiseerde gesprekken las. has_placeholders is dan true. Core vult ze nooit in.

Over een voorstel beslissen¶

curl -s -X PATCH "$CORE_URL/improvements/proposals/prop_01M4…" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"status": "accepted", "note": "Pakken we volgende sprint op"}'

status is de nieuwe status, note een optionele toelichting van hoogstens 1.000 tekens. Het antwoord is het voorstel met decided_by en decided_at. decided_by is het id van de sleutel die besliste, of auto als een analyse het voorstel zelf toepaste.

resolved zet alleen een analyse: een latere analyse die het probleem niet meer vindt. Een dismissed voorstel komt dismiss_quiet_days dagen niet terug, tenzij het aandeel erachter verdubbelt. applied met PATCH is voor een wijziging die je zelf maakte, zoals een koppeling die je bouwde; de route hieronder zet het zelf.

Core weigert met 409:

• A proposal cannot move from dismissed to applied. — de overgang staat niet in de tabel.
• A newer proposal of the same finding is open; act on that one. — je heropent een voorstel waarvan een latere analyse dezelfde bevinding al opnieuw voorstelde.

Een voorstel toepassen¶

curl -s -i -X POST "$CORE_URL/improvements/proposals/prop_01M4…/apply" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"change": {"instructions_addition": "Openingstijden: ma-vr 9:00-17:00."}}'

Toepassen schrijft de wijziging via de eigen route van de agent, prompt of skill, met jouw sleutel en dus onder elke controle die die route doet. Er wordt niets overschreven: het maakt een nieuwe versie of een nieuwe agent, en wie een vaste versie gebruikt houdt die. Een nieuwe agent-, prompt- of skillversie is een concept, en dat is ook wat een voorstel evaluation_create of evaluation_scenarios schrijft (een conceptversie van een evaluatie, die een beheerder in de console publiceert; een sleutel leest haar niet). Een voorstel agent_trimmed is de uitzondering en publiceert meteen (Proeven). Je sleutels blijven de gepubliceerde versie gebruiken tot een beheerder het concept publiceert, en applied_ref zegt "draft": true. Een agentversie houdt de skillversie die ze vastzette, dus een nieuwe skillversie verandert een agent pas als een nieuwe agentversie haar vastzet. Een verzoek dat de skill zelf noemt zonder versie, in skills, gebruikt de nieuwe skillversie zodra die gepubliceerd is. Verandert de herschreven SKILL.md de omschrijving, dan kiest laden door zoeken de gepubliceerde skill niet meer voor zo'n verzoek, tot er een versie via de eigen route van de skill is geschreven.

De body is optioneel. Zonder change past Core de uitgewerkte wijziging toe. Met change stuur je een wijziging van dezelfde soort, die in de plaats komt en op dezelfde manier wordt gecontroleerd; zo vervang je een plaatshouder of herschrijf je een zin.

Het antwoord is 201 met het voorstel, nu applied, met applied_ref, en een Location-header naar wat er is gemaakt (/api/v1/memory/{id}). Een nieuwe agent-, prompt- of skillversie, of een nieuwe agent of skill, is een concept dat je sleutel niet kan lezen: dan is er geen Location, en zegt applied_ref "draft": true zonder versienummer, of het id van een nieuwe agent of skill. Twee keer tegelijk toepassen schrijft één keer; de tweede krijgt 409.

Core weigert in deze volgorde en schrijft dan niets. Elke weigering is een conflict of een andere soort, en de zin in detail zegt welke:

Een wijziging die niets zou veranderen, zoals een tool die de agent al heeft of een skill die hij niet laadt, is 422. Daarna beslist de route van de agent, prompt of skill zoals altijd: 403 voor een naam die de regels van je sleutel niet noemen, 404 voor een doel dat weg is of buiten bereik, 409 voor een gekoppelde kopie, een naam die al bestaat of een SKILL.md met een andere naam dan de skill, en 422 voor een definitie die ze weigert.

Toepassen zonder beoordeling¶

Een analyse kan voorstellen zelf toepassen, zonder dat iemand ze leest, voor de soorten die je organisatie kiest. Wat dat per soort betekent staat in Inzicht. De keuze is apply_level in de instellingen: per kind propose (de standaard), draft (de analyse schrijft een concept dat een beheerder publiceert) of publish (ze schrijft het concept en publiceert het). GET /improvements/settings noemt elke soort en haar niveau. agent_version, prompt_version, agent_create, skill_rewrite en skill_create kennen alle drie; memory_shared_fact kent propose of publish; connector_request, skill_retire, evaluation_create, evaluation_scenarios en agent_trimmed alleen propose.

curl -s -X PATCH "$CORE_URL/improvements/settings" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"apply_level": {"agent_create": "draft", "skill_rewrite": "publish"}}'

Een soort die je niet noemt, houdt wat ze heeft. Een niveau dat een soort niet kent, of een naam die Core niet kent, is 422 op apply_level.<soort> en er verandert niets. Een agentversie die de hele instructies vervangt, publiceert een analyse nooit: bij publish wacht ze op jou, bij draft wordt ze als concept geschreven. Net als de rest van de instellingen vraagt dit management.

Wat een analyse doet. Na elke controle past ze elk open voorstel van een gekozen soort toe dat ze in die analyse schreef of ververste. Ze doet dat als de organisatie, zonder sleutel: met de capabilities van de organisatie en onder de hele policy van de organisatie en de organisaties erboven. Het is dezelfde toepassing als die van de route hierboven, met dezelfde weigeringen. Een voorstel dat accepted of dismissed is, past ze nooit toe.

Toegepast. Het voorstel is applied, met decided_by "auto" en in applied_ref wat er is gemaakt. Het auditspoor heeft een gebeurtenis improvements.proposal.applied met auto: true.

Geweigerd. Er is niets geschreven en het voorstel blijft open, met in auto_apply_refused waarom. Daarna beslist een persoon of een sleutel erover zoals over elk open voorstel; een volgende analyse die dezelfde bevinding vindt, probeert het opnieuw.

Een andere waarde is de soort weigering die de route van het doel gaf, zoals unprocessable_content, of refused als die route geen soort noemde. auto_apply_refused is null als geen analyse het voorstel probeerde, of zodra het is toegepast.

Tellen. Een analyse noemt per controle in checks ook auto_applied en auto_apply_refused: hoeveel voorstellen ze zelf toepaste en hoeveel ze open liet. Elke controle die draaide heeft ze, met 0 als geen soort gekozen is; bij failed, interrupted en skipped_no_tracing en bij analyses van voor deze functie ontbreken ze.

Terugdraaien. Toepassen overschrijft niets. Een nieuwe agentversie of promptversie draai je terug door de vorige versie vast te zetten waar die wordt gebruikt (Agents via de API, Prompts via de API); een nieuwe agent verwijder je. Een nieuwe skillversie is een concept, dat een beheerder weggooit; eenmaal gepubliceerd verandert ze geen agent zolang geen agentversie haar vastzet, en een verzoek dat de skill zelf noemt, zet je terug door de vorige versie te noemen, als naam@N.

Een skill geleerd uit sessies¶

Vindt episode_patterns een nieuwe les, dan schrijft de controle twee soorten voorstellen: een skill_create met de nieuwe skill, en een agent_version voor elke agent in wiens sessies de les naar voren kwam, met de nieuwe skill in add_skills. De agentversie heeft de skill nodig, dus pas eerst de skill_create toe; daarvoor antwoordt het toepassen van de agentversie 409 (not_applicable). Een geleerde skill komt uit wat mensen in hun sessies zeiden en wordt een instructie op de agents van hun collega's, en de controles van Core vangen namen, contactgegevens en ids, geen instructies. Dus ook als je beide soorten op publish zet in apply_level, past een analyse de nieuwe skill toe maar laat ze de agentversie voor jou open, tenzij je de skill zelf toepaste en hij gepubliceerd is. Ook bij draft wacht de agentversie op jou. Dekt een bestaande skill de les al, dan krijg je in plaats daarvan een skill_rewrite van die skill. Een geleerde skill gaat over het werk van je organisatie: een concept dat een persoon noemt, of een e-mailadres, telefoonnummer of link bevat, wordt nooit voorgesteld.

Analyses¶

De klok in de instellingen start analyses vanzelf. Start er een meteen met:

curl -s -X POST "$CORE_URL/improvements/analyses" -H "Authorization: Bearer $CORE_KEY"

Het antwoord is 202 met de analyse: status queued, trigger manual. Core weigert met 409:

• Improvement analyses are off for this organisation; turn them on in its settings.
• An analysis of this organisation is already queued or running.

GET /improvements/analyses geeft de analyses, de nieuwste eerst, met cursor gepagineerd. GET /improvements/analyses/{id} geeft er één, met de periode die ze werkelijk las en per controle in checks een outcome met de aantallen, waaronder auto_applied en auto_apply_refused (Toepassen zonder beoordeling). Een analyse is partial als minstens één controle niet alles kon lezen, en een cancelled analyse zegt in reason waarom ze niet draaide.

Naast outcome noemt een controle aantallen van wat ze deed en wat ze wegliet, elk een getal en afwezig als er geen is: bij leaner_agent queued, no_judge, no_cost_history, no_trial_key, trial_key_gone, trial_key_uncapped, budget_exhausted, trial_not_permitted, trial_limit, window_too_short, too_few_turns, all_tools_used, no_model_named, names_a_router, no_token_history, current_unpriced, no_cheaper_model, not_shorter, markers_lost, en per proef proposed, not_better, running, target_changed, run_failed en agent_deleted; bij de controles die tekst opstellen about_a_person, too_close_to_source, not_a_scenario, too_few_kept, too_few_read, too_few_agents, no_answer, no_draft, no_procedure, no_lesson en not_rewritable. Lees ze als namen, niet als een fout.

Een analyse schrijft alleen een voorstel dat je organisatie op dat moment zou kunnen toepassen: voordat ze er een schrijft, stelt Core dezelfde vragen als bij het toepassen, bijvoorbeeld of het beleid van je organisatie de naam van de agent toestaat en of de capability aanstaat, zonder iets te veranderen. Wat ze weglaat, telt ze per controle in not_permitted, per reden, bijvoorbeeld {"policy_denied": 2}. Bij het toepassen vraagt Core het opnieuw, dus een voorstel dat je beleid inmiddels niet meer toestaat, wordt dan alsnog geweigerd. Verandert je beleid terug, dan stelt de volgende analyse het opnieuw voor.

Skills, evaluaties en slankere agents¶

Vijf controles meer, alle uit tot je ze aanzet in checks:

Een scenario van evaluation_drafts valt af als het een plaatshouder, een contactgegeven of een id bevat, of als een stap te dicht bij het bericht zit waar hij vandaan komt; dat wordt geteld en nooit aan jou overgelaten om op te ruimen.

Proeven¶

leaner_agent probeert één wijziging van een agent, eerst minder tools, dan een goedkoper model, dan kortere instructies, als twee uitvoeringen van de eigen evaluatie van de agent: de gepubliceerde versie van de agent en een concept met de wijziging, over dezelfde scenario’s met hetzelfde beoordelingsmodel. De volgende analyse vergelijkt ze. Ze schrijft alleen een voorstel agent_trimmed als de score van de kandidaat minstens die van de basis is, geen stap die de basis haalde mislukte, en de kosten of de latentie minstens 10% lager zijn. Tot dan staat de proef open; per analyse starten hoogstens drie, per agent een tegelijk, en een agent wordt eenmaal per gepubliceerde versie geprobeerd. Er is geen route om een proef te lezen: je leest zijn uitkomst via het voorstel en zijn aantal in de analyse.

De proefsleutel. Proeven draaien als de sleutel die je noemt in trial_key_id, nooit als de eigen sleutel van de evaluatie. PATCH /improvements/settings neemt elke sleutel van je organisatie (422 op trial_key_id voor een andere) en null om er geen te noemen; het vraagt management naast improvements, omdat het bepaalt wiens geld proeven uitgeven. Zonder proefsleutel start er geen proef (no_trial_key), en een sleutel die inmiddels is verwijderd, uitgezet of verlopen start er ook geen (trial_key_gone).

Zijn maandplafond is het budget. Elke beurt van beide uitvoeringen en elke aanroep van het beoordelingsmodel wordt op de proefsleutel geboekt, dus monthly_cost_cap_eur van de sleutel begrenst de proeven, binnen het plafond van je organisatie zelf. Een sleutel zonder plafond start geen proef (trial_key_uncapped). Voordat een proef in de wachtrij komt schat Core twee keer wat de laatst afgeronde uitvoering van die evaluatie door die agent kostte, beoordeling inbegrepen; is dat meer dan de maand nog heeft, dan komt er niets in de wachtrij (budget_exhausted). Het beleid van de sleutel moet de agent en het kandidaatmodel bereiken; doet het dat niet, dan komt de proef niet in de wachtrij (trial_not_permitted).

Een proef gebruikt de echte tools van de agent. Een proefuitvoering roept dezelfde tools aan als een echt gesprek, dus een tool die verstuurt, schrijft of boekt, doet dat tijdens de proef echt, in beide uitvoeringen. Zet leaner_agent alleen aan voor agents van wie je het goed vindt dat hun tools worden aangeroepen.

Het voorstel. Een voorstel agent_trimmed noemt de wijziging en draagt in figures beide uitvoeringen (candidate en baseline, elk met run_id, score, mean_score, cost_eur en mean_latency_ms), monthly_saving_eur (null als het niet te schatten is), turns_per_month, scenarios, trial_id, draft_version en cannot_show: A trial shows one thing: on these … scenarios, graded by this judge, the leaner agent did not do worse. It cannot show how the agent behaves on topics the evaluation lacks, whether a tool needed once a quarter is still needed, whether the tone drifted in a way the judge does not check, or that the result would repeat: each side is one run. De console toont die zin in het Nederlands: Een proef laat één ding zien: op deze … scenario’s, beoordeeld door dit beoordelingsmodel, deed de slankere agent het niet slechter. Een proef laat niet zien hoe de agent zich gedraagt bij onderwerpen die de evaluatie mist, of een tool die één keer per kwartaal nodig is nog nodig is, of de toon is verschoven op een manier die het beoordelingsmodel niet controleert, of dat de uitkomst zich herhaalt: elke kant is één uitvoering. POST .../apply publiceert het concept dat is gemeten als nieuwste versie van de agent, dus elke aanroep zonder vastgezette versie draait het meteen; een concept dat iemand weggooide wordt opnieuw geschreven en gepubliceerd. Een analyse stelt het alleen voor: zijn apply_level is propose. De evidence van het voorstel is leeg, want het rust op uitvoeringen.

Een agent zonder evaluatie van minstens vijf scenario’s wordt niet geprobeerd, en geen aantal noemt hem; de voorstellen van evaluation_drafts stellen er een op.

Kosten en sporen¶

Elke modelaanroep van een analyse is een regel model_tokens in je verbruik, zonder sleutel, en elke analyse die begint één regel improvement_analysis. De uitvoeringen van een proef worden op de proefsleutel geboekt, zoals elke uitvoering van die sleutel. Wat Core naar het model stuurde staat als trace bij je organisatie, leesbaar met je sleutel of in de console. Het auditspoor houdt bij wie wat deed, met gebeurtenissen als improvements.settings.updated, improvements.proposal.updated en improvements.proposal.applied, zonder tekst.

Wil je niet steeds de lijst lezen, volg dan de events improvements.proposal.created en improvements.analysis.finished (Events volgen).

Beheerroutes¶

Elke route hier heeft een tweeling onder /tenants/{tenant_id}/improvements/... voor een beheerder die met de console is ingelogd, met dezelfde verzoeken en antwoorden. Een tweeling ziet elk voorstel van die organisatie, en de Location van een toepassing staat dan onder /tenants/{tenant_id}. Het analysemodel zet een beheerder met analysis_model op PATCH /tenants/{id}.