Ga naar inhoud

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 vereist runs en threads.
  • Taken ingeschakeld voor de installatie. Dat bepaalt je operator. Staat het uit, dan antwoorden de routes op deze pagina 404 en krijgt geen beurt een taaktool aangeboden, wat de sleutel ook zegt.
  • De capability van de tool zelf: tooling voor een API-koppeling of een MCP-server, tooling en computer voor een script, tooling met generate_image onder de systeemtools van de sleutel voor een afbeeldingstool, tooling met transcribe_audio onder de systeemtools van de sleutel voor een transcriptietool, tooling met computer onder de systeemtools van de sleutel en de capability computer voor een shelltool, agents voor een agent, workflows voor 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 zonder threads, 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: false gebruikt 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 met builtin__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 computer van de sleutel), ook als een taak hem gebruikt. Het commando van de taak mag draaien zolang er van zijn max_seconds en van de leeftijd van de computer over is, in plaats van de twee minuten van een aanroep binnen een beurt; een commandogrens in de capability computer van de sleutel maakt dat nog korter.
  • De computer wordt gemeten zolang hij blijft staan, in sandbox_seconds vanaf 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_safe uit, dan eindigt de taak failed met de code interrupted, en het model leest Task was interrupted; it may or may not have completed.
  • Staat retry_safe aan, dan stuurt Core dezelfde aanroep opnieuw, met dezelfde header Idempotency-Key als 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 progress van 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_required beëindigt de taak als failed met de code input_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 required aangeeft, heeft de modus always nodig. 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