Website Tools

Overview

Let your chatbot's AI agent call functions that run on your own website, from a public site search to actions for a signed-in user.

Website tools (host-run tools) let the AI agent in the Sarufi web widget call JavaScript functions on your page. The function runs in the visitor's browser, so the agent can search your site, or answer "what is my balance?" through your own API, without you opening a new API to Sarufi. Over the Developer API the same tools are calls your server answers.

A tool has a definition (its name, what it does, and the JSON Schema of its arguments) and a handler (the code that runs). The definition is what the model reads; the handler is yours.

Three paths

Start with the simplest one that fits.

You wantPathDefinitions come fromBackend or token needed
Public features anyone can use: search, store hours, stockPublic site toolsA tool set in your workspace, linked to the botNo
Features for a signed-in user: balance, orders, paymentsSigned-in usersA tool set, with "Needs signed-in user" onYes: a host token per user
Definitions kept next to your code, shipped with your releaseTools declared in page codeChatWidget.tool() on the pageYes: a host token that also signs the tools

In every path the page only runs tools. What the model is told about a tool comes from you, never from unsigned page code.

Read the safety rules before going live

A tool call is a request your page makes on the visitor's behalf, with arguments chosen by a model. Safety lists what your server must still check.

Public site tools

The whole setup for a public site search, with no backend and no token.

1. Create a tool set and connect it. In the dashboard, open your bot's Integrations, then Website tools, Create tool set. Add a tool:

  • name search_site;
  • what it does: "Search this website's pages and products.";
  • one text input, query, required;
  • Status while running: "Searching the site" (optional; see the status line);
  • leave "Needs signed-in user" off.

Save. A tool set made from a bot's page is connected to that bot automatically. To manage tool sets through the API instead, see Tool sets and limits.

2. Register the handler after the widget loads. ChatWidget is defined by the embed snippet of your web integration, so your code must run after that script has loaded:

<script src="https://your-deployment.example.com/widget.js" data-widget-key="YOUR_CHATBOT_ID" async></script>
<script>
  window.addEventListener("load", () => {
    ChatWidget.registerTools({
      search_site: async ({ query }) => {
        const hits = await fetch(`/search.json?q=${encodeURIComponent(query)}`).then((r) => r.json());
        return hits.slice(0, 5).map((h) => ({ title: h.title, url: h.url }));
      },
    });
  });
</script>

That is all. The widget checks the args against the tool's schema before your function runs, and catches anything it throws (see What the widget guarantees).

Visitor
Widget
Sarufi
Your page
  1. 1Asks: do you have blue shoes?
  2. 2Sends the message and the tools this page has
  3. 3The agent picks search_site
  4. 4Run search_site for blue shoes
  5. 5Calls your handler
  6. 6Returns five matches
  7. 7Sends the result
  8. 8Replies with the matches
A public site tool, from question to reply

Test on your own site. The dashboard playground does not run website tools, because they live in your page. Open your site, ask "search for blue shoes", and run ChatWidget.debug(true) in the console if nothing happens.

What you'll see in your dashboard

  • Inbox: each agent reply shows the tools it used, with their outcome and how long they took. Failed and timed-out calls stand out, so you can find the conversation where a handler went wrong.
  • Per-tool stats: for each tool, how often it runs, how often it fails and with what, and how long it takes.
  • Analytics: how your tools are helping (conversations that used a tool and were resolved), and capability gaps: things visitors keep asking for that the bot cannot do or answer yet, each with a suggested fix such as adding a website tool, an MCP integration or a knowledge base topic. A gap is shown only when several different visitors asked for it. Requests the bot's safety guards stopped, and off-topic requests it declined, never count as gaps.

Where to go next

On this page