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.

agent:    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
agent:    "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 turn continues without waiting for the browser, 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).

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({ userId: 'admin@example.com' });
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 agent where the visitor is

Send the current page and its keys as the page_context request variable. session.setDynamicPrompt() sets it for you, or pass requestVars at connect. The manifest already has the keys:

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

Adapters

WordPress and other multi-page sites

The question is what happens to the avatar when the visitor moves to another page. It depends on how the site changes pages.

Normal multi-page theme: resume the thread

Every page load creates a new KalturaAvatarSession. The old one is gone with its page. What carries over is the thread. Save session.threadId and pass it as cfg.threadId on the next page. The join of the new session carries it, so the agent continues the same conversation.

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

// Your server mints a per-visitor token, calls appInit and returns its ks and host fields.
const { ks, conversationManagerUrl, srsBaseUrl, turnServerUrl } = await (await fetch('/api/avatar-session')).json();

const session = new KalturaAvatarSession({
  token: ks,
  conversationManagerUrl,
  srsBaseUrl,
  turnServerUrl,
  videoEl: document.querySelector('#avatar-video'),
  audioEl: document.querySelector('#avatar-audio'),
  socketFactory: (url, opts) => io(url, opts),
  threadId: sessionStorage.getItem('avatar.thread') || undefined,
});
session.on('turnEnd', () => {
  if (session.threadId) sessionStorage.setItem('avatar.thread', session.threadId);
});
session.on('warning', (w) => {
  if (w.code === 'playback_blocked') showTapToStart(() => session.startPlayback());
});

new SiteNavigator({
  session,
  manifestUrl: '/nova/sections.json',
  navigate: (url) => location.assign(url),
});
await session.connect();

What the visitor gets and what they do not:

Keeping the threadId in the browser is safe only with a per-visitor token (createAgentToken({ agentId, userId }), see Per-visitor browser path). With a widget token, anyone who has a threadId can continue that thread, so keep each threadId per user on your server instead. See Security & Compliance § Session type.

sessionStorage is per tab. Use localStorage only if a returning visitor in a new tab should also resume.

SPA and headless front ends

Keep the avatar elements outside the view the router replaces and create the session once at the app shell. Route changes do not touch the session, the mic or the picture. Give SiteNavigator the router:

new SiteNavigator({
  session,
  manifestUrl: '/nova/sections.json',
  navigate: (url) => router.push(url), // return a promise that resolves after the route renders
});

If the framework re-mounts the <video>, rebind it with session.setVideoEl(el). See README § Avatar audio and video rendering.

Page-transition libraries

All of these keep one document, so the session, the mic permission and the WebRTC connection survive. The risk is the avatar's DOM and your boot script.

Barba rebind. Read the new container from the hook data. At afterEnter both containers are in the DOM, so getElementById finds the old element.

barba.hooks.afterEnter((data) => {
  const video = data.next.container.querySelector('#avatar-video');
  if (video) session.setVideoEl(video);
});
barba.init({ preventRunning: true });

new SiteNavigator({ session, manifestUrl, navigate: (url) => barba.go(url) });

Swup rebind. content:replace runs after the new content is in the DOM, so getElementById finds the new element.

swup.hooks.on('content:replace', () => {
  const video = document.getElementById('avatar-video');
  if (video) session.setVideoEl(video);
});

Boot guard for htmx or any setup where the script can run twice:

if (!window.avatarSession) {
  window.avatarSession = new KalturaAvatarSession(cfg);
}

WordPress

Verified on a WordPress block theme (Twenty Twenty-Five) with a footer script, with Barba.js and with Swup, against a live backend. The avatar markup and the boot module are printed from the footer. Persistent-container rules for Barba.js and Swup are in Page-transition libraries.

Token endpoint. Add a route on your site that mints the visitor's token and returns the ks and host fields from appInit, as in the per-visitor browser path. A PHP route that makes those two calls over HTTP worked. A small Node service that runs Management works too.

Keep each threadId per user on the server when you use a widget token. See Security & Compliance § Session type.

Build sections.json from your published pages with buildSectionsManifest (see The manifest). Re-run it when content changes.

Block themes with a page-transition library

A router that swaps only one container breaks two things on a block theme. Both reproduced in Chromium, Firefox and WebKit.

1. Back and Forward reload the page. The theme's Interactivity API reloads on popstate when the history entry has no wpInteractivityId. Barba.js and Swup write entries without it, so the avatar restarts on every Back. Keep the id on every entry the router writes. Run this once, before the router starts:

for (const method of ['pushState', 'replaceState']) {
  const original = history[method].bind(history);
  history[method] = (state, ...rest) => {
    const id = history.state?.wpInteractivityId;
    return original(state && typeof state === 'object' && id !== undefined ? { ...state, wpInteractivityId: id } : state, ...rest);
  };
}

2. The new page is only half applied. The container swap leaves out the body classes, the per-page block styles (<style id="wp-block-…-inline-css">) and the inline scripts. Copy them from the fetched page after each swap:

function syncPage(html, container) {
  const next = new DOMParser().parseFromString(html, 'text/html');
  document.body.className = next.body.className;
  for (const el of next.querySelectorAll('style[id], link[rel="stylesheet"][id]')) {
    if (!document.getElementById(el.id)) document.head.append(el.cloneNode(true));
  }
  container.querySelectorAll('script').forEach((old) => {
    const fresh = document.createElement('script');
    for (const attr of old.attributes) fresh.setAttribute(attr.name, attr.value);
    fresh.textContent = old.textContent;
    old.replaceWith(fresh);
  });
}
// Barba.js: skip the first load, the page already ran its scripts.
barba.hooks.afterEnter((data) => { if (data.current.container) syncPage(data.next.html, data.next.container); });
// Swup:
swup.hooks.on('page:view', (visit) => syncPage(visit.to.html, document.getElementById('swup')));

With both fixes, the transitioned page matched a direct load of the same URL (title, body classes, style ids).

Not tested: whether a browser asks for the microphone again after a full page load (the tests granted it), caching plugins, and other themes or page-builder plugins.

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.

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