Navigation

Navigation lets the agent move users through your app (open a page, follow a deep link, or drive a multi-step flow) while you stay in control of how navigation happens: SPA router, full reload, hash change, and so on. Use it whenever the right response is to put the user somewhere rather than perform an action.

When to use it

• Open a specific page or sub-section (e.g. /settings/brand).
• Jump to an entity detail view (e.g. /accounts/42).
• Drive multi-step flows where the agent guides the user through screens.

How it works

Navigable routes are not defined in code. Product teams create and publish them in the Agent Studio UI, and your job as a developer is to implement the handler that executes them inside your app.

1. In Agent Studio (UI): PMs or Admins define allowed URL patterns (e.g. /settings/brand, /orders/:id) under the Navigation section. Once published, these routes become available to the agent.
2. In your app (code): you register a navigationHandler with the SDK. When the agent triggers a Navigation Action, it calls your handler with the resolved URL.

Caution

The list of navigable routes is defined and published by product teams in Agent Studio under Navigation, not in your codebase.

Register a navigation handler

Define a handler and register it with the agent. The handler decides how to navigate and must call onSuccess or onError.

const handler = (url: string, ok: (m: string) => void, err: (m: string) => void) => {
  window.history.pushState({}, "", url);
  ok(`Navigated to ${url}`);
};

window.foldspace.agent("AGENT_KEY").setNavigationHandler(handler);

Parameters

Parameter	Type	Required	Description
url	string	Yes	The target URL or route requested by the agent. This can be a full path (e.g. /settings/brand) or a route key if you’ve implemented mapping.
onSuccess	(message: string) => void	Yes	Invoke when navigation succeeds. The message is logged in the agent’s observability/debug view.
onError	(message: string) => void	Yes	Invoke when navigation fails (e.g. invalid route, blocked by guards). The message helps identify why navigation was rejected.

Examples

React Router (v6+)

import { useNavigate } from "react-router-dom";

export function AgentBootstrap() {
  const navigate = useNavigate();

  React.useEffect(() => {
    const handler = (url: string, ok: (m: string) => void, err: (m: string) => void) => {
      try {
        navigate(url);            // SPA route change
        ok(`Navigated to ${url}`);
      } catch (e) {
        err(`React Router failed: ${(e as Error).message}`);
      }
    };

    window.foldspace.agent("AGENT_KEY").setNavigationHandler(handler);
  }, [navigate]);

  return null;
}

Angular

import { Injectable } from '@angular/core';
import { Router } from '@angular/router';

@Injectable({ providedIn: 'root' })
export class AgentNav {
  constructor(private router: Router) {}

  init() {
    const handler = async (
      url: string,
      ok: (m: string) => void,
      err: (m: string) => void
    ) => {
      try {
        const success = await this.router.navigateByUrl(url);
        if (success) {
          ok(`Navigated to ${url}`);
        } else {
          err(`Navigation to "${url}" was canceled or failed (guards/redirects).`);
        }
      } catch (e: any) {
        err(`Angular router error navigating to "${url}": ${e?.message ?? e}`);
      }
    };

    window.foldspace.agent('AGENT_KEY').setNavigationHandler(handler);
  }
}

Related

• Defining navigation in Agent Studio: set up navigable routes before wiring the handler.