Faustine Docs
⌘K
Sign in
Technologies menu

DocsTechnologiesWeb app frameworksQuickstart

Angular quickstart

View as MarkdownOpen in ClaudeOpen in ChatGPT

Add a Web Agent to an Angular 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

  • An Angular 19 or later app with standalone components, started with bootstrapApplication.
  • 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 is plain JavaScript with its own types. It loads the widget and your agent's served version from Faustine when the page loads.

3. Start the agent

Wrap the loader in a service, so that the rest of the app reaches the agent through dependency injection.

src/app/faustine.service.ts
import { Injectable } from '@angular/core';
import Faustine, { type AgentHandle, type IdentifyInfo } from '@faustine-ai/web-agent';

@Injectable({ providedIn: 'root' })
export class FaustineService {
  private agent: AgentHandle | null = null;

  start(): void {
    this.agent ??= Faustine.init({ agentId: '<AGENT_ID>' });
  }

  identify(info: IdentifyInfo): void {
    this.agent?.identify(info);
  }

  logout(): void {
    this.agent?.logout();
  }
}

Start the agent from an app initializer in app.config.ts. The initializer runs once, before the root component renders.

src/app/app.config.ts
import { ApplicationConfig, inject, provideAppInitializer } from '@angular/core';
import { provideRouter } from '@angular/router';
import { routes } from './app.routes';
import { FaustineService } from './faustine.service';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideAppInitializer(() => inject(FaustineService).start()),
  ],
};

init returns immediately and loads the widget in the background, so the initializer does not delay the app. It loads the Production environment. To load another one, pass its name: env: 'Staging'.

4. Identify the signed-in user

In the root component, 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/app.ts
import { Component, effect, inject } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { FaustineService } from './faustine.service';
import { SessionService } from './session.service';

@Component({
  selector: 'app-root',
  imports: [RouterOutlet],
  template: '<router-outlet />',
})
export class App {
  private readonly faustine = inject(FaustineService);
  private readonly session = inject(SessionService);
  private signedIn = false;

  constructor() {
    effect(() => {
      const user = this.session.user();
      if (user) {
        this.faustine.identify({ userId: user.id, name: user.name, email: user.email });
        this.signedIn = true;
      } else if (this.signedIn) {
        this.faustine.logout();
        this.signedIn = false;
      }
    });
  }
}

SessionService stands for your own service, and user is a signal that holds the signed-in user or null. The effect calls logout only after a user has been identified, so a visitor who never signs in keeps their conversation.

If your session is an observable, subscribe to it instead and run the same two branches, or convert it with toSignal.

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
ng serve

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 src/index.html. The JS / Auto tab of the Install the assistant card has this snippet with your ID filled in.

src/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. ng serve runs on localhost:4200. Add localhost:4200 to the environment you develop against. See Restrict the domains that can load the agent.
provideAppInitializer is not exported The app is on Angular 18 or earlier. Call inject(FaustineService).start() in the constructor of the root component.
The server log shows init called outside a browser The app renders on the server and the initializer 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