> For the complete documentation index, see [llms.txt](https://docs.cherryai.com.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cherryai.com.cn/docs/en-us/advanced-basic/agent-workspace.md).

# Agent Workspace

An Agent is suited for tasks with clear goals, requiring tools or files, and possibly spanning multiple steps. The entry point is the left sidebar \[Work], not the top tab in the old tutorial.

{% hint style="success" %}
The easiest way to configure it is to first tell the Agent what you want to accomplish, then let it check which models, tools, knowledge bases, or channels are missing. When precise control is needed, open the Agent editing window or \[Settings] to adjust manually.
{% endhint %}

<figure><img src="/files/6381b20a242275c1221a2283d1cfc7a7be141e4b" alt="Agent 从说明交付物、选择工作目录到检查文件和结果的任务闭环图"><figcaption><p>The working directory, permissions, and completion criteria run through the entire task; when changes are needed, return to the planning stage to confirm them again.</p></figcaption></figure>

## What makes up the workspace

| Section           | Effect                                           | When to pay attention                                                   |
| ----------------- | ------------------------------------------------ | ----------------------------------------------------------------------- |
| Agent             | Save roles, models, prompts, and capabilities    | When the same kind of work needs to be repeated                         |
| Task              | A continuous work record                         | Open a separate task for each goal to keep the context.                 |
| Working directory | The range of files the Agent can directly handle | File tasks such as code, material organization, and document generation |
| Input area        | Send goals, attachments, and call tools          | Start a task or add requirements                                        |
| Right-side panel  | View status, files, subtasks, and message stream | Track long tasks, check deliverables, or troubleshoot                   |

<figure><img src="/files/aecf93d13d04d1712557ff1141528696395346ee" alt="Agent 工作区中的 Agent、模型、工作目录和右侧面板"><figcaption><p>Before starting a task, first confirm the Agent, model, working directory, and right-side panel.</p></figcaption></figure>

## Start a task

{% stepper %}
{% step %}

### 1. Open \[Work] and select an Agent

If you already have a suitable Agent, select it directly; if not, click \[Add Agent] and create one in four steps: basic information, persona, skills, and knowledge base.
{% endstep %}

{% step %}

### 2. Select the working directory

When you need to process local files, choose the directory for this task; if no files are involved, you can use the default workspace created by the app. One task corresponds to one workspace, avoiding the Agent from searching back and forth among unrelated directories.
{% endstep %}

{% step %}

### 3. Describe the task in terms of results

Tell the Agent what to deliver, what materials it can use, what restrictions there are, and what counts as done. For example:

```
Read the meeting notes in the current directory, organize the decisions, owners, and deadlines, and generate action-items.md. Do not modify the original files.
```

{% endstep %}

{% step %}

### 4. Check the process and deliverables in the right-side panel

\[Status] shows active tasks, sub-agents, workflows, and background commands; \[Files] lets you preview and edit text deliverables; after enabling Developer Mode, you can also view the \[call chain].
{% endstep %}
{% endstepper %}

## API Gateway tip

Agent operation depends on Cherry Studio's API Gateway. When the gateway is not enabled, the app will prompt \[Enable and start]; you can also go to \[Settings] → \[API Gateway] to check the port, running status, and whether local security software is blocking it.

{% hint style="warning" %}
The API Gateway is a runtime dependency for the Agent, but that does not mean the interface must be exposed to the network. Keep the default local use; only when you explicitly want other programs to call it do you need to copy the URL and API key.
{% endhint %}

## One Agent or multiple Agents

* Same role, same set of capabilities, but different tasks: reuse one Agent and create multiple tasks.
* Different roles, different material scopes, or different permissions: split into multiple Agents.
* One goal requires parallel research or multi-step collaboration: first let one Agent use sub-agents or a workflow; there is no need to manually create many Agents right away.

## User case: organizing project materials

A product manager puts the requirement spec, interview notes, and competitor materials in the same directory, creates a "Requirements Organization" Agent, binds the product knowledge base, and uses \[Step-by-step confirmation] permission. The Agent first reads the materials, then writes the requirements list and questions to be confirmed into a new file. The product manager directly revises the text in the right-side \[Files], and the original materials remain unchanged.

<details>

<summary>Why can't the Agent see the capability I just bound?</summary>

Edits to the Agent are saved automatically. The response currently being generated will not be interrupted; changes to models, skills, MCP, and knowledge bases will take effect starting with the next message. If it still does not appear, first confirm that the capability is enabled, then send a new message.

</details>

<details>

<summary>Will deleting the working directory also delete the disk files?</summary>

When deleting a working directory in the task list, only the directory record in Cherry Studio and the task records under that directory will be removed; the actual directory on disk will not be deleted. File operations performed by the Agent during task execution are still subject to the selected permission mode.

</details>


---

# 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.cherryai.com.cn/docs/en-us/advanced-basic/agent-workspace.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.