Je AI-medewerker bouwen
Tools & uitgebreide berichten
Tools zijn hulpprogramma’s aan de serverkant die je agent tijdens een beurt kan aanroepen. De bezoeker typt iets in, de LLM besluit: „Ik moet hiervoor een tool hiervoor aanroepen", de tool draait op de server en het resultaat wordt ofwel teruggekoppeld naar het uiteindelijke antwoord van de LLM, ofwel direct in de widget weergegeven als een gestructureerd blok (bijv. een knop "Verbind me met een medewerker").
Tools worden beperkt door de verticale mogelijkheden van de agent.
Elke tool geeft aan welke mogelijkheid hij nodig heeft; het register maakt een tool alleen
beschikbaar voor agenten waarvan de lijst met mogelijkheden die slug bevat.
Beheerders kunnen de lijst verder beperken met vertical_overrides.enabled_tools.
Tools uitrollen
| Tool | Vereiste capaciteit | Automatisch ingeschakeld op | Wat het doet |
|---|---|---|---|
escalate_to_human |
ticket_escalation |
Elke branche (functie is standaard ingeschakeld bij elke preset) | Toont een knop 'Breng me in contact met een medewerker' (bloktype escalation_button). Als je erop klikt, wordt de bestaande lead-capture-flow geactiveerd, zodat een medewerker het gesprek kan overnemen. Argumenten: reason. |
lookup_order |
order_status |
e-commerce | Roep het WooCommerce REST-eindpunt van de werkruimte aan via LookupOrderClient en haal de recente bestellingen van de bezoeker op (status + artikelen + tracking). Time-out van precies 5 seconden. Vereist een ingelogde klant (JWT-claim via shopper.wp_user_id) en een woocommerce_products-bron die aan de medewerker is gekoppeld — werkt soepel als een van beide ontbreekt. Argumenten: limit (standaard 5, max. 10), optioneel status. |
open_ticket |
ticketing |
help_center (functie automatisch inbegrepen) | Opent een blijvend supportticket vanuit het gesprek — factureringsgeschillen, accountproblemen, bugrapporten. Wordt opgeslagen in de tickets-tabel die gekoppeld is aan het bron-gesprek. Argumenten: subject (≤ 120 tekens), body, optioneel priority (laag / normaal / hoog / urgent). |
send_kb_article |
kb_article_card |
help_center | Toont een kaartje met een link naar een gepubliceerd artikel uit de Knowledge Base. Zoekt de slug op in de geselecteerde antwoorden van de werkruimte; de bezoeker ziet een kaartje met titel + fragment + doorkliklink. Argumenten: slug. |
Toolgating is het snijpunt van (a) de verticale mogelijkheden van de agent,
(b) de vereiste mogelijkheden van elke tool, en (c) de allowlist van de beheerder
vertical_overrides.enabled_tools
. Elke tool waarvan
de vereiste capaciteit niet in de set van de agent zit, wordt stilletjes genegeerd voordat
de LLM deze ziet.
Hoe het hot path toolaanroepen afhandelt
Voor elke bezoeker die een tool-enabled agent activeert, voert
MessageStreamController
een kleine tool-resolutielus uit
voordat
het definitieve antwoord wordt gestreamd:
-
Bouw de OpenAI-achtige
tools-array op basis van hetforAgent($agent)-resultaat uit het register. -
Roep
llm->chatWithTools(messages, tools)niet-streaming aan. Het model geeft ofweltool_callsterug (het wil een of meer tools aanroepen) ofwelcontent(het is klaar om te antwoorden). -
Als
tool_calls: stuur dan eentool_callSSE- gebeurtenis voor elke aanroep, voer deexecute()van de tool uit, voeg het resultaat van de tool toe aan de berichtgeschiedenis als een{role: 'tool'}-bericht, en herhaal de lus. -
Zodra het model
contentteruggeeft (of na 3 hops, wat het eerst komt), ga je verder via het bestaandestreamChat-pad. De bezoeker krijgt nog steeds token-voor-token-streaming voor het uiteindelijke antwoord, dus TTFT blijft behouden. -
Alle
block-payloads die de tools hebben geproduceerd (bijv.escalation_button) worden uitgezonden alsblockSSE-gebeurtenissen, zodat de widget ze inline kan weergeven.
Compatibiliteit van providers
| Provider | Tool-aanroep | Opmerkingen |
|---|---|---|
| OpenAI (gpt-4o-mini, gpt-4o) | Inbouw | Volledige ondersteuning voor OpenAI-tools-arrays via de SDK. |
| OpenRouter | Afhankelijk van het model | Modellen die met tools kunnen werken (Claude 3.5, Llama 3.3 70B Hermes, enz.) werken via dezelfde OpenAI-compatibele interface. |
| Cloudflare Workers AI | Afhankelijk van het model | Llama 3.3 70B Hermes en een handvol andere modellen ondersteunen het aanroepen van functies. Modellen zonder tool-ondersteuning schakelen soepel over naar een lagere prestatieniveau — ze negeren de tools-array en geven direct inhoud terug, waardoor de lus gewoon wordt afgesloten. |
Weergave van blokken in de widget
De widget ontvangt block SSE-gebeurtenissen tijdens een beurt en
voegt elk blok toe aan het lopende assistentbericht. Het
rendererregister in resources/widget/src/ui/blocks.tsx
koppelt blok type aan een Preact-component. Onbekende bloktypes
worden stilletjes genegeerd (voorwaarts compatibel voor nieuwere servers).
De helper canRender(capability, agent) van de widget geeft nu
true terug wanneer:
- de bundel een renderer voor die functionaliteit bevat, EN
-
de door de server opgeloste
capabilities-array van de agent hiervoor is aangemeld.
Beide zijn vereist — de widget schakelt nooit een functie in die de server niet heeft geautoriseerd, en probeert nooit een blok weer te geven waarvan de renderer niet in de bundel zit.
Een nieuwe tool toevoegen
-
Implementeer
App\Services\Tools\Contracts\Toolinapp/Services/Tools/Tools/YourTool.php. Kies een uniekename(), schrijf een duidelijkedescription()(de LLM gebruikt deze om te bepalen wanneer hij moet worden aangeroepen), declareer decapability()-slug die nodig is, en definieer deschema()-JSON. -
Registreer de tool in
ToolRegistry::__construct. -
Als de
execute()van je tool eenblockpayload teruggeeft, lever dan een renderer daarvoor inui/blocks.tsxen voeg de relevante capability-slug toe aan deRENDERABLE-set incapabilities.ts. -
Voeg een Pest-unit-test toe voor de tool en een feature-test voor de
end-to-end-stroom met behulp van
FakeOpenAi::pushToolCall.
Overwegingen met betrekking tot latentie
De tool-loop voegt één niet-streaming round-trip per hop toe voordat het streaming eindantwoord begint. Voor een typische beurt waarbij „één tool nodig is“ betekent dat ongeveer +200–500 ms latentie voordat de bezoeker het eerste token te zien krijgt. Het 99%-scenario (geen tools gebruikt) blijft ongewijzigd, omdat het register een lege tool-lijst teruggeeft voor agents waarvan de mogelijkheden niet overeenkomen met een geregistreerde tool.
Om de vertraging beheersbaar te houden, schrijf je toolbeschrijvingen zo beknopt mogelijk, zodat de LLM alleen een tool aanroept als die echt nodig is. De hop-limiet (3) is een vangnet — goed geschreven toolbeschrijvingen zouden binnen 1 hop moeten convergeren.