Site navigation — one fire-and-forget go_to tool for any website

Let the agent move the visitor to the right page and section of your site while it answers. One client tool, two string arguments, no result to wait for, so it can never spiral or leave the avatar silent.

brain:    go_to({ path: "/guides/pause-resume/", section: "edge-case-dont" })
browser:  navigate("/guides/pause-resume/#the-edge-case-dont-leave-the-avatar-stuck-paused") → scroll → point
brain:    "Pause before the video starts and resume on its ended event..."

Three pieces, one shared contract:

Why fire-and-forget

A navigation tool needs no answer from the page. The tool is provisioned with wait_for_response: false, so the backend produces the tool result itself right after the model emits the call, and the browser never sends anything back. There is nothing to ACK, time out on, or retry.

The model writes its spoken answer in the same turn. Compare Client-Side Commands § Tool spirals for what happens to tools that do wait.

Two consequences shape the browser side:

• The model may emit two go_to calls in one turn when a question spans two pages. The plugin executes the first call that resolves to a real page and drops the rest until the next turn (oncePerTurn).
• The model may send a slightly wrong path or section. The plugin resolves both against the manifest with a fallback chain, and an unknown section still lands on the page top. An unknown path is dropped, never guessed.

The manifest (sections.json)

The site build publishes one public JSON file. The same file feeds the prompt (rendered as a SITE MAP) and the browser (resolution).

{
  "version": 1,
  "lang": "en",
  "generatedAt": "2026-09-04T10:00:00.000Z",
  "pages": [
    {
      "path": "/guides/pause-resume/",
      "title": "Pause/Resume for Video",
      "sections": [
        { "key": "what-it-is", "id": "what-it-is", "text": "What it is" },
        { "key": "edge-case-dont", "id": "the-edge-case-dont-leave-the-avatar-stuck-paused", "text": "The edge case: don't leave the avatar stuck paused" },
        { "key": "demo-box", "id": "demo-box", "text": "Live demo", "kind": "target" }
      ]
    }
  ]
}

Only public data belongs here: paths and headings that are already on the page. Never add internal notes, draft pages, or anything a visitor should not see.

Building it

buildSectionsManifest(pages, opts) takes any page source: built HTML, a markdown tree, a SPA route table, a CMS export. Only path is mandatory per page.

import { buildSectionsManifest } from '@kaltura/intelligent-agents/management';

const manifest = buildSectionsManifest([
  { path: '/guides/pause-resume/', title: 'Pause/Resume', headings: [
    { id: 'what-it-is', text: 'What it is', level: 2 },
    { id: 'the-edge-case-dont-leave-the-avatar-stuck-paused', text: "The edge case: don't leave the avatar stuck paused", level: 2 },
  ], targets: [{ id: 'demo-box', text: 'Live demo' }] },
], { lang: 'en', depth: 2 });
writeFileSync('_site/nova/sections.json', JSON.stringify(manifest));

How keys are derived

Deterministic, so a docs change re-keys only the page it touched:

1. NFKC-normalize the heading, drop URLs, drop apostrophes and dots inside words (don't → dont, v2.3 → v23), split on anything that is not a letter or number. Hebrew, CJK, accented Latin and emoji-laden headings all yield usable keys.
2. Lower-case and drop stop words. A single upper-case letter like the A in Recipe A survives. Pure numbers drop when at least two other words remain.
3. Take the first maxWords words, hyphen-joined. Fewer than two words left means the full word list is used; nothing left means section.
4. On a collision within the page, extend the key one word at a time, then suffix -2, -3.
5. Boilerplate headings (Related docs, Contents, On this page, Next steps and friends, see BOILERPLATE_IDS) are left out so the model never targets them.

pageSectionKeys(headings, opts) exposes step 1–5 for one page when you need only the keys.

Rendering the SITE MAP

renderSiteMap(manifest) gives the prompt text: two lines per page, the page title and then path: key1, key2, with a blank line between pages. About 45 tokens per page. The title lets the model match what a visitor calls a page ("the wire protocol page") to its path. The path line carries only the path and the keys: a label next to the path gets copied into go_to as part of the path.

siteMapPrompt(manifest) wraps it as a prompt block and warns (never throws) when the estimate passes maxTokens (default 3000). The docs site's 49 pages and ~174 sections render to about 2500 tokens (test/fixtures/site-map.snapshot.txt).

Provisioning

import {
  Management, goToTool, siteMapPrompt, SITE_NAV_RULES_PROMPT, PAGE_CONTEXT_PROMPT, loadSectionsManifest,
} from '@kaltura/intelligent-agents/management';

const m = new Management({ partnerId, adminSecret });
const ks = await m.sessions.createAdminToken();
const manifest = await loadSectionsManifest('https://docs.example.com/nova/sections.json');

const tool = await m.tools.add(goToTool({ siteLabel: 'the Example docs' }), ks);
await m.intellects.create({
  type: 'internal',
  status: 2,
  tool_ids: [tool.id],
  allow_client_variables: true,
  base_directive: '...',
  prompts: [identityPrompt, siteMapPrompt(manifest), SITE_NAV_RULES_PROMPT, PAGE_CONTEXT_PROMPT], // identityPrompt is your own prompt block, not part of this SDK
  capabilities: { /* your own capabilities config */ },
}, ks);

Prompt order matters: identity first, then SITE MAP, then rules, then page context. Turn kaltura_genie_experiences off on the intellect, otherwise the built-in experience tools compete with go_to.

Redeploys stay on the same tool id when you look the tool up by name and call tools.update(id, { config: goToTool() }). tools.delete refuses while an intellect still references the tool, so retire an old tool in a separate explicit step after the intellect's tool_ids has moved on.

Browser plugin

import { SiteNavigator } from '@kaltura/intelligent-agents/experience/site-nav';

const nav = new SiteNavigator({
  session,
  manifestUrl: '/nova/sections.json',
  navigate: (url) => router.push(url),          // SPA
  // navigate: (url) => location.assign(url),   // MPA full reload
  point: (el) => el.classList.add('is-pointed'),
  onNavigate: (info) => analytics.track('go_to', info),
});
// when the session ends
nav.destroy();

Construct it once per session, right after the session. destroy() unsubscribes everything and is idempotent (stop() is an alias). A second live navigator on the same session logs a warning.

Behaviour contract

onNavigate receives either a result or a drop:

// resolved
{ path, url, section, sectionId, resolvedBy, fellBackToTop, splitPath, samePage, sectionFound, args }
// dropped
{ dropped: true, reason: 'unknown_path' | 'once_per_turn' | 'no_manifest' | 'unsafe_url', args }

Telling the brain where the visitor is

Send the current page and its keys as page_context through session.setDynamicPrompt() (or requestVars at connect). The manifest already has the keys:

const page = resolvePath(nav.manifest, location.pathname);
session.setDynamicPrompt({ page_context: { url: page.path, sections: page.sections.map((s) => s.key) } });

Adapters

Taking it to another app

1. Produce sections.json with buildSectionsManifest from whatever you have. Only path is mandatory per page. Publish it at a public, same-origin URL.
2. Provision: tool_ids: [ (await tools.add(goToTool({ siteLabel }), ks)).id ], prompts [identity, siteMapPrompt(manifest), SITE_NAV_RULES_PROMPT, PAGE_CONTEXT_PROMPT], allow_client_variables: true, kaltura_genie_experiences off.
3. Browser: new SiteNavigator({ session, manifestUrl, navigate }).
4. Optional: point for a visual pointer, onNavigate for analytics, lang and stopWords for a non-English site, overrides for keys that read badly.

Extensibility hooks that cost nothing today:

Non-goals: multi-argument actions (action: 'open' | 'highlight'), server-side routing, search over page bodies, replacing the knowledge base. One tool, two args.

Testing

• npm test covers the key algorithm, manifest build/validate/resolve, the prompt builders and the browser plugin offline (test/unit/site-keys.test.js, test/unit/site-nav-management.test.js, test/unit/site-nav.test.js). test/fixtures/site-map.snapshot.txt pins the rendered SITE MAP for the docs site so a key change is a visible diff.
• npm run live-verify:site-nav (scripts/live-verify-site-nav.mjs) runs against the real Kaltura API: tool echo shape, idempotent update, prompt echo, one mapped ask producing exactly one resolvable go_to, one unmapped ask producing none, then deletes everything it created. CI runs it on every merge and on PRs labelled run-live-verify. Tool names are unique per partner, so on a partner that already runs a live go_to tool the script records a skip, exits 0, and leaves that tool untouched. Point AGENTIC_PARTNER_ID at a partner without a live go_to deployment to run it for real.

Security

• Only manifest paths are navigable. The model cannot invent a destination.
• Every URL handed to navigate passes safeUrl. The browser's own manifest fetch (manifestUrl) does too; the provisioning-side loadSectionsManifest only requires an http(s):// URL, since it runs server-side against a URL you supply yourself.
• A fetched manifest is size-guarded, parsed, passed through sanitizeJson (prototype keys dropped) and validated before use, on both the server and the browser side.
• No innerHTML, no selector strings built from model output, no eval.
• The manifest is public data. Keep internal or unpublished pages out of the build input.

Related docs