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 want | Path | Definitions come from | Backend or token needed |
|---|---|---|---|
| Public features anyone can use: search, store hours, stock | Public site tools | A tool set in your workspace, linked to the bot | No |
| Features for a signed-in user: balance, orders, payments | Signed-in users | A tool set, with "Needs signed-in user" on | Yes: a host token per user |
| Definitions kept next to your code, shipped with your release | Tools declared in page code | ChatWidget.tool() on the page | Yes: 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).
- 1Asks: do you have blue shoes?
- 2Sends the message and the tools this page has
- 3The agent picks search_site
- 4Run search_site for blue shoes
- 5Calls your handler
- 6Returns five matches
- 7Sends the result
- 8Replies with the matches
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
- Tool sets and limits: defining tools, the set id rule, and every limit.
- Signed-in users: host tokens, signing in and out, and shared devices.
- Running calls: handlers, steps, the status line, and what happens on reload.
- Tools declared in page code:
ChatWidget.tool()and signed definitions. - Developer API: the same tools without the widget.
- Safety and Troubleshooting.