How-to: a docs-site co-pilot

A visitor lands on your documentation and types "how do I rotate my API keys?" — and rather than getting a wall of links, they get a direct answer and the page jumps to the exact doc that sourced it. That's what this guide builds.

You're adding the Perfox widget to a docs site (here, example.com) so that it can answer questions from your knowledge base and navigate visitors straight to the relevant page. By the end you'll have the agent answering, navigating, and leaving no dead ends.

You name the events — not Perfox

Perfox is a broker: it carries a { event, payload } to your page and never decides what an event does — your page does. Perfox ships a few suggested names (navigate, scroll_to, highlight…) with conventional payloads, but the name is just a string you and your page agree on. You can invent your own — the OTP-login guide used a fully custom user_authenticated — and even navigate does nothing until you wire it (here, to a client-side route).

This is the agent-driven path: the agent decides to navigate mid-conversation. (The OTP-login guide shows the server-driven path for sensitive actions.)

Why this one is simpler than login

Navigation is low-stakes, so your page acts on the command directly — there's no need to echo it to your server and call /events/verify (that round-trip is only for sensitive actions like login or billing). The built-in same-origin guard keeps it safe: Perfox('on:ui','navigate', …) drops cross-origin URLs by default, so a docs bot jumping within its own site just works and can't be steered off to another origin. (Opt out with { same_origin_only: false } or an allowed_hosts list only if you really navigate off-site.)

Step 1 — Allow the event (once, in Studio)

Same panel as any UI command — no JSON to paste:

1. Build → Agents → open your agent.
2. Click the Web Chat trigger node → Install tab.
3. Section "Client-side UI commands (co-pilot)" → tick "Let the agent drive the host page (navigate, highlight, prefill…)".
4. In "Allowed events", type navigate, then publish the agent.

Step 2 — Tell the agent when to navigate (Persona)

When and how the agent drives the UI lives in its Persona (AI Agent), not in code. Add an instruction like:

When your answer is based on a documentation page, call drive_ui with event navigate and that page's URL, so the reader jumps straight to it.

Where does the URL come from? If your knowledge base was built from your docs site, each page carries its own URL and the agent navigates to the source of its answer. Otherwise, give the Persona a simple topic → URL mapping.

Step 3 — Handle it on your page

Register a handler on the page that embeds the widget — for navigate, just route:

Perfox('on:ui', 'navigate', ({ payload }) => {
  // your app's client-side router — same-origin is enforced for you
  router.push(payload.url);          // e.g. /docs/security/api-keys
});

That's the whole thing. The agent drives it inside the conversation; the widget re-emits it; your page routes. No backend calls, no verification — because navigating your own docs isn't sensitive.

Worked example: Priya asks, the page moves

Asha is the admin at Acme Diagnostics. She has connected the Acme Diagnostics docs site to a knowledge base in Perfox and activated a docs co-pilot agent.

Setup: Asha allowed the navigate event in Studio, added the Persona instruction above, and dropped the widget embed on every docs page.

Action: Priya, a new customer, opens the docs and types "how do I rotate my API keys?" into the widget.

Result: The agent answers with a short explanation, then calls drive_ui with navigate and the URL https://example.com/docs/security/api-keys. The widget fires Perfox('on:ui','navigate',…), the three-line handler routes the page, and Priya's browser lands on the exact section.

What just happened: the agent sourced its answer from the knowledge base, which stored the URL of each doc page. It then sent a signed navigate command through the widget. The same-origin guard ran silently — because the URL was within example.com, the command went through without any extra configuration.

Doing something sensitive instead?

If the command should trigger a login, a purchase, or anything you wouldn't let an arbitrary page script do, don't act directly — verify it on your server first. That flow (signature + /events/verify) is covered in How-to: OTP login → host UI. The bus envelope, both producers, and the full event registry are in the UI-command bus reference.

You're set

You can now build a docs co-pilot that answers questions from your knowledge base and navigates visitors straight to the source page — all in three steps, with no backend work for navigation.

Where to go next:

• UI-command bus — see every supported event, the payload shape, and how to invent your own (the reference you'll return to when you add scroll_to or highlight).
• How-to: OTP login → host UI — follow this when a command needs server-side verification before your page acts on it.