> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/work/file-library/use-in-maigpt.md).

# Use Workspaces in MaiGPT

Start a MaiGPT conversation from a file workspace so AI can find files, read them in full, and then answer. Learn how workspace guides, automatic filing of conversation attachments, and automatic savi

Once you attach a workspace to MaiGPT, you no longer need to upload files one by one. AI finds the files relevant to your question, reads them in full, and answers with source citations. Attachments you upload in the conversation and files AI generates are also saved automatically to the file library.

## Use Case <a href="#use-case" id="use-case"></a>

A sales representative clicks <mark style="color:blue;">Start a conversation here</mark> in the “A1 Launch Proposal” workspace. She first asks, “What files are in this workspace?” to check what AI can access, then asks, “Summarize the differences between the plans in the Q3 quotation.” AI reads the quotation and presents a comparison table. When the customer sends a new requirements document, she drags it directly into the conversation, and the system displays “Filed in ‘A1 Launch Proposal’.” She then asks AI to write a proposal outline as a Word file based on the specifications and the new requirements. The file is saved automatically to her temporary storage, with details identifying the source workspace and conversation.

***

## Start a Conversation from a Workspace <a href="#start-chat" id="start-chat"></a>

### 1. Start a Conversation Here <a href="#start-from-workspace" id="start-from-workspace"></a>

Open the workspace you want to use in the file library, then click <mark style="color:blue;">Start a conversation here</mark>.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-9f16f323c0c88d68d18152cfccf04e075a7aaeaf%2Ffile-library-start-chat.png?alt=media" alt="Start a conversation here button at the top of a workspace"><figcaption><p>Start a conversation here appears above the workspace list</p></figcaption></figure>

### 2. Confirm the Workspace Is Attached <a href="#workspace-mounted" id="workspace-mounted"></a>

When MaiGPT opens, a workspace tag (such as “A1 Launch Proposal”) appears below the input box, indicating that the workspace is attached to this conversation. Click <mark style="color:blue;">×</mark> next to the tag to detach it.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-59acf502eacf4cb74dfc00e95e0571dbb0ceb44c%2Ffile-library-maigpt-mounted.png?alt=media" alt="Attached workspace tag displayed below the MaiGPT input box"><figcaption><p>The workspace tag below the input box</p></figcaption></figure>

{% hint style="info" %}

* You can attach one workspace to a conversation at a time.
* You can also click <mark style="color:blue;">Start a conversation</mark> in the file details, or select multiple files and click <mark style="color:blue;">Start a conversation</mark>, to bring only the selected files into the conversation.
  {% endhint %}

***

## Let AI Read Files and Answer <a href="#ai-reads-files" id="ai-reads-files"></a>

With a workspace attached, you can ask questions using file names or descriptions of their contents:

| Try asking                                                        | What AI does                                                             |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------ |
| “What files are in this workspace?”                               | Lists folders and files so you can check what it can access              |
| “Summarize the differences between the plans in the Q3 quotation” | Finds the quotation, reads it in full, and answers with source citations |
| “Compare the specifications with the competitor presentation”     | Reads multiple files as needed and summarizes the differences            |

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-76bfa236d19a88636d2fc0ca8ea7ce9a12f69af8%2Ffile-library-maigpt-read.png?alt=media" alt="AI presents a plan comparison table after reading the Q3 quotation, with workspace attachments displayed above the input box"><figcaption><p>AI shows which files it has read; files it has read appear as attachments labeled “From workspace”</p></figcaption></figure>

File reading rules:

* **AI can read up to 5 files at a time**. If you need more files, split your questions across several requests.
* **Files that are still being parsed or failed to parse cannot be read**. Wait for parsing to finish before asking.
* **If the file name is ambiguous**, AI asks you to confirm which file you mean.
* **If the workspace has more than 300 items**, AI first sees a folder-level overview, then searches deeper based on your question.
* For members with view-only access, AI can still read files but will not modify them.

***

## Workspace Guide <a href="#workspace-guide" id="workspace-guide"></a>

Each workspace has a <mark style="color:blue;">Workspace guide</mark> describing its contents and what each file is for. AI refers to this guide when answering. After opening a workspace, click <mark style="color:blue;">Workspace guide</mark> (the document icon) in the toolbar at the top to open it.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-7e44520401145484a5766f50ccee59803925f4eb%2Ffile-library-instructions-entry.png?alt=media" alt="Toolbar at the top of a workspace, with the pointer over the document icon showing the Workspace guide tooltip"><figcaption><p>The Workspace guide is in the toolbar to the right of Start a conversation here</p></figcaption></figure>

### Use Case <a href="#workspace-guide-use-case" id="workspace-guide-use-case"></a>

A sales representative opens the workspace guide for “A1 Launch Proposal” and sees that the system has already organized a file map based on the quotation and the specifications. She wants AI to add a reminder when answering about pricing, so she clicks <mark style="color:blue;">Edit</mark> and adds “Pricing follows the Q3 quotation; remind the user when its validity period has expired.” She first clicks <mark style="color:blue;">Save</mark> below the input box to confirm the draft, then clicks <mark style="color:blue;">Save</mark> at the bottom right of the window. The screen displays “Workspace guide saved,” and her name and the update time are recorded next to the guide. A few days later, a colleague uploads a competitor comparison presentation. When she opens the guide again, she sees a notice that an update suggestion has been generated. She clicks <mark style="color:blue;">Apply suggestion</mark> to review the new content first, and after confirming it, clicks <mark style="color:blue;">Save</mark>. The guide then returns to automatic maintenance.

### View the Guide <a href="#view-workspace-guide" id="view-workspace-guide"></a>

The guide content appears at the top of the window, and the information about the last update appears on the right:

* **Guides updated automatically by the system**: Show only <mark style="color:blue;">Last updated:</mark> and the time.
* **Guides saved by someone with the bottom-right Save button** (including saves after applying a suggestion): The name of the person who last saved it is added before the time, for example, “Alex Wang・Last updated: 2026-10-25 10:51:55,” until the next automatic update of the guide by the system.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-863dd7cef93a69ce2a4ff8eee5c5de59227f8c8c%2Ffile-library-instructions-auto.png?alt=media" alt="Workspace guide window showing a system-organized file map and retrieval strategy, with only the last updated time at the top right and the Save button at the bottom right disabled"><figcaption><p>An automatically updated guide shows only the update time; Save is unavailable until you make changes</p></figcaption></figure>

When the guide has no content yet (for example, the workspace has no files), the message “No workspace guide has been set. Click ‘Regenerate’ to have AI generate a suggestion based on the existing files” appears.

### Edit, Save, and Cancel <a href="#edit-workspace-guide" id="edit-workspace-guide"></a>

Changing the guide takes two steps: first edit a draft in the window, then click <mark style="color:blue;">Save</mark> at the bottom right to actually write it.

{% stepper %}
{% step %}

### Edit the Draft <a href="#edit-draft" id="edit-draft"></a>

Click <mark style="color:blue;">Edit</mark>, and the content becomes an editable text box. When you finish, click <mark style="color:blue;">Save</mark> below the text box. This only updates the draft in the window and does not write it to the workspace yet. While you are editing, <mark style="color:blue;">Save</mark> at the bottom right is disabled; finish editing first.
{% endstep %}

{% step %}

### Confirm and Save <a href="#save-guide" id="save-guide"></a>

<mark style="color:blue;">Save</mark> at the bottom right is available only when the draft differs from the current content. After you click it, “Workspace guide saved” appears and the window closes.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-ad14cbc225db14aca341af562c15fb9c86acf3b4%2Ffile-library-instructions-draft.png?alt=media" alt="Workspace guide window showing a draft with an added answering-principles section, with the Save button at the bottom right enabled"><figcaption><p>After the draft is edited, Save at the bottom right becomes available</p></figcaption></figure>
{% endstep %}
{% endstepper %}

If you change your mind partway through, click <mark style="color:blue;">Cancel</mark> to close the window. The draft is discarded and the guide keeps its original content.

* **No automatic overwriting after a manual save**: After you save a guide, the system does not rewrite it directly when files change. Instead, it generates an update suggestion, as described in the next section.
* **Regenerate**: Click <mark style="color:blue;">Regenerate</mark>, and the system rewrites a version based on the current files and places it in the draft, displaying “New guide suggestion generated.” Click <mark style="color:blue;">Save</mark> at the bottom right to keep it; if you click <mark style="color:blue;">Cancel</mark>, nothing changes.

### Apply an Update Suggestion <a href="#apply-suggestion" id="apply-suggestion"></a>

When nobody has manually edited the guide, the system automatically rewrites it after files are imported, moved, or deleted, or attachments are filed. Multiple changes made within a short period are combined into one update. An entry labeled <mark style="color:blue;">Workspace guide automatically updated</mark> is added to the version history and can be restored.

When the guide has been saved manually, the system instead generates an update suggestion, and the notice “File changes detected. The system has generated a workspace guide update suggestion (not applied automatically because you edited the guide manually)” appears at the top of the window.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-7e38ed29321fc12ea3da0ce146cd3fcc53646480%2Ffile-library-instructions-pending.png?alt=media" alt="Workspace guide window with a yellow notice at the top about detected file changes and an Apply suggestion button, with the name of the last person to save (masked) and the last updated time on the right"><figcaption><p>When files change in a manually saved guide, an update suggestion is shown instead</p></figcaption></figure>

1. Click <mark style="color:blue;">Apply suggestion</mark> in the notice. The suggested content is placed in the draft for you to review first; it has not been written yet.
2. If it looks right, click <mark style="color:blue;">Save</mark> at the bottom right. After you apply it, the guide returns to automatic maintenance, and later file changes update it directly. Until the system's next automatic update, your name and save time still appear next to the guide.
3. To modify the suggestion first, click <mark style="color:blue;">Edit</mark>, adjust it, and then save. This counts as a manual save, and the guide does not return to automatic maintenance.

{% hint style="warning" %}
A manual save does not clear this update suggestion. Whether you save after modifying the suggestion or edit and save without handling it, the notice at the top of the window continues to appear. If you then click <mark style="color:blue;">Apply suggestion</mark>, the suggested content overwrites the changes you just saved, so check before applying it.
{% endhint %}

{% hint style="info" %}
If the system updates the suggestion again based on new file changes while you are reviewing it, clicking <mark style="color:blue;">Save</mark> displays “The suggestion has been updated. Please review the latest content before saving,” and the window loads the latest content. Review it again before applying.
{% endhint %}

### Permissions <a href="#workspace-guide-permissions" id="workspace-guide-permissions"></a>

* You need edit permission for the space to see <mark style="color:blue;">Edit</mark>, <mark style="color:blue;">Regenerate</mark>, <mark style="color:blue;">Apply suggestion</mark>, and <mark style="color:blue;">Save</mark>.
* Members with view-only access can open the workspace guide to read its content, but cannot modify it.

***

## Automatically File Conversation Attachments <a href="#attachment-filing" id="attachment-filing"></a>

When you upload a file in a conversation with a workspace attached, the file is automatically added to that workspace. The message “Filed in ‘Workspace name’” appears in the upper-right corner. If it was filed in the wrong place, click <mark style="color:blue;">Undo</mark> in the notification to undo the filing.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-60f0cee512442e5ac7af7f17e10970707b979354%2Ffile-library-attachment-archived.png?alt=media" alt="After an attachment is uploaded in the conversation, a notification shows it was filed in A1 Launch Proposal and provides an Undo button"><figcaption><p>The filing notification remains until you act on it</p></figcaption></figure>

To put the file in another workspace, say so directly in your message, for example, “Put this in the Client Project workspace.” If that workspace cannot be found or you do not have write access, the file stays in the current workspace and the system explains why.

***

## Automatically Save AI Outputs <a href="#agent-output" id="agent-output"></a>

Documents, images, and videos that AI generates in a conversation are automatically saved to <mark style="color:blue;">Temporary storage</mark> under <mark style="color:blue;">My files</mark>, so you do not need to download and organize them separately.

* **Output list on the right**: <mark style="color:blue;">Output</mark> in the panel on the right lists this conversation’s outputs chronologically. You can preview and download them. Clicking <mark style="color:blue;">Open in file library</mark> takes you to the folder containing the file and opens its details.
* **File details**: Open a generated file in temporary storage to see its <mark style="color:blue;">Source</mark>, labeled <mark style="color:blue;">Agent output</mark>, along with the <mark style="color:blue;">Source workspace</mark> and <mark style="color:blue;">Output conversation</mark>. Click the output conversation to return to the original conversation.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-c3c1a0b7ec28751ead6ea10af6e7f3b9e17cb43b%2Ffile-library-output-panel.png?alt=media" alt="The Output list in the right panel of MaiGPT shows a Word file generated by AI"><figcaption><p>The Output list in the right panel</p></figcaption></figure>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-868b4ed5cd33dc10a9f3f72c4446812e16fe4fce%2Ffile-library-agent-output-detail.png?alt=media" alt="File details in temporary storage show Agent output as the source, along with the source workspace and output conversation"><figcaption><p>Generated file details identify the source workspace and output conversation</p></figcaption></figure>

{% hint style="info" %}
You can move outputs you want to keep long term from temporary storage to a permanent workspace.
{% endhint %}

***

## Related Pages <a href="#related" id="related"></a>

* [Let AI Edit and Organize Files](https://docs.maiagent.ai/maiagent-user-guide/en/work/file-library/ai-edit.md)
* [Version History and Restoration](https://docs.maiagent.ai/maiagent-user-guide/en/work/file-library/versions.md)
* [AI Conversations](https://docs.maiagent.ai/maiagent-user-guide/en/work/maigpt/chat.md)


---

# 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.maiagent.ai/maiagent-user-guide/en/work/file-library/use-in-maigpt.md?ask=<question>&goal=<user_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.
