Faustine Docs
⌘K
Sign in
Technologies menu

DocsTechnologiesWeb app frameworksQuickstart

Vue quickstart

View as MarkdownOpen in ClaudeOpen in ChatGPT

Add a Web Agent to a Vue 3 single-page app. 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 Vue 3 app built with Vite, written with <script setup>.
  • 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 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

terminal
npm install @faustine-ai/web-agent

The package has no dependency on Vue. 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. The agent lives outside the Vue app, so it needs no plugin and no component.

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

export const agent = Faustine.init({
  agentId: '<AGENT_ID>',
});
src/main.ts
import { createApp } from 'vue';
import App from './App.vue';
import router from './router';
import './faustine';

createApp(App).use(router).mount('#app');

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

4. Identify the signed-in user

Write a composable that watches the user and tells the agent when it changes. This example passes a display name and email, which appear in the agent's Monitoring tab as Unverified.

src/composables/useFaustineUser.ts
import { watch, type Ref } from 'vue';
import { agent } from '../faustine';

type User = { id: string; name: string; email: string };

export function useFaustineUser(user: Ref<User | null>) {
  watch(
    user,
    (current, previous) => {
      if (current) {
        agent.identify({ userId: current.id, name: current.name, email: current.email });
      } else if (previous) {
        agent.logout();
      }
    },
    { immediate: true },
  );
}

immediate: true runs the watcher once at setup, so a user who is already signed in when the app loads is identified. logout runs only when the user goes from a value to null, so a visitor who never signs in keeps their conversation.

Call the composable from App.vue. useSession stands for your own composable or store, and user is a ref that holds the signed-in user or null.

src/App.vue
<script setup lang="ts">
import { useSession } from './session';
import { useFaustineUser } from './composables/useFaustineUser';

const { user } = useSession();
useFaustineUser(user);
</script>

<template>
  <RouterView />
</template>

With Pinia, get the ref with storeToRefs: const { user } = storeToRefs(useSessionStore()).

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.
The user is not identified after sign-in The composable received a plain object, not a ref, so the watcher never runs again. Pass the ref itself, or a getter: watch(() => store.user, …).
The server log shows init called outside a browser The app renders on the server and src/faustine.ts ran there. init does nothing on the server. No change is needed. The agent starts when the app loads in the browser.

Next steps

Last updated November 13, 2026