> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/ai-in-umbraco/17.latest/add-ons/agent-copilot.md).

# Agent Copilot

The Agent Copilot add-on (`Umbraco.AI.Agent.Copilot`) provides an interactive AI assistant sidebar in the Umbraco backoffice. It depends on `Umbraco.AI.Agent.UI` (shared chat components), which in turn depends on the Agent Runtime (`Umbraco.AI.Agent`).

## Installation

Install the Copilot package — `Umbraco.AI.Agent.UI` and `Umbraco.AI.Agent` are pulled in transitively:

{% code title="Package Manager Console" %}

```powershell
Install-Package Umbraco.AI.Agent.Copilot
```

{% endcode %}

Or via .NET CLI:

{% code title="Terminal" %}

```bash
dotnet add package Umbraco.AI.Agent.Copilot
```

{% endcode %}

{% hint style="info" %}
`Umbraco.AI.Agent.Copilot` depends on `Umbraco.AI.Agent.UI`, which depends on `Umbraco.AI.Agent`. Installing Copilot installs all three packages.
{% endhint %}

## Features

* **Sidebar Chat UI** - Conversational interface in the backoffice
* **Content Awareness** - Understands current editing context
* **Tool Execution** - Frontend tools execute in the browser
* **HITL Approval** - Human-in-the-loop confirmation for actions
* **AG-UI Integration** - Real-time streaming responses
* **Entity Selector** - Target specific content items

## Quick Start

### 1. Install the Copilot Package

```bash
dotnet add package Umbraco.AI.Agent.Copilot
```

### 2. Create an Agent for the Copilot Surface

In the backoffice, navigate to the **AI** section > **Agents** and create an agent. To make it available in the Copilot sidebar, tick **Copilot** in the agent's **Surfaces** selection.

The Copilot surface is registered by `CopilotAgentSurface` with `SurfaceId = "copilot"`. At runtime the sidebar loads only agents whose `SurfaceIds` contains `"copilot"`. If more than one agent matches, the Copilot uses Auto mode (see [Copilot Usage](/ai-in-umbraco/17.latest/add-ons/agent-copilot/copilot.md)) to route each prompt to the most relevant agent.

### 3. Access the Copilot

The Copilot sidebar appears in sections that declare compatibility with it (Content and Media out of the box). Click the **AI Assistant** button in the backoffice header to toggle the sidebar.

## Package Architecture

```
┌───────────────────────────────────────────────────┐
│                 Umbraco.AI.Agent                   │
│  (Backend APIs, Agent Definitions, AG-UI streaming)│
└───────────────────────────────────────────────────┘
                        ▲
                        │ depends on
                        │
┌───────────────────────────────────────────────────┐
│               Umbraco.AI.Agent.UI                  │
│  (Shared chat components, frontend tool manager)   │
└───────────────────────────────────────────────────┘
                        ▲
                        │ depends on
                        │
┌───────────────────────────────────────────────────┐
│            Umbraco.AI.Agent.Copilot                │
│  (Sidebar, Copilot surface, example tools)         │
└───────────────────────────────────────────────────┘
```

The Agent package provides:

* Agent CRUD operations
* AG-UI streaming endpoints (`StreamAgentAGUIAsync`)
* Backend tool execution
* Management API

The Agent UI package provides:

* Shared chat element (`<uai-chat>`)
* Frontend tool manager and executor
* HITL approval infrastructure and the `uaiAgentFrontendTool` / `uaiAgentToolRenderer` manifest types

The Copilot package provides:

* Sidebar host and backoffice header app
* The `copilot` agent surface (`CopilotAgentSurface`)
* Example frontend tools

## Documentation

| Section                                                                            | Description                       |
| ---------------------------------------------------------------------------------- | --------------------------------- |
| [Copilot Usage](/ai-in-umbraco/17.latest/add-ons/agent-copilot/copilot.md)         | Using the chat interface          |
| [Frontend Tools](/ai-in-umbraco/17.latest/add-ons/agent-copilot/frontend-tools.md) | Creating browser-executable tools |

## Related

* [Agent Runtime](/ai-in-umbraco/17.latest/add-ons/agent.md) - Backend agent functionality
* [Add-ons Overview](/ai-in-umbraco/17.latest/add-ons/add-ons.md) - All add-on packages
* [AI Contexts](/ai-in-umbraco/17.latest/concepts/contexts.md) - Brand voice and guidelines


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.umbraco.com/ai-in-umbraco/17.latest/add-ons/agent-copilot.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.