> 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/add-ons/copilot-workspace/copilot-workspace.md). # Usage Using Copilot Workspace: conversations, projects, the context panel, and archived conversations. Copilot Workspace is a full backoffice section for AI conversations, opened via the **Copilot** entry in the section rail. Unlike the [Contextual Copilot](/ai-in-umbraco/add-ons/agent-copilot/copilot.md) sidebar, conversations here are not tied to a single content or media item. They persist across sessions and can span whatever you need help with. ## The Workspace Layout Copilot Workspace uses a three-region layout: * **Sidebar** - Projects and recent conversations, with search. * **Center** - The active chat. * **Context panel** - Instructions, contexts, and resources grounding the current conversation (collapsible). Before you open a conversation, the sidebar shows a launcher. Use it to start a new chat or pick up a recent one: ![The Copilot Workspace launcher with New chat, New project, and a list of recent conversations](https://583970477-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCHKT9bQhbR3swAdBvil4%2Fuploads%2Fgit-blob-2d89a9e8678f6a23ac8a7692e046f70ff065f2cf%2Fcopilot-workspace-launcher.png?alt=media) ## Starting a Conversation Use **New chat** to start an unsaved conversation, or **New chat in a project** to start one inside a specific [project](#projects). A conversation is only persisted once you send its first message. ## Conversations Each conversation in the sidebar supports the following actions via its **...** menu: * **Pin** / **Unpin** - Keep important conversations at the top. * **Rename** - Give a conversation a custom title (conversations are auto-titled otherwise). * **Move to project...** - Attach or move a conversation to a project. * **Archive** - Remove a conversation from the active list without deleting it. * **Delete** - Permanently remove a conversation. ![The conversation actions menu, showing Pin, Rename, Move to project, Archive, and Delete](https://583970477-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCHKT9bQhbR3swAdBvil4%2Fuploads%2Fgit-blob-6a659f36fec34b5847b34f5736231b0f29748dc6%2Fcopilot-workspace-conversation-actions.png?alt=media) ### Archived Conversations Archiving hides a conversation from your active lists without deleting it. Archived conversations are grouped under **Archived** in the sidebar and are read-only until restored: ![The Archived group in the sidebar, with a conversation showing a read-only notice](https://583970477-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCHKT9bQhbR3swAdBvil4%2Fuploads%2Fgit-blob-c5cad98849dbd21d5b42e5848de537173c53f02d%2Fcopilot-workspace-archived.png?alt=media) ## Projects A project groups related conversations under shared instructions and reusable context. Anything you attach to a project is inherited by every conversation inside it: * **Instructions** - Guidance applied to every conversation in the project (for example, "Talk like a pirate" or brand-specific tone rules). * **Contexts** - Existing [AI Contexts](/ai-in-umbraco/concepts/contexts.md), such as brand voice guidelines. * **Resources** - Attached content, files, or other resources, each with an injection mode (for example, **Always** included, or resolved on demand). ![The project editor, showing Description, Instructions, Contexts, and Resources fields](https://583970477-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCHKT9bQhbR3swAdBvil4%2Fuploads%2Fgit-blob-17c0e4d1367b97a4199f71a01337fb877ae566c4%2Fcopilot-workspace-project.png?alt=media) Create a project with **New project** in the sidebar, or via the top-level create menu. Deleting a project detaches its conversations rather than deleting them. ## The Context Panel While chatting, the context panel on the right shows what's grounding the current conversation. This includes the project's instructions, contexts, and resources (if the conversation belongs to a project), plus anything attached directly to the conversation itself. Collapse it for more chat space, or expand it to review or edit what the agent can see: ![The three-region Copilot Workspace layout: sidebar, chat, and an expanded context panel showing Instructions, Contexts, and Resources](https://583970477-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCHKT9bQhbR3swAdBvil4%2Fuploads%2Fgit-blob-77b188643474b897f0c5403ed67b181b6c662109%2Fcopilot-workspace-chat.png?alt=media) ## Backend Tools and Approvals Copilot Workspace isn't scoped to a single open item. Its agents on the `copilot-workspace` surface can be granted broader tool permissions than Contextual Copilot allows. This includes backend tools that create, update, publish, or delete content and media anywhere on the site. Copilot Workspace only stops to ask for approval when a change is something editors can't undo themselves: | Tier | What happens | Built-in tools | | ---------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Runs without asking | Saves a draft. Version history can roll it back, so the agent doesn't stop. | `create_umbraco_content`, `update_umbraco_content`, `set_umbraco_content_value`, `clear_umbraco_content_value`, `add_umbraco_content_item`, `remove_umbraco_content_item`, `move_umbraco_content_item`, `create_umbraco_media`, `update_umbraco_media` | | Asks for approval once | Changes what the public sees, or removes an item. The editor approves or denies the named action. | `publish_umbraco_content`, `unpublish_umbraco_content`, `delete_umbraco_content`, `delete_umbraco_media` | The approval message names the item, for example "Publish 'Home', making it live." Delete tools move items to the recycle bin. Tools only run if the agent is allowed to use them. Both tiers belong to the destructive `content-write` and `media-write` scopes, so an agent needs those scopes (or the specific tools) granted first. Custom tools choose their tier with the [`RequiresApproval`](/ai-in-umbraco/extending/tools/creating-a-tool.md#step-3-configure-the-aitool-attribute) setting. {% hint style="warning" %} Review tool permissions carefully for agents used in Copilot Workspace. See [Agent Tool Permissions](/ai-in-umbraco/add-ons/agent/permissions.md) for how to scope destructive tools to the right agents and user groups. {% endhint %} ## Configuring Copilot Workspace Agents Any agent in the **AI > Agents** backoffice section that is associated with the **Copilot Workspace** surface becomes available in the Workspace. Tick **Copilot Workspace** in the agent's **Surfaces** selection to opt it in. Unlike Contextual Copilot, where availability also depends on the current section and entity type, Copilot Workspace availability depends only on this surface opt-in. An agent enabled here is available in every conversation and project. If no agent is enabled, the Workspace shows an empty state guiding you to enable one. If multiple agents are enabled, Copilot Workspace can auto-select the most relevant one per prompt, the same way [Auto Mode](/ai-in-umbraco/add-ons/agent-copilot/copilot.md#auto-mode-and-agent-routing) works for Contextual Copilot. ## Related * [Contextual Copilot](/ai-in-umbraco/add-ons/agent-copilot/copilot.md) - The contextual sidebar, scoped to the item you have open * [Agent Tool Permissions](/ai-in-umbraco/add-ons/agent/permissions.md) - Scoping tool access, including destructive backend tools * [AI Contexts](/ai-in-umbraco/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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.umbraco.com/ai-in-umbraco/add-ons/copilot-workspace/copilot-workspace.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.