> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scoutos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scout Copilot: Embed an AI Agent in Your Website or App

> Deploy a Scout agent as an embeddable chat widget on your website or app. Configure instructions, tools, and widget behavior for your end users.

Copilot is how you put a Scout agent directly in front of your users — as a chat widget embedded on your website, inside your product, or anywhere a simple script tag can run. Every Copilot is powered by a Scout agent you configure, so the same agent you've been building and testing in Studio becomes the experience your customers, prospects, or internal teams interact with. You control the instructions, the tools it can use, and how it presents itself — without writing any backend code.

## What Copilot Is

A Copilot deployment is a lightweight embeddable widget backed by a Scout agent. When a user opens the widget and sends a message, they're talking to your agent — with access to exactly the tools you've enabled, following exactly the instructions you've written. The widget handles the conversation UI; your agent handles the intelligence.

Common Copilot use cases:

* **Customer support** — answer product questions, surface documentation, and escalate when needed
* **User onboarding** — walk new users through setup and answer questions at each step
* **In-app assistant** — help users get more from your product without leaving the page
* **Internal knowledge base** — give your team a conversational interface to internal docs and processes
* **Sales and marketing** — answer prospect questions on your website and qualify interest

***

## Creating a Copilot Deployment

<Steps>
  <Step title="Open your agent">
    Navigate to the agent you want to deploy in Scout Studio. If you haven't built the agent yet, see [Getting Started](/agents/getting-started) to set one up first.
  </Step>

  <Step title="Go to Settings → Deployments">
    In the agent editor, click **Settings** and open the **Deployments** section.
  </Step>

  <Step title="Create a new Copilot deployment">
    Click **New Deployment** and select **Copilot**. Give it a name that identifies where it will be used — for example, "Support Portal" or "Marketing Site."
  </Step>

  <Step title="Configure the deployment">
    Adjust the widget settings for this deployment. Each deployment can have its own welcome message, tags for session tracking, and optional features like text-to-speech.
  </Step>

  <Step title="Copy the embed snippet">
    Scout generates a deployment-specific embed snippet. Copy it and paste it into your website or application where you want the widget to appear.
  </Step>
</Steps>

***

## Embedding the Widget

The basic embed is a single script tag and a custom element. Paste this into your HTML where you want the widget to appear:

```html HTML theme={null}
<script src="https://cdn.scoutos.com/copilot.js" defer></script>
<scout-copilot copilot-id="your-copilot-id"></scout-copilot>
```

Replace `your-copilot-id` with the deployment ID shown in Scout Studio. That's everything required for a basic deployment. The widget loads, positions itself, and connects to your agent automatically.

### Configuration attributes

You can extend the embed element with optional attributes to customize behavior:

| Attribute     | Required | Description                                                         | Default |
| ------------- | -------- | ------------------------------------------------------------------- | ------- |
| `copilot-id`  | Yes      | The deployment ID from Scout Studio                                 | —       |
| `tags`        | No       | Array of tags attached to agent sessions for tracking and filtering | `[]`    |
| `tts-enabled` | No       | Enable text-to-speech playback for assistant messages               | `false` |

### Add session tags

Pass metadata tags to every session your Copilot creates. Tags appear in the **History** view in Studio and can be used to filter and categorize sessions by source, page, or user segment:

```html HTML theme={null}
<scout-copilot
  copilot-id="your-copilot-id"
  tags='["support", "onboarding"]'
></scout-copilot>
```

Use tags to distinguish traffic from different placements — your homepage widget, your app's help sidebar, your support portal — so you can analyze them separately in Studio.

### Enable text-to-speech

Add `tts-enabled="true"` to make the widget read assistant messages aloud:

```html HTML theme={null}
<scout-copilot
  copilot-id="your-copilot-id"
  tts-enabled="true"
></scout-copilot>
```

When TTS is enabled, a speaker icon appears next to each assistant message. Users can click it to hear the message read aloud. Starting a new message automatically stops any currently playing one. TTS runs entirely in the browser — message content is not sent to any third party for speech synthesis.

**Browser support for TTS:** Chrome 33+, Safari 7+, Edge 14+, Firefox 49+. If the browser doesn't support TTS, the control appears disabled with an accessible message.

***

## How Agent Revisions Work

Copilot deployments always use the agent's active revision. When you update your agent's instructions, tools, or model settings and promote the new version, the Copilot automatically starts using it — you don't need to update or replace the embed snippet.

<Warning>
  Test your Copilot after making significant changes to the agent. A change that improves behavior in Studio may affect the public-facing widget in unexpected ways, especially if the instructions weren't written with a public audience in mind.
</Warning>

***

## Multiple Deployments for One Agent

A single agent can power multiple Copilot deployments simultaneously. This is useful when you want the same underlying intelligence with different surface-level configurations — different welcome messages, different tags, different placement on your site.

Each deployment is a separate channel into the same agent:

* Public homepage Copilot — welcoming, general-purpose
* Authenticated in-app assistant — more direct, assumes product context
* Customer support portal — focused on known issues and escalation paths
* Internal team tool — accesses internal knowledge sources not exposed publicly

Create each as a separate deployment so you can tailor the experience and track sessions independently.

***

## Public Deployment Checklist

Before you embed a Copilot on a public-facing site, review what your agent can do from a user's perspective. A tool that's harmless in internal testing may create risk when exposed to anonymous users.

### Review your tools

Check each tool enabled on the agent and ask: should an anonymous user be able to trigger this?

Look out for:

* **CRM or ticketing tools** that can read or modify customer data
* **Email or messaging tools** that can send outbound communications
* **Internal knowledge sources** that contain information not meant for external audiences
* **Code execution** or web access that could be misused by adversarial prompts
* **Tools with side effects** — anything that creates, updates, or deletes records in downstream systems

Disable any tool that a public user shouldn't have access to, or create a separate agent for the public Copilot with a more restricted tool set.

### Tighten your instructions

Public Copilots need stricter guardrails than internal agents. Update the instructions to:

* Define what kinds of requests the agent should refuse
* Limit when it calls tools versus answering directly from its knowledge
* Require explicit confirmation before taking any high-impact action
* Instruct it not to reveal sensitive internal information even if asked
* Set clear boundaries on tone, scope, and response length for a public audience

<Tip>
  Test your public Copilot with adversarial prompts before launch — ask it to ignore its instructions, reveal system prompts, or perform actions outside its intended scope. This surfaces instruction gaps before your users find them.
</Tip>

### Plan your deployment surfaces

Different placements usually benefit from different deployments with different configurations. Think through each surface where you want the Copilot to appear and whether a single configuration covers all of them, or whether separate deployments with tailored instructions make more sense.

***

## Common Questions

**Can I change the appearance of the widget?**
The widget adapts to your site's theme automatically. For deeper appearance customization, create the deployment in Studio and use the available configuration options. Advanced styling may require reaching out to Scout support.

**Do I need to re-embed after updating my agent?**
No. The embed snippet points to the deployment, and the deployment always uses the agent's active revision. Update the agent, promote the revision, and the Copilot updates automatically.

**Can I restrict the Copilot to authenticated users only?**
Yes. Deploy the embed snippet only on pages behind your authentication wall. The Copilot widget itself doesn't enforce authentication — your application does.

**How do I track which sessions came from the Copilot?**
Use the `tags` attribute on the embed element: `tags='["source:copilot", "surface:homepage"]'`. Sessions with these tags appear in your agent's History tab in Studio where you can filter and analyze them.

**Can I have the same Copilot on multiple pages?**
Yes. Paste the same embed snippet on as many pages as you need. If you want to track sessions per page, use tags to identify the source page.