B Blengi docs

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

ToolVereiste capaciteitAutomatisch ingeschakeld opWat 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:

  1. Bouw de OpenAI-achtige tools-array op basis van het forAgent($agent)-resultaat uit het register.
  2. Roep llm->chatWithTools(messages, tools) niet-streaming aan. Het model geeft ofwel tool_calls terug (het wil een of meer tools aanroepen) ofwel content (het is klaar om te antwoorden).
  3. Als tool_calls: stuur dan een tool_call SSE- gebeurtenis voor elke aanroep, voer de execute() van de tool uit, voeg het resultaat van de tool toe aan de berichtgeschiedenis als een {role: 'tool'}-bericht, en herhaal de lus.
  4. Zodra het model content teruggeeft (of na 3 hops, wat het eerst komt), ga je verder via het bestaande streamChat-pad. De bezoeker krijgt nog steeds token-voor-token-streaming voor het uiteindelijke antwoord, dus TTFT blijft behouden.
  5. Alle block-payloads die de tools hebben geproduceerd (bijv. escalation_button) worden uitgezonden als block SSE-gebeurtenissen, zodat de widget ze inline kan weergeven.

Compatibiliteit van providers

ProviderTool-aanroepOpmerkingen
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:

  1. de bundel een renderer voor die functionaliteit bevat, EN
  2. 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

  1. Implementeer App\Services\Tools\Contracts\Tool in app/Services/Tools/Tools/YourTool.php. Kies een unieke name(), schrijf een duidelijke description() (de LLM gebruikt deze om te bepalen wanneer hij moet worden aangeroepen), declareer de capability()-slug die nodig is, en definieer de schema()-JSON.
  2. Registreer de tool in ToolRegistry::__construct.
  3. Als de execute() van je tool een block payload teruggeeft, lever dan een renderer daarvoor in ui/blocks.tsx en voeg de relevante capability-slug toe aan de RENDERABLE -set in capabilities.ts .
  4. 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.