> 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/copilot.md).

# Copilot Usage

The Copilot is an AI-powered assistant that appears as a sidebar in the Umbraco backoffice. It provides conversational AI capabilities directly within your content editing workflow.

## Accessing the Copilot

The Copilot is available in the **Content** and **Media** sections:

1. Look for the **AI Assistant** button in the header
2. Click to toggle the sidebar open/closed
3. The button shows an active state when the sidebar is open

{% hint style="info" %}
The Copilot button only appears in sections where it's relevant (Content and Media).
{% endhint %}

![The AI Copilot sidebar showing a conversation in the Umbraco backoffice](/files/pcVC3G9zrZnoPBhUX9cV)

## Features

### Conversational Interface

Chat naturally with the AI assistant:

* Ask questions about your content
* Request suggestions and improvements
* Get help with writing tasks
* Multi-turn conversations maintain context

### Content Awareness

The Copilot understands your current editing context:

* Current content item being edited
* Property values and structure
* Content type information
* Media items and relationships

### Tool Execution

Agents can execute tools to interact with Umbraco:

* Read property values
* Update content fields
* Navigate to related content
* Perform custom actions

### Human-in-the-Loop Approval

For sensitive operations, the Copilot requests confirmation:

The approval workflow ensures editors maintain control over content changes.

![The Human-in-the-Loop approval dialog with Approve and Deny buttons](/files/PbKy6a8RrFlBblppp4WT)

## Configuring Copilot Agents

Agents power the Copilot's capabilities. Any agent in the **AI > Agents** backoffice section that is associated with the **Copilot** surface becomes available inside the sidebar.

### Opting an agent into the Copilot

The Copilot package registers an agent surface via `CopilotAgentSurface` with `SurfaceId = "copilot"`. When editing an agent in the backoffice, tick **Copilot** in the **Surfaces** selection to expose it to the sidebar. Internally this adds `"copilot"` to the agent's `SurfaceIds` collection, and the sidebar loads agents filtered by that surface ID.

If only one agent is associated with the Copilot surface, the sidebar uses it directly. If multiple agents are available, the Copilot uses Auto mode to route each prompt (see below).

### Agent Instructions

Configure agent instructions for Copilot behavior:

```
You are an AI assistant helping editors create content in Umbraco.

Your capabilities:
- Suggest improvements to content
- Help with writing and editing
- Answer questions about the current page
- Update properties when asked

Always be helpful and concise.
```

## Auto Mode and Agent Routing

When multiple agents are available on a surface, the Copilot uses "Auto" mode to automatically select the best agent for each user message. Auto mode works by sending the user's prompt to a classifier model that picks an agent based on each agent's name and description.

### Classifier Profile

By default, the classifier uses the default chat profile, which may be a powerful (and expensive) model. Since classification only returns a single GUID, you can configure a cheaper or faster model specifically for this task:

1. Navigate to the **AI** section > **Settings**
2. Set the **Classifier Chat Profile** to a lightweight model (e.g., GPT-4o Mini, Claude Haiku)
3. Save

See [Settings](/ai-in-umbraco/17.latest/concepts/settings.md#classifier-chat-profile) for more details on the fallback chain.

## Related

* [Agent Runtime](/ai-in-umbraco/17.latest/add-ons/agent.md) - Backend agent functionality
* [Frontend Tools](/ai-in-umbraco/17.latest/add-ons/agent-copilot/frontend-tools.md) - Custom tool integrations


---

# 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/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.