Een tool op de achtergrond draaien¶
Een toolaanroep blokkeert normaal de beurt: het model wacht op het antwoord voordat het verdergaat. Een taak is één toolaanroep die langer leeft dan de ronde die haar deed. Het model start de aanroep, krijgt meteen een taak-id en gaat door met het gesprek; Core voert de aanroep los daarvan uit en zet het resultaat in de thread zodra het er is. Gebruik het voor een aanroep die langer duurt dan een beurt hoort te wachten: een rapport dat minuten kost, een export, of een gespecialiseerde agent die een lange klus afwerkt.
Deze pagina beschrijft welke tools zo kunnen draaien, hoe je het toestaat, wat het model ziet, en de routes waarmee je applicatie taken leest en annuleert. Het concept achter tools staat in Tools.
Wat je nodig hebt¶
- De capability
tasks, aan in het plafond van de organisatie en op de sleutel. In de console is dat de schakelaar Een beurt een agent op de achtergrond laten starten en het resultaat lezen als die klaar is, bij Toegestane capabilities en op de sleutel. Ze vereistrunsenthreads. - Taken ingeschakeld voor de installatie. Dat bepaalt je operator. Staat het uit, dan
antwoorden de routes op deze pagina
404en krijgt geen beurt een taaktool aangeboden, wat de sleutel ook zegt. - De capability van de tool zelf:
toolingvoor een API-koppeling of een MCP-server,toolingencomputervoor een script,toolingmetgenerate_imageonder de systeemtools van de sleutel voor een afbeeldingstool,toolingmettranscribe_audioonder de systeemtools van de sleutel voor een transcriptietool,toolingmetcomputeronder de systeemtools van de sleutel en de capabilitycomputervoor een shelltool,agentsvoor een agent,workflowsvoor een workflow. - Een beurt die in een thread wordt bewaard. Een resultaat dat later komt, heeft een thread
nodig om in te landen. Een beurt met
store: false, of onder een sleutel zonderthreads, kan dus geen taak starten.
Welke tools als taak kunnen draaien¶
Acht soorten tools kun je op de achtergrond laten starten:
| Tool | Naam die het model ziet | Waar je het toestaat |
|---|---|---|
| Een agent die als tool wordt aangeboden | agent__<naam> |
op de agentversie |
| Een API-koppeling | api__<identifier> |
op de versie van de koppeling |
| Een tool van een MCP-server | mcp__<server>__<tool> |
op de registratie van de server, voor al zijn tools |
| Een script | script__<naam> |
op de scriptversie |
| Een SQL-koppeling | sql__<naam> |
op de versie van de koppeling |
| Een afbeeldingstool | builtin__generate_image__<model> |
voor de organisatie, via /tools/{name}/background |
| Een transcriptietool | builtin__transcribe_audio__<model> |
voor de organisatie, via /tools/{name}/background |
| Een shelltool | builtin__computer_exec, builtin__computer_write_file, builtin__computer_read_file |
voor de organisatie, één instelling per tool, via /tools/{name}/background |
| Een workflow | workflow__<naam> |
nergens: een workflow start altijd op de achtergrond |
Een hernoemde tool volgt de tool waar hij voor staat. Elke andere tool die Core levert, zoals zoek-, geheugen-, datastore- en mailtools, draait altijd binnen zijn beurt.
Een workflow heeft geen instelling. Hij draait alleen op de achtergrond: wie workflow__<naam>
rechtstreeks aanroept, start hem en krijgt een taak-id terug, zoals bij een tool op always, en een
beurt die geen taak kan vasthouden krijgt hem niet aangeboden. Hij kent geen max_seconds (de
eigen deadline van de run geldt) en geen retry_safe.
Een agent laten starten beschrijft hem.
Een tool die zich als persoon aanmeldt, wordt nooit op de achtergrond gestart. Een API-koppeling of een MCP-server waarvan de authenticatie de eigen login van de persoon is, draait altijd binnen zijn beurt, wat de instelling ook zegt. Je kunt de instelling wel opslaan; ze gaat gelden zodra de authenticatie een andere soort is.
Afbeeldingstools¶
Een afbeeldingstool heeft geen eigen versie of registratie, dus de organisatie zegt hoe hij mag draaien: één instelling per tool, bewaard voor de organisatie en gelezen door elke sleutel ervan. Ze heeft dezelfde drie velden als hieronder. Zonder instelling wacht een afbeeldingstool op zijn antwoord.
curl -s -X PUT "$CORE_URL/tools/builtin__generate_image__gpt-image-1/background" \
-H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
-d '{"mode": "allowed", "max_seconds": 300}'
GET op hetzelfde pad leest de instelling (never als er geen is), en DELETE, of een PUT met
"mode": "never", haalt haar weg. Wie de organisatie beheert, gebruikt
/tenants/{tenant_id}/tools/{name}/background. Alleen afbeeldingstools,
transcriptietools en de drie shelltools kennen een
instelling: elke andere tool antwoordt 422 met een zin die
zegt waar zijn eigen instelling staat. De console past
haar aan op de pagina Tools (In de console).
Een afbeeldingstaak tekent de afbeelding wanneer Core hem oppakt, onder het beleid van de sleutel
zoals het dan is, en leest referentieafbeeldingen met de toegang die de sleutel dan heeft. Als je
tussen de start en het oppakken het beleid aanscherpt of de instelling weghaalt, mislukt de taak en
wordt het afbeeldingsmodel nooit aangeroepen. retry_safe betekent bij een afbeeldingstool een
tweede aanroep van de afbeeldingsprovider als Core hem opnieuw moest sturen; laat het uit tenzij dat
acceptabel is. Core meet hoe dan ook één afbeelding, maar de provider kan de installatie voor beide
aanroepen rekenen.
Een sleutel die persoonsgegevens verbergt, start ook een afbeelding op de achtergrond, en de
afbeeldingsprovider leest dezelfde plaatshouders als in de beurt. Het model schrijft
<PERSON_1> in zijn prompt, de tool krijgt de echte naam, en Core zet de plaatshouder terug
voordat de prompt naar de provider gaat. Voor een taak bewaart Core de items van de
vertaaltabel die de prompt bevat, versleuteld bij de
taak, en de worker gebruikt ze om de namen weer te verbergen; ze worden verwijderd als de taak
eindigt. Kan Core ze bij het oppakken van de taak niet ontsleutelen, dan mislukt de taak met
pseudonymisation_failed en wordt de provider nooit aangeroepen. De eigen arguments van de taak
bevatten de echte waarden, net als de items van het gesprek: persoonsgegevens verbergen gaat over
wat een provider leest, niet over wat Core voor je organisatie bewaart.
Elk item van GET /tools en GET /tools/{name} heeft background, dat zegt wat nu geldt en waar
het is opgeslagen: mode, max_seconds, retry_safe, stored_on (connector_version,
script_version, mcp_server of organisation; null voor een tool die niet op de achtergrond
kan draaien) en reason (person_login als de eigen login van een persoon het never maakt).
Transcriptietools¶
Een transcriptietool neemt de instelling van de organisatie precies zoals een afbeeldingstool, één instelling per tool, zodat een lange opname wordt getranscribeerd terwijl het gesprek doorgaat (Audio transcriberen):
curl -s -X PUT "$CORE_URL/tools/builtin__transcribe_audio__whisper-large-v3/background" \
-H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
-d '{"mode": "allowed", "max_seconds": 600}'
De taak leest het bestand en transcribeert het wanneer Core haar oppakt, onder het beleid en de
toegang van de sleutel zoals die dan zijn; een beleid dat sinds de start is ingeperkt, laat de taak
mislukken voordat de opname wordt verstuurd. retry_safe betekent een tweede aanroep naar de
leverancier als Core haar opnieuw moest sturen, en die kan de leverancier in rekening brengen; Core
rekent de seconden hoe dan ook één keer af. Op een sleutel die persoonsgegevens verbergt, wordt de
prompt behandeld zoals de prompt van een afbeeldingstaak, hierboven. De opname zelf wordt nooit
verborgen (Persoonsgegevens verbergen voor het model), en het
transcript komt op de thread als onvertrouwd toolresultaat.
Shelltools¶
De drie shelltools nemen de instelling van de organisatie, zoals een afbeeldingstool, met één instelling per tool. Zo laat je een lang commando op de achtergrond draaien en houd je het schrijven en lezen van bestanden in de beurt:
curl -s -X PUT "$CORE_URL/tools/builtin__computer_exec/background" \
-H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
-d '{"mode": "allowed", "max_seconds": 1800}'
Een shelltaak draait op de computer van het gesprek. Ze ziet de bestanden die de beurt daar schreef, tenzij ze in de wachtrij stond tot die computer weg was, en wat ze schrijft blijft staan voor de beurten erna. Anders dan een scripttaak, die een eigen computer krijgt, is het de computer die de beurten van de thread delen:
- Hij blijft zolang de taak hem nodig heeft. De beurt die de taak startte, eindigt zonder de
computer weg te halen, en dat geldt voor elke beurt die eindigt voordat het resultaat van de taak
gelezen is: de wake die het resultaat beantwoordt, vindt hem. De
beurt die het resultaat leest, haalt hem weg als ze eindigt; zonder zo'n beurt haalt Core hem zo'n
tien minuten na de taak weg, hooguit vijftien, tenzij je operator die tijden veranderde. Een taak die startte
voordat de thread een computer had, maakt er een. Een tweede beurt die op de thread loopt terwijl
een andere de computer vasthoudt, krijgt een eigen computer, die ze niet deelt, en een beurt met
store: falsegebruikt de computer van het gesprek nooit. - Een thread verwijderen haalt hem weg, kort daarna, wat er ook op draait; net als het wissen van de persoon van wie de thread is.
- Eén commando tegelijk. Terwijl het commando van een taak loopt, wacht een shellaanroep die het
model in een beurt doet niet achter de taak: hij antwoordt meteen
The computer is busy with a background task., en het model kan de taak volgen metbuiltin__task_status. Een taak die een commando van een beurt bezig vindt, wacht tot dat klaar is. - De maximale levensduur blijft gelden. Een computer wordt weggehaald als hij de leeftijd
bereikt die je operator toestaat (een uur, tenzij die dat veranderde, of de kortere grens in de
capability
computervan de sleutel), ook als een taak hem gebruikt. Het commando van de taak mag draaien zolang er van zijnmax_secondsen van de leeftijd van de computer over is, in plaats van de twee minuten van een aanroep binnen een beurt; een commandogrens in de capabilitycomputervan de sleutel maakt dat nog korter. - De computer wordt gemeten zolang hij blijft staan, in
sandbox_secondsvanaf het moment dat hij werd gemaakt tot hij wordt weggehaald, op de sleutel wiens beurt hem maakte.
retry_safe betekent bij een shelltool dat het commando opnieuw draait nadat Core de aanroep
kwijtraakte, op dezelfde computer als die er nog is: zet het alleen aan als twee keer draaien geen
kwaad kan.
Een tool toestaan op de achtergrond te draaien¶
Een agent, een API-koppeling, een MCP-server en een script hebben elk een instelling background.
Zonder die instelling wacht elke aanroep op het antwoord.
| Veld | Betekenis |
|---|---|
mode |
never (de standaard): elke aanroep wacht op het antwoord. allowed: het model mag de tool op de achtergrond starten, naast het gewoon aanroepen. always: een directe aanroep start de tool op de achtergrond en geeft een taak-id terug, overal waar de beurt een taak kan vasthouden |
max_seconds |
hoe lang een taak met deze tool mag lopen, in seconden, minstens 1. Laat het weg voor de grens die je operator voor de installatie heeft gezet (een uur, tenzij die dat wijzigde). Je kunt die grens korter maken en nooit langer: een grotere waarde wordt erop afgekapt |
retry_safe |
alleen bij koppelingen, MCP-servers, scripts, afbeeldingstools, transcriptietools en shelltools: of Core de aanroep na een onderbreking opnieuw mag sturen. Standaard false, zie Als een aanroep wordt onderbroken |
Een agent heeft geen retry_safe: een agenttaak is een achtergrondrun, en die gaat verder vanaf
haar laatste afgeronde ronde.
Via de API¶
Stuur background mee als je een agent maakt of er een versie van publiceert (POST /agents,
POST /agents/{agent_id}/versions), als je een API-koppeling maakt of wijzigt
(POST /api_connectors, PATCH /api_connectors/{connector_id}) of een SQL-koppeling
(POST /sql_connectors, PATCH /sql_connectors/{connector_id}), als je een MCP-server
registreert of wijzigt (POST /mcp_servers, PATCH /mcp_servers/{server_id}) en als je een
script maakt of er een versie van schrijft (POST /scripts, POST /scripts/{script_id}/versions).
curl -s -X PATCH "$CORE_URL/api_connectors/tool_0KR7dX..." \
-H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
-d '{"background": {"mode": "allowed", "max_seconds": 900, "retry_safe": true}}'
Bij een koppeling hoort de instelling bij wat de koppeling doet, dus een wijziging legt een nieuwe
versie vast. Bij een PATCH zet "background": null haar terug op
never, en een body zonder het veld laat haar zoals ze is. Bij een script hoort ze bij de versie:
een versie zonder het veld is never, en een versie die alleen deze instelling wijzigt, is een
nieuwe versie.
In de console¶
De console heeft dezelfde instelling als de sectie Asynchrone tool, op een agent, een API-koppeling, een script en een MCP-server: zie Asynchrone tool. Het formulier van een script heeft dezelfde sectie, gevuld vanuit de laatste versie.
De instelling van elke tool lees je ook op één plek. Open Tools en kies Achtergrond onder het zoekvak: elke tool staat er als Kan niet, Toegestaan of Altijd, met de langste run en waar de instelling staat, en de kaarten in het overzicht dragen een label bij de tools die op de achtergrond mogen draaien. Een tool die niet kan, zegt waarom als een eigen aanmelding van een persoon de reden is. Dezelfde toestand, met dezelfde knop om aan te passen, staat op de eigen pagina van een tool en op de pagina Systeemtools.
De instelling blijft bij de tool, dus de knop hangt af van waar ze staat:
- Afbeeldingstools, transcriptietools en de shelltools: Aanpassen opent een venster. Kies je Nooit, dan verdwijnt de instelling van de organisatie.
- Een MCP-server: Aanpassen opent hetzelfde venster en bewaart de instelling op de server.
- Een API-koppeling of een script: de instelling hoort bij een versie. Nieuwe versie van de connector of Nieuwe versie van het script opent het formulier voor de volgende versie, en opslaan daar maakt er een.
- Een SQL-koppeling: ook hier hoort de instelling bij een versie. Nieuwe versie van de connector opent het formulier van de SQL-koppeling voor de volgende versie, en opslaan daar maakt er een.
- Een agent: ook hier hoort de instelling bij de versie van de agent. Naar de agent opent de pagina van de agent; pas je de agent daar aan en sla je op, dan ontstaat de volgende versie.
- Een workflow loopt altijd op de achtergrond en een bron die zich als persoon aanmeldt nooit; beide pas je niet aan. Een alias volgt zijn doel, dus pas de instelling aan op het doel.
- Een tool zonder instelling, zoals een zoektool uit Kennis of een datastoretool, wacht altijd op zijn antwoord. De lijst zegt Deze tool heeft geen instelling voor de achtergrond.
Schermafbeeldingen van de weergave Achtergrond en het venster volgen nog, en de schermafbeelding van het overzicht op Tools in de console is van voor de wisselknop en de achtergrondlabels.
Wat het model ziet¶
Kan een beurt een taak vasthouden en biedt ze minstens één tool aan die het
toestaat, dan voegt Core vijf tools aan die beurt toe. Je noemt ze niet in tools, geen toolset
bevat ze en ze staan niet in het Overzicht van
Tools.
| Tool | Argumenten | Antwoord |
|---|---|---|
builtin__task_start |
tool, arguments |
{"task_id": "...", "status": "queued"}, of één vaste zin als de start wordt geweigerd |
builtin__task_status |
task_id, of geen voor elke open taak van de thread |
status, tool, starttijd, deadline en, als de tool er een meldde, de laatste voortgangsregel |
builtin__task_result |
task_id, eventueel wait_seconds |
het resultaat als de taak is voltooid; haar status zolang ze loopt, en als ze is mislukt, geannuleerd of verlopen. wait_seconds wacht even tot de taak afloopt, hooguit zo lang als één toolaanroep mag duren |
builtin__task_cancel |
task_id |
de status na het annuleren |
builtin__task_send |
task_id, input |
alleen agenttaken: het bericht komt in de eigen thread van de agent, en de agent leest het voor zijn volgende ronde |
Het model kiest met de tool die het aanroept. api__rapport direct aanroepen is de gewone aanroep
die wacht. builtin__task_start aanroepen met {"tool": "api__rapport", "arguments": {...}} start
dezelfde aanroep als taak. Een tool die het toestaat, zegt dat in zijn beschrijving, zodat het model
weet dat het de keuze heeft. Een tool die op always staat, start ook bij een directe aanroep als
taak.
Het beleid van de sleutel beslist twee keer over een start: over de naam builtin__task_start, en
daarna over de tool die wordt gestart, op zijn eigen naam en labels. Een regel over Tools geldt
dus voor een tool, op welke manier hij ook wordt gestart.
Een start wordt met één vaste zin geweigerd als de thread of de organisatie aan haar grens zit (Grenzen), of als de genoemde tool er geen is die deze beurt aanbiedt met de achtergrond toegestaan. Die zinnen, en de zinnen onder Hoe een resultaat terugkomt, zijn van Core zelf en altijd Engels.
Een agenttaak is een achtergrondrun van die agent in een eigen thread, onder jouw sleutel
en voor dezelfde persoon. Een taak noemt beide als run_response_id en run_thread_id, en je volgt
hem zoals elke achtergrondrun.
Een taak van een API-koppeling, MCP-tool of script wordt opnieuw getoetst wanneer Core haar oppakt: is sinds de start de sleutel ingetrokken, de tool verwijderd, het beleid aangescherpt of de achtergrondinstelling ingetrokken, dan mislukt de taak met een code en wordt er niets aangeroepen.
Een scripttaak draait op een eigen computer, gemaakt wanneer Core de taak oppakt en verwijderd
zodra het script klaar is, nooit op de computer van het gesprek. De bestanden die de startende beurt
kreeg, worden gekopieerd naar /workspace/inputs/, zoals bij een script dat in een beurt draait.
Het script mag het grootste deel van de max_seconds van de taak lopen, binnen de maximale
levensduur van de computer, in plaats van de twee minuten die een aanroep binnen een beurt krijgt, tenzij je operator dat
veranderde;
de eigen timeout_seconds van een versie, en een commandogrens op de capability computer van de
sleutel, maken dat nog korter. De bestanden die het schrijft, komen
terug zoals hieronder staat.
Hoe een resultaat terugkomt¶
Als een taak afloopt, zet Core één item in de thread dat de taak en de tool noemt en zegt hoe ze afliep.
| De taak | Wat het model leest |
|---|---|
| is voltooid | Task <id> (<tool>) completed. Its result: gevolgd door het resultaat, afgekapt op 32 KiB |
| is mislukt | Task <id> (<tool>) failed. Bij een aanroep van een koppeling of MCP-tool gevolgd door wat een directe aanroep had geantwoord |
| is geannuleerd | Task <id> (<tool>) was cancelled. |
liep langer dan haar max_seconds |
Task <id> (<tool>) expired before it finished. |
| is onderbroken | Task <id> (<tool>) failed. gevolgd door Task was interrupted; it may or may not have completed. |
Een resultaat is informatie voor het model en nooit een instructie, zoals bij elk toolresultaat (Vertrouwen in toolresultaten). Hetzelfde geldt voor een voortgangsregel en voor alles wat een agenttaak zegt.
Bestanden komen terug als artefact. Een bestand of afbeelding die een koppeling, MCP-tool, script
of afbeeldingstool op de achtergrond antwoordt, wordt bewaard als artefact,
zoals na een directe aanroep, en het item met het resultaat verwijst ernaar: hoogstens tien per
aanroep, elk hoogstens 25 MiB, voor een sleutel met de capability artifacts. Een bestand boven die
grenzen, en elk bestand bij een sleutel zonder artifacts, wordt weggelaten en het resultaat zegt
dat. Wat een agenttaak maakte, blijft in de eigen thread van die agent.
Draait de beurt die de taak startte nog, dan komt het resultaat in haar volgende ronde.
Is die beurt al afgelopen, dan start Core één beurt in dezelfde thread om het resultaat te beantwoorden: een wake. Dat is een achtergrondrun onder dezelfde sleutel en voor dezelfde persoon, met de tools die de startende beurt had en zonder nieuwe invoer. Je applicatie merkt het zoals elke achtergrondrun: door de thread te lezen of via events. Een wake volgt alleen op een beurt die is voltooid. Een wake die zelf een taak start, wordt ook voor dat resultaat gewekt, tot een grens die je operator zet (drie op rij, tenzij die dat wijzigde); daarna komt het resultaat in de thread en start er niets.
Wil je resultaten in de thread laten staan voor je eigen volgende beurt, stuur dan
"task_wake": false mee op POST /responses, of zet wake op false in de capability tasks
van de sleutel om het voor elke beurt van die sleutel af te slaan.
Core kondigt elke taak aan als event: thread.task.started, thread.task.completed,
thread.task.failed, thread.task.cancelled en thread.task.expired. Elke start wordt gemeten als
één task_start (Gebruik en audit via de API). Een tool op de
achtergrond kost wat een directe aanroep kost: elke keer dat een koppeling, MCP-tool of script
voor een taak draait, wordt dat gemeten als één tool_invocation onder de eigen naam van de tool,
ook maar één keer als Core de aanroep opnieuw moest sturen. De computer van een script wordt
gemeten in sandbox_seconds, zoals bij een directe aanroep, en de computer van het gesprek zolang
een shelltaak hem laat staan. Een transcriptietaak rekent haar seconden audio één
keer af, als één rij audio_transcription.
Op de hoogte blijven als een taak eindigt¶
Een organisatie kan vragen om bericht als een taak eindigt. Zet Taak afgerond aan onder Soorten meldingen (Meldingen): één mail of Slack-bericht per taak die klaar is, mislukt of verlopen, met de naam van de tool en de taak, nooit met het resultaat.
Als een aanroep wordt onderbroken¶
Core kan een aanroep kwijtraken terwijl ze uitstaat, bijvoorbeeld bij een herstart. Core kan dan niet weten of je endpoint de aanroep heeft uitgevoerd.
- Staat
retry_safeuit, dan eindigt de taakfailedmet de codeinterrupted, en het model leestTask was interrupted; it may or may not have completed. - Staat
retry_safeaan, dan stuurt Core dezelfde aanroep opnieuw, met dezelfde headerIdempotency-Keyals de eerste keer. Na herhaalde onderbrekingen eindigt de taak alsnog als onderbroken.
Zet retry_safe alleen aan als je endpoint een herhaling met dezelfde Idempotency-Key behandelt
als de aanroep die het al afhandelde. Voor een script betekent een herhaling dat het opnieuw vanaf het begin draait, op een nieuwe
computer: zet retry_safe aan als twee keer draaien geen kwaad kan. Een agenttaak heeft zo'n
belofte niet nodig: ze gaat verder vanaf haar laatste afgeronde ronde.
Grenzen¶
Je operator stelt deze in voor de installatie. De getallen zijn de waarden die een installatie heeft tenzij de operator ze wijzigde.
| Grens | Waarde | Daarboven |
|---|---|---|
| Hoe lang één taak mag lopen | 3600 seconden; per tool korter met max_seconds |
de taak eindigt expired |
| Open taken in één thread | 8; een sleutel kan dat verlagen met max_open_per_thread in haar capability tasks |
de start wordt geweigerd: This conversation has too many open tasks. |
| Open taken in de organisatie | 1000 | de start wordt geweigerd: Too many tasks are running; try again later. |
| Wakes op rij | 3 | het resultaat komt in de thread, er start niets |
| Taken die door een taak worden gestart | geen: een agent die als taak draait, krijgt geen taaktools aangeboden | — |
Een open taak is een taak die queued of running is.
MCP-servers met eigen taken¶
Een MCP-server kan aangeven dat hij een tool zelf als taak uitvoert en met een verwijzing antwoordt (MCP-revisie 2025-11-25). Core legt vast wat elke tool aangeeft wanneer hij de server leest. Wordt zo'n tool als taak gestart, dan vraagt Core de server hem als eigen taak van de server uit te voeren en kijkt daarna met tussenpozen hoe het ermee staat, in plaats van een verbinding open te houden: met de tussenpoos die de server noemt, binnen grenzen die je operator zet.
- Voortgang. Het statusbericht van de server wordt de
progressvan de taak: één regel, hooguit 200 tekens. Een server die voortgangsmeldingen stuurt tijdens een aanroep die Core voor een taak openhoudt, vult hetzelfde veld. - Een server die om invoer vraagt, laat de taak mislukken. Een taak heeft niemand om het aan te
vragen, dus
input_requiredbeëindigt de taak alsfailedmet de codeinput_required. - Annuleren en verlopen worden aan de server gemeld. Core stuurt de server één keer een annulering. De status van de taak wacht niet op het antwoord van de server.
Drie dingen om te weten als je zo'n server registreert:
- Een thread verwijderen stopt de taak van de server niet. De taak verdwijnt met haar thread, en de eigen taak van de server loopt door tot de deadline die Core haar bij de start gaf.
- Bestanden en afbeeldingen in het antwoord van de server worden weggelaten: anders dan bij een aanroep die Core zelf vasthoudt, bewaart een resultaat dat Core bij de eigen taak van de server ophaalt ze niet.
- Een tool die taken als
requiredaangeeft, heeft de modusalwaysnodig. Core stuurt een aanroep alleen als taak van de server wanneer de aanroep zelf als taak wordt gestart. Een directe aanroep binnen een beurt is een gewone aanroep, en die accepteert zo'n tool niet. Zet de server op Altijd, zodat elke aanroep als taak start.
Taken lezen en annuleren vanuit je applicatie¶
Wie een thread mag lezen, mag haar taken lezen. De voorbeelden gebruiken verzonnen id's.
De taken van een thread opvragen¶
curl -s "$CORE_URL/threads/thr_0KQ9aB.../tasks?limit=20" -H "Authorization: Bearer $CORE_KEY"
{
"items": [
{
"object": "task",
"id": "task_0KR8mT...",
"thread_id": "thr_0KQ9aB...",
"response_id": "resp_0KQ2mR...",
"call_round": 0,
"call_id": "call_1",
"call_id_sha256": null,
"tool": "api__rapport",
"tool_version": 3,
"arguments": { "klant": "acme", "jaar": 2025 },
"status": "running",
"created_at": "2026-03-02T09:14:07Z",
"deadline_at": "2026-03-02T09:29:07Z",
"ended_at": null,
"progress": null,
"result": null,
"error_code": null,
"run_response_id": null,
"run_thread_id": null,
"depth": 1,
"result_position": null,
"delivered_response_id": null
}
],
"next_cursor": null
}
Geef next_cursor mee als cursor voor de volgende pagina.
Eén taak lezen¶
curl -s "$CORE_URL/tasks/task_0KR8mT..." -H "Authorization: Bearer $CORE_KEY"
Het antwoord is één taakobject zoals hierboven. Als de taak is afgelopen (overige velden als hierboven):
{
"object": "task",
"id": "task_0KR8mT...",
"status": "completed",
"ended_at": "2026-03-02T09:21:40Z",
"result": "{\"rapport_url\": \"https://your-app.example/rapporten/acme-2025\"}",
"error_code": null,
"result_position": 14,
"delivered_response_id": "resp_0KQ4pV..."
}
| Veld | Betekenis |
|---|---|
status |
queued, running, completed, failed, cancelled of expired |
result |
wat de taak antwoordde, afgekapt op 32 KiB; null tot ze afliep, en bij een taak die verliep of werd geannuleerd |
error_code |
waarom een taak mislukte, zoals interrupted, key_revoked, tool_unavailable, background_withdrawn, pseudonymisation_failed, cost_limit of input_required; anders null |
response_id, call_round, call_id |
het antwoord en de toolaanroep die de taak startten, zoals ze in de trace staan. Een heel lange call_id is null, en call_id_sha256 bevat dan de SHA-256 ervan |
result_position |
de positie in de thread van het item met het resultaat; tot dan null |
delivered_response_id |
het antwoord waarvan de beurt het resultaat als eerste las; null zolang geen beurt dat deed |
run_response_id, run_thread_id |
bij een agenttaak het antwoord van de achtergrondrun waarin ze draait, en de thread van die run |
labels |
de labels van de beurt die de taak startte, gekopieerd bij de start; geen regel leest ze |
Een taak annuleren¶
curl -s -X POST "$CORE_URL/tasks/task_0KR8mT.../cancel" -H "Authorization: Bearer $CORE_KEY"
{ "object": "task", "id": "task_0KR8mT...", "status": "cancelled", "ended_at": "2026-03-02T09:16:02Z" }
Core antwoordt 200 met de taak (hier ingekort). Een taak annuleren die al geannuleerd is, geeft
hetzelfde antwoord; een taak die op een andere manier afliep, geeft 409. Een aanroep die uitstaat
als je annuleert, wordt kort daarna gestopt.
Een bericht sturen naar een agenttaak¶
curl -s -X POST "$CORE_URL/tasks/task_0KR9cW.../messages" \
-H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
-d '{"input": "Laat de facturen van voor 2024 weg."}'
{ "object": "task", "id": "task_0KR9cW...", "tool": "agent__facturatie", "status": "running" }
Core antwoordt 200 met de taak (hier ingekort). Het bericht komt in de eigen thread van de agent,
en de agent leest het voor zijn volgende ronde. input bevat 1 tot 64.000 tekens. Een taak die is
afgelopen, en elke taak die geen agenttaak is, geven 409.
Annuleren en een bericht sturen veranderen het werk, en horen daarom bij de persoon voor wie de taak is gestart. In een thread die meerdere mensen gebruiken, kan het verzoek van een ander de taak wel lezen, maar niet annuleren en er geen bericht naar sturen.
Elke route antwoordt 404 als tasks niet aanstaat voor de sleutel of de installatie, en voor een
taak of thread die de sleutel niet bereikt.
Zie ook¶
- Een trace lezen: hoe een tool op de achtergrond in een gesprek wordt getekend, van de start tot de beurt die het resultaat las.
- Een beurt op de achtergrond draaien: de hele beurt op de achtergrond, en dat is iets anders dan één toolaanroep van een beurt.
- Een agent als tool aan een beurt geven.