Svelte quickstart | Faustine Docs

Add a Web Agent to a Svelte app built with Vite. At the end, the agent's launcher is on every page of your app and the agent knows which user is signed in.

Prerequisites

A Svelte 5 app that uses runes, built with Vite, that runs in the browser only.
A Web Agent in your workspace whose analysis has finished, with a version deployed to Production.

1. Copy your agent ID

In the portal, go to Web Agents and select your agent.
In the Overview tab, find the Install the assistant card and select the npm tab.
Copy the agentId value from the snippet.

2. Install the loader

terminal

npm install @faustine-ai/web-agent

terminal

pnpm add @faustine-ai/web-agent

terminal

yarn add @faustine-ai/web-agent

terminal

bun add @faustine-ai/web-agent

The package has no dependency on Svelte. It loads the widget and your agent's served version from Faustine when the page loads.

3. Start the agent

Create a module that starts the agent, and import it from src/main.ts.

src/faustine.ts

import Faustine from '@faustine-ai/web-agent';

export const agent = Faustine.init({
  agentId: '<AGENT_ID>',
});

src/main.ts

import { mount } from 'svelte';
import App from './App.svelte';
import './faustine';

const app = mount(App, { target: document.getElementById('app')! });

export default app;

init loads the Production environment. To load another one, pass its name: env: 'Staging'.

4. Identify the signed-in user

An effect tells the agent when the user changes. This example passes a display name and email, which appear in the agent's Monitoring tab as Unverified.

src/App.svelte

<script lang="ts">
  import { agent } from './faustine';
  import { session } from './session.svelte';

  let signedIn = false;

  $effect(() => {
    const user = session.user;
    if (user) {
      agent.identify({ userId: user.id, name: user.name, email: user.email });
      signedIn = true;
    } else if (signedIn) {
      agent.logout();
      signedIn = false;
    }
  });
</script>

session stands for your own state, declared with $state in a .svelte.ts module, where user is the signed-in user or null.

signedIn is a plain variable, not $state, so writing it does not run the effect again. The effect calls logout only after a user has been identified, so a visitor who never signs in keeps their conversation.

For production, replace the labels with a token signed by your backend. See Verify your users with a signed token.

5. Run your app

terminal

npm run dev

Checkpoint

The agent's launcher appears on the page. Select it and send a message. In the portal, the conversation appears under the agent's Monitoring tab.

Install with a coding agent

The install-faustine skill does steps 2 to 4 in your repository and follows its conventions.

terminal

npx skills add faustine-ai/skills

Then, in your coding agent:

/install-faustine <AGENT_ID>

Install without a build step

If you cannot add a dependency, load the widget from a script tag in index.html. The JS / Auto tab of the Install the assistant card has this snippet with your ID filled in.

index.html

<script src="https://webagent.faustine.ai/embed?wid=<AGENT_ID>" async></script>

Troubleshooting

Symptom	Cause	Fix
No launcher, and the request to `webagent.faustine.ai/embed` returns `404`	No environment of the agent serves a version.	Publish a version.
No launcher, and the same request returns `403`	The page's domain is not in the environment's allowed domains.	See Restrict the domains that can load the agent.

Next steps

Verify your users with a signed token: give users their history on every device.
Restrict the domains that can load the agent: allow your own domains only.
Use your own launcher button: open the agent from a button in your layout.
JavaScript API: every option of init and every method of the handle.