# Navigation

Navigation is the part of a Web Agent that knows your app's routes and can take the user to one of them. The analysis reads your router and writes the code that changes the route the way your app does. You see it in the agent's [**Actions**](https://auth.faustine.ai/go?to=%2Fweb-assistants) tab, in the **Assistant** group, as **Navigation**.

## How it works

The analysis records the list of routes and writes one function, `navigate(path)`, in a file named `navigation.js`. The model receives the list of routes with every conversation and navigates only to paths on it. For a route with a parameter, such as `/contacts/:id`, it fills in the value.

The route change is a soft one: the page does not reload, so the widget and the conversation stay open. For a client-side router that listens to browser history, the function body is these two lines.

```js filename="navigation.js"
history.pushState({}, '', path);
window.dispatchEvent(new PopStateEvent('popstate'));
```

The analysis writes a different body when your router needs one. Next.js apps get one that calls the Next.js router.

## When the agent navigates

The agent navigates to show the user the result of something it did, and when the user asks to go somewhere.

| The agent navigates | The agent stays on the current screen |
| --- | --- |
| After it creates or substantially edits a record that has a detail route. It opens that record. | After it reads, searches or answers a question. |
| When the user asks to open or go to something that matches a route. | After a secondary change, such as saving a preference. |
| | When the user is already on that path. |

The agent does not send the user to a form to do the work themselves. Asked to create a contact, it runs the action.

## What the analysis records

Open **Navigation** in the **Actions** tab to see three things.

| Part | What it is |
| --- | --- |
| **How your app navigates** | A description, in words, of the router the analysis found. |
| **Routes detected** | The paths the agent can navigate to, with their count. |
| `navigation.js` | The body of `navigate(path)`. Only the body can be edited. |

## Refresh after a change

`navigation.js` also holds a `refresh()` function. The agent's code calls it after every action that writes, so that the page shows the new data. In an app that renders its data in the browser, the function does nothing. In a server-rendered app, it asks the framework to load the page's data again.

## Change the navigation

Change it when routes are added or renamed, or when a soft navigation does not move your app.

- Run an update or a re-analysis to pick up new routes. See [Keep the agent up to date](https://docs.faustine.ai/web-agents/keep-up-to-date/).
- Edit the body of `navigate(path)` in the **Actions** tab, then select **Save changes**.
- Select **Doesn't look right? Fix it in an interactive session** to open [the Advanced editor](https://docs.faustine.ai/web-agents/advanced-editor/) with the request already written.

The change is saved to the draft. Your site gets it when you publish a version.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| The address bar changes and the screen does not | Your router does not react to the history event the function sends. | Replace the body with a call to your router's own navigation function, or ask for the fix in the Advanced editor. |
| The agent says it cannot open a screen that exists | The route is not in **Routes detected**. | Run an update so that the analysis reads the new route. |
| The list on screen does not show a record the agent created | The page did not load its data again after the change. | In the Advanced editor, set `refresh()` to call what your app uses to reload its data. |

## Next steps

- [Authentication](https://docs.faustine.ai/web-agents/authentication/): how actions run as the signed-in user.
- [The Guide](https://docs.faustine.ai/web-agents/guide/): an agent that takes users to a screen and points at what to select.
- [The Advanced editor](https://docs.faustine.ai/web-agents/advanced-editor/): change `navigation.js` from a conversation.