De toolrouter¶

Met de toolrouter kan een beurt veel meer tools bereiken dan een model in één aanroep accepteert. Het model krijgt dan niet al je tools in zijn lijst, maar twee tools van Core: een om tools op betekenis te zoeken en een om een gevonden tool uit te voeren. Alles achter die twee blijft zoals het bij een directe aanroep is: policy, budgetten, toegestane hosts, verbruik en traces gelden per echte tool.

Waarom een router¶

Elke tool die je een model aanbiedt, gaat met zijn naam, beschrijving en parameterschema mee in elke aanroep. Dat heeft twee gevolgen:

• Een model heeft een grens. Een leverancier weigert een aanroep met meer tools dan zijn model aankan, en Core houdt je daarom aan de grens van het model (Hoeveel tools een model aankan).
• Veel tools kosten context en keuzes. Een lange lijst kost tokens voordat het model je invoer leest, en na enkele tientallen tools kiest een model minder goed.

Een agent die bij honderden tools moet kunnen, zoals een agent over de hele API van Core of over een grote MCP-server, zet je daarom achter de router. Een agent met een handvol tools heeft er niets aan: hij doet dan een extra ronde om te zoeken wat hij direct had kunnen zien.

Wat het model ziet¶

In de modus router krijgt het model twee tools in plaats van de tools van de beurt:

Een zoekopdracht geeft zoveel tools terug als het model met top_k vraagt. Noemt het model er geen, dan geldt de top_k van het verzoek, de agent of de sleutel (standaard 5, van 1 tot 20). Hoe dan ook stopt het antwoord voordat het groter wordt dan budget_tokens (standaard 4.000). Een uitvoering controleert eerst of de naam bij deze beurt hoort en of de argumenten bij het schema van de tool passen. Is dat niet zo, dan krijgt het model een toolresultaat met een zin waar het iets mee kan: dat er geen tool met die naam beschikbaar is en het er een moet zoeken, of welk argument welke regel breekt. In de volgende ronde kan het de aanroep verbeteren. In de trace draagt die toolaanroep de error_code unknown_tool of invalid_arguments. Een naam die het model al kent, mag het zonder zoekopdracht uitvoeren.

Een paar tools blijven direct in de lijst, ook in de modus router:

• de tools die Core zelf toevoegt zonder dat je erom vraagt: het laden van een skill (builtin__load_skill), de taaktools en het zoeken in je geüploade bestanden (knowledge__uploads);
• je eigen custom tools (vrije tekst met een grammatica), omdat die alleen werken voor een tool die het model in zijn lijst heeft;
• de tool die je met tool_choice afdwingt.

Je eigen functietools gaan wél achter de router. Vindt en voert het model er een uit, dan krijg je dezelfde function_call (op /messages: tool_use) als bij een directe aanroep, onder de eigen naam van de tool, en beantwoord je die zoals altijd.

Een beurt die niets achter de router zet, krijgt geen van beide tools. Een gesprek kan van modus wisselen tussen twee beurten: Core toont een eerdere uitvoering aan een beurt in de modus direct als een gewone aanroep van de tool.

Policy beslist zoals bij een directe aanroep¶

De router laat het model niets bereiken wat de beurt zonder router niet had mogen gebruiken:

• Voordat het model iets ziet. Een tool die de policy van de sleutel weigert of waarvoor een capability ontbreekt, valt uit de beurt voordat de router hem kent. Een zoekopdracht kan zo'n tool niet vinden, niet rangschikken en niet tellen.
• Bij elke uitvoering. Een uitvoering wordt beslist op de echte naam, met de labels van de tool en de persoon, en daarna uitgevoerd met de time-out, toegestane hosts, opgeslagen credentials en budgetten van die tool. Een weigering is dezelfde denied_by_policy als bij een directe aanroep.
• Een onbekende naam zegt niets. Een naam die niet bestaat, een naam die de policy weigerde en een naam waarvoor een capability ontbreekt krijgen hetzelfde antwoord, dus een uitvoering is geen manier om te ontdekken welke tools er zijn.

De twee routertools zijn zelf geen onderwerp van policy: een regel over builtin__tool_* heeft geen effect, omdat de beslissing altijd op de echte tool valt.

Een tool uit een verzegelde publicatie kan in de zoekresultaten staan, met de naam, beschrijving en parameters die de uitgever zichtbaar laat. Zo'n resultaat is als verzegeld gemarkeerd, zodat het gesprek het later niet terugtoont (Publiceren en installeren via de API).

Wat wordt vastgelegd en gefactureerd¶

Zoekopdrachten tellen mee voor het maandplafond van je organisatie. Is dat plafond bereikt, of heeft je organisatie geen embeddingmodel dat de sleutel mag gebruiken, dan rangschikt een zoekopdracht alleen op trefwoorden. In de trace staat dat bij de zoekopdracht.

Core houdt de beschrijvingen van je tools klaar om op te zoeken, maar niet voor elke soort tool op dezelfde manier. API-koppelingen, aliassen, scripts en de tools van een MCP-server worden op de achtergrond voorbereid zodra je ze toevoegt of wijzigt, en alles wordt voorbereid zodra tool search voor de organisatie wordt aangezet. De eigen tools van Core (core__ en builtin__), datastore-, kennis- en geheugentools, het zoeken in je uploads en alle tools van een nieuwe organisatie krijgen geen eigen achtergrondrun: ze worden voorbereid bij de volgende achtergrondrun die een van die wijzigingen start, of als een zoekopdracht ze nodig heeft. Elke zoekopdracht embedt hoogstens 64 ontbrekende beschrijvingen zelf, gefactureerd zoals de zoekvraag, en vindt de rest op trefwoord. Tot een van beide is gebeurd, wordt zo'n tool nooit vooraf gekozen.

Hoeveel tools een model aankan¶

Elk model heeft een grens voor het aantal tools in één aanroep. GET /models geeft die als max_tools, en de console toont hem in de kolom Max. tools van de modellenlijst. Core zelf biedt hoogstens 128 tools per beurt aan, en zonder eigen opgave geldt die 128 ook voor een model. Biedt een beurt meer tools aan, dan weigert Core het verzoek voordat er een model wordt aangeroepen: 422 op tools, en 400 in de vorm van de leverancier op /responses en /messages. Ligt de grens van het model lager dan 128, dan noemt de melding het model en zijn grens, zoals "This request offers more than 64 tools; model 'M' accepts at most 64."; anders luidt hij "This request offers more tools than a turn may carry." Kan een beurt via fallback of een modelrouter op meerdere modellen uitkomen, dan telt de kleinste grens.

Core zet de router nooit zelf aan omdat een beurt te veel tools heeft. Jij kiest hem, en dan tellen alleen je eigen custom tools en de twee routertools mee voor de grens van het model. Alles achter de router telt voor een eigen grens, ook je functietools en de agents die een beurt als tool aanbiedt. Achter de router passen per beurt hoogstens 2.048 tools; daarboven antwoordt Core 422 op tools.

Tools vooraf kiezen¶

Een sleutel kan een beurt in de modus router laten beginnen met de tools die het best bij het bericht passen, al gevonden. Het model krijgt die tools dan als het resultaat van een zoekopdracht aan het begin van de beurt en voert ze uit met builtin__tool_run, zonder eerst zelf te zoeken. Andere tools kan het nog steeds zoeken.

• Het staat standaard uit en is een instelling van de sleutel alleen; een agentversie of verzoek kan het niet aan- of uitzetten.
• Het kiest alleen uit de tools die de beurt achter de router heeft, met dezelfde policy. Een tool waarvan Core de beschrijving nog niet klaar heeft, wordt niet vooraf gekozen maar is wel te zoeken.
• Het gebruikt de ene embedding van het bericht die de beurt ook voor geheugen en skills maakt, en telt niet als zoekopdracht in je verbruik.
• Het verandert de lijst van het model niet. Die blijft het hele gesprek gelijk, zodat de cache van de leverancier blijft werken.

Waar je hem aanzet¶

De router wordt gekozen per beurt, nooit per tool. Elke tool kan direct of via de router worden aangeboden, en je markeert niets op een tool of een toolset.

Een beurt kiest zijn modus in deze volgorde: het verzoek, dan de agentversie, dan default_mode van de sleutel. Noemt een verzoek of agent router terwijl de sleutel of de organisatie dat niet toestaat, dan weigert Core het verzoek met tool_search.mode en "Tool search is not enabled for this key." Een default_mode van router op de sleutel onder een organisatie die het niet toestaat, wordt stil direct. Een agent die als tool in een andere beurt draait, volgt zijn eigen modus, niet die van de beurt die hem aanroept.

Een MCP-client buiten Core kiest de router met ?tool_search=router op het adres, met dezelfde voorwaarden (Core gebruiken vanuit een MCP-client).

Lees verder¶