# Svelte quickstart

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

1. In the portal, go to [**Web Agents**](https://auth.faustine.ai/go?to=%2Fweb-assistants) and select your agent.
2. In the **Overview** tab, find the **Install the assistant** card and select the **npm** tab.
3. Copy the `agentId` value from the snippet.

## 2. Install the loader

**npm**

```bash
npm install @faustine-ai/web-agent
```

**pnpm**

```bash
pnpm add @faustine-ai/web-agent
```

**yarn**

```bash
yarn add @faustine-ai/web-agent
```

**bun**

```bash
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`.

```ts filename="src/faustine.ts"
import Faustine from '@faustine-ai/web-agent';

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

```ts filename="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**.

```svelte filename="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](https://docs.faustine.ai/web-agents/verify-users/).

## 5. Run your app

```bash
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.

```bash
npx skills add faustine-ai/skills
```

Then, in your coding agent:

```text
/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.

```html filename="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](https://docs.faustine.ai/web-agents/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](https://docs.faustine.ai/web-agents/restrict-domains/). |

## Next steps

- [Verify your users with a signed token](https://docs.faustine.ai/web-agents/verify-users/): give users their history on every device.
- [Restrict the domains that can load the agent](https://docs.faustine.ai/web-agents/restrict-domains/): allow your own domains only.
- [Use your own launcher button](https://docs.faustine.ai/web-agents/custom-launcher/): open the agent from a button in your layout.
- [JavaScript API](https://docs.faustine.ai/reference/javascript-api/): every option of `init` and every method of the handle.