Pages and highlights

Let a tool offer the customer a page of your app, or point at something on the page.

import { defineConfig, navigation } from "@mediansh/agent-tools";

export default defineConfig({
  plugins: [navigation({ exclude: ["/admin/**", "/internal/**"] })],
  tools: {
    // ...
  },
});

"use client";

import { MedianSupport } from "@mediansh/widget";
import { useRouter } from "next/navigation";

export function Support({ publicKey }: { publicKey: string }) {
  const router = useRouter();
  return <MedianSupport apiKey={publicKey} onNavigate={router.push} />;
}

A tool result can carry a page, a highlight, or both. The page becomes a Take me there button under the agent’s reply. Nothing moves until the customer presses it. Without onNavigate on the widget there is no button. See Support widget.

Offer any page

navigation() is a plugin that adds one tool, goToPage. It reads your Next.js routes when the route module loads and offers every page you do not exclude.

• The agent picks a page from the list and supplies a value for each bracketed segment. /orders/[id] and 1234 become /orders/1234.
• Values are URL encoded. A catch-all [...slug] value may contain slashes. An optional [[...slug]] may be left empty.
• Values are sent comma separated, in bracket order, so one value cannot contain a comma.
• The page input only accepts pages on the list. The wrong number of values, or an empty value, returns { offered: false, reason } so the agent can try again.
• goToPage counts toward the 20 tools per organization. It shows on Agent → Tools like any tool and can be switched off.
• A page on the list returns navigateTo(path, { offered: true, page }). See Offer a page from your own tool.

Exclude pages

Patterns match pages as Next.js writes them, brackets included, so /orders/[id] excludes that one page. Nothing is excluded by default.

An excluded page is left out of the list the agent gets, so the agent cannot offer it or learn from the list that it exists.

An exclusion that matches no page logs a console warning, Median: navigation() has no pages matching "/admni/**", so it excludes nothing. Check the spelling if you meant to keep a page out.

Where the routes come from

The scan goes 24 folders deep and reads up to 20,000 files in each folder it starts from. It skips node_modules, .git, .next, dist and build.

What counts as a page

Load errors

Edge runtimes

The scan reads the disk, which needs Node 20.16 or later, or Bun. On an edge runtime it finds nothing, so pass routes:

navigation({ routes: ["/", "/settings", "/orders/[id]"] })

Offer a page from your own tool

Wrap a result in navigateTo when the page depends on something only your server knows:

import { defineConfig, navigateTo, p } from "@mediansh/agent-tools";

export default defineConfig({
  tools: {
    openOrder: {
      description: "Offer the customer one of their orders.",
      input: { orderNumber: p.string("The order number.") },
      async execute({ orderNumber }, { visitor }) {
        if (!visitor.verified) return { ok: false, reason: "not_signed_in" };
        const order = await findOrder(visitor.externalId, orderNumber);
        if (order === null) return { found: false };
        return navigateTo(`/orders/${order.id}`, { found: true });
      },
    },
  },
});

navigateTo(path, facts?) returns facts with a medianNavigateTo key. The agent reads facts. Median removes the path before the agent reads the result, so the agent never sees it and cannot invent one.

Query strings are allowed, as in /orders/1234?tab=refunds.

On a bad path, navigateTo throws This tool cannot navigate there. followed by the reason. The call fails, and the agent is told the tool could not do it. Check a path first with navigationPathIssue(path), which returns the reason or null.

Median checks the path again when the result arrives, and drops one that is not a path on your site.

Point at something

Add medianHighlight, a CSS selector, to a result:

return {
  ...navigateTo(`/orders/${order.id}`, { found: true }),
  medianHighlight: "#refund-button",
};

Without a destination it points at something already on screen:

return { exported: true, medianHighlight: "#export-button" };

What the customer sees

Buttons under a reply do not expire.