Overview

Let the agent navigate your app (deep-link or route changes) while you keep full control over how navigation happens (SPA router, full reload, hash changes, etc.).

When to use

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

Prerequisites

Navigation lets the agent move users through your app (e.g., open Settings, Accounts, or Order detail).

📘
⚠️ Important: The list of navigable routes is not defined in code.
Product teams create and publish Navigation Actions in the Agent Studio UI under Actions → Navigation.

As a developer, your role is to implement the navigation handler that executes those routes inside your app.

How it works

In Agent Studio (UI)
- PMs or Admins define allowed URL patterns (e.g., /settings/brand, /orders/:id) inside a Navigation Action.
- Once published, these routes become available to the agent.
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.

Registering 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 ${target}`);
};

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

NavigationHandler 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 this when navigation succeeds. The message is logged in the agent’s observability/debug view.
`onError`	`(message: string) => void`	Yes	Invoke this 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.eucera.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.eucera.agent('AGENT_KEY').setNavigationHandler(handler);
  }
}

Creating Navigation In Agent Studio

Defining Navigation

Learn how to set up the Eucera SDK before adding actions