> 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).

# Contextual Copilot

Contextual Copilot chat UI add-on for AI agents with sidebar, tool execution, and Human In The Loop (HITL) support.

The Contextual Copilot add-on (`Umbraco.AI.Agent.Copilot`) provides an interactive AI assistant sidebar in the Umbraco backoffice, scoped to the content or media item currently being edited. It depends on `Umbraco.AI.Agent.UI` (shared chat components), which in turn depends on the Agent Runtime (`Umbraco.AI.Agent`).

{% hint style="info" %}
In the Umbraco backoffice itself, this add-on's sidebar and its agent surface are both labeled **Copilot**. This documentation uses **Contextual Copilot** to distinguish it from [Copilot Workspace](/ai-in-umbraco/17.latest/add-ons/copilot-workspace.md) (`Umbraco.AI.Agent.Copilot.Workspace`), a separate add-on for broader, persisted, cross-site conversations. Where a step below tells you to tick or select an on-screen option, that option is exactly as labeled in the backoffice.
{% endhint %}

## Installation

Install the Contextual 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 Contextual 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

### Step 1: Install the Contextual Copilot Package

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

### Step 2: Create an Agent for the Contextual Copilot Surface

In the backoffice, navigate to the **AI** section > **Agents** and create an agent. To make it available in the Contextual Copilot sidebar, tick **Copilot** in the agent's **Surfaces** selection. This is the option registered by the Contextual Copilot add-on, as distinct from the **Copilot Workspace** option next to it.

The Contextual 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, Contextual Copilot uses Auto mode (see [Usage](/ai-in-umbraco/17.latest/add-ons/agent-copilot/copilot.md)) to route each prompt to the most relevant agent.

### Step 3: Access Contextual Copilot

The Contextual Copilot sidebar appears in sections that declare compatibility with it (Content and Media out of the box). Open a content or media item and click the floating **AI Assistant** button in the bottom-right corner of the workspace 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, Contextual Copilot, 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 Contextual Copilot package provides:

* Sidebar host and the floating trigger button shown in supported workspaces
* The `copilot` agent surface (`CopilotAgentSurface`)
* Example frontend tools

## Documentation

| Section                                                                            | Description                       |
| ---------------------------------------------------------------------------------- | --------------------------------- |
| [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

* [Copilot Workspace](/ai-in-umbraco/17.latest/add-ons/copilot-workspace.md) - Broader, cross-site AI conversations with persisted history and projects
* [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.