# Quickstart: add an agent to your web app

Create a Web Agent from the code of a single-page app and load it on a page. At the end, the agent's launcher is on your app and the agent runs the app's actions for the signed-in user.

This is the short path, with the defaults. For each step explained on an example app, see [Build your first Web Agent](https://docs.faustine.ai/web-agents/build-your-first-web-agent/).

## Prerequisites

- A Faustine workspace with a model provider connected. See [Connect your model provider](https://docs.faustine.ai/get-started/connect-your-ai-provider/).
- The code of a client-rendered web app (React, Vue, Angular, Svelte or another single-page app) in a GitHub, GitLab or Bitbucket repository, or as a ZIP.
- A place to edit the app's `index.html`.

For a Next.js app, follow the [Next.js (App Router) quickstart](https://docs.faustine.ai/technologies/nextjs-app-router/) instead. The install step is different.

## 1. Create the Web Agent

1. In the portal, go to [**Web Agents**](https://auth.faustine.ai/go?to=%2Fweb-assistants) and select **New Web Agent**. The **Quick start** wizard opens.
2. In **Choose your app type**, select **Single Page Application** and your framework.
3. Under **What is your agent for?**, select **Get the work done for them**.
4. In **Details**, enter an **Assistant name**. Under **Environments**, **Staging** is selected. The first environment you select is where new versions are served.
5. In **Connect your code**, choose where the code is, then select the **Repository** and its branch. To use an archive, select **Upload a ZIP**.
6. In **Keep the assistant up to date**, keep **Automatic**. Faustine analyzes the code again on every push to the branch.
7. In **Extra resources**, select **Continue**. The step is optional.
8. In **Review & create**, select **Create & start analysis**.

> **Warning:** The analysis runs on your model provider and your provider bills you for it. The larger the codebase, the more it costs.

## 2. Run the analysis

The analysis page opens and shows its stages. You can leave the page while it runs. Faustine emails you as each stage finishes.

1. Wait for **Clone the repository** and **Analyze the architecture & modules** to finish.
2. In **Choose what to analyze**, select the modules the agent should work with. A module is one feature area of your app, such as deals or contacts. Each module you select adds to the cost of the analysis, and you can analyze more later.
3. Select **Analyze selected**.
4. When **Summary** shows **Analysis complete**, select **Continue to setup**.

The summary lists the modules and actions the analysis found.

## 3. Finish the setup

The **Set up your assistant** wizard has seven steps: **Get to know your assistant**, **Actions**, **Web search**, **Knowledge base**, **Look & feel**, **AI model** and **Install the assistant**. Each one has a working default.

1. Read the three prompts in **Get to know your assistant** and correct anything that is wrong about your app. Select **Continue**.
2. Select **Continue** on each of the next five steps.
3. In **Install the assistant**, select **Copy** to copy the embed snippet.
4. Select **Launch**. Faustine publishes a version with your setup and opens the agent's page.

## 4. Add the script tag

Paste the snippet inside the `<head>` of your app's `index.html`. `<AGENT_ID>` is filled in when you copy it from the portal.

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

The script names no environment. It loads Production, or the agent's first environment while the agent has no Production. To install from npm or in a specific framework, see the [React quickstart](https://docs.faustine.ai/technologies/react/), the [Vue quickstart](https://docs.faustine.ai/technologies/vue/), the [Angular quickstart](https://docs.faustine.ai/technologies/angular/), the [Svelte quickstart](https://docs.faustine.ai/technologies/svelte/) or [Plain HTML and other single-page apps](https://docs.faustine.ai/technologies/html/).

## 5. Run your app

Start your app and sign in.

> **Checkpoint:** The agent's launcher appears on the page. Select it and ask the agent to do something one of the analyzed modules covers. In the portal, the conversation appears under the agent's **Monitoring** tab.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| The portal shows **Connect your AI provider first** instead of the wizard | The workspace has no model provider connected. | [Connect your model provider](https://docs.faustine.ai/get-started/connect-your-ai-provider/). |
| 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/): tell the agent which user it is talking to.
- [Actions](https://docs.faustine.ai/web-agents/actions/): review what the agent can do and require confirmation where it matters.
- [Versions, environments and deployments](https://docs.faustine.ai/web-agents/versions-and-environments/): add Staging and control what Production serves.
- [Set up with a coding agent](https://docs.faustine.ai/get-started/set-up-with-a-coding-agent/): let Claude Code or Cursor do the install.