> 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
Agents are suited for tasks with clear goals, that require tools or files, and may continue through multiple steps. The entry point is the left sidebar \[Work], not the top tabs in the old tutorial.
{% hint style="success" %}
The easiest setup 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 you need precise control, open the Agent edit window or manually adjust it in \[Settings].
{% endhint %}
### What makes up the workspace
| Section | Function | When to pay attention |
| ----------------- | ------------------------------------------------ | -------------------------------------------------------------------------- |
| Agent | Save roles, models, prompts, and capabilities | When the same kind of work needs to be repeated |
| Task | A continuous record of work | Open a separate task for each goal to keep the context intact |
| Working directory | The range of files the Agent can handle directly | File tasks such as code, information organization, and document generation |
| Input area | Send goals, attachments, and invoke tools | Start a task or add more requirements |
| Right panel | View status, files, subtasks, and message flow | Track long tasks, inspect deliverables, or troubleshoot |
### 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], choose a running mode first in \[Basic Info], then complete the four setup steps: system prompt, skills, and knowledge base. The running mode cannot be changed after creation.
{% endstep %}
{% step %}
#### 2. Choose the working directory
When you need to work with 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, which prevents the Agent from searching back and forth among unrelated directories.
{% endstep %}
{% step %}
#### 3. Describe the task with the desired outcome
Tell the Agent what to deliver, which materials it can use, what constraints there are, and how to know when it's 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 panel
The \[Status] view 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 Tips
Agent execution depends on Cherry Studio's API Gateway. If the gateway is not enabled, the app will prompt you to \[Enable and Start] it; 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 has to be exposed to the network. Keep the default local-only use; only copy the URL and API key when you explicitly want other programs to call it.
{% 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 scope of materials, or different permissions: split into multiple Agents.
* One goal requires parallel research or multi-step collaboration: first let one Agent use sub-agents or workflows; there is no need to manually create many Agents right away.
### User case: organizing project materials
A product manager places the requirements spec, interview notes, and competitor materials in the same directory, creates a "Requirements Organization" Agent, binds a product knowledge base, and uses \[Confirm Each Step] permissions. The Agent first reads the materials, then writes the requirement list and questions to be confirmed into a new file. The product manager directly edits the text in the right-side \[Files] panel, while the original materials remain unchanged.
Why can't the Agent see the capabilities I just bound?
Edits to the Agent are saved automatically. Replies that are currently being generated will not be interrupted; changes to the model, skills, MCP, and knowledge base will take effect starting from the next message. If they still do not appear, first confirm the capability is enabled, then send a new message.
Will deleting the working directory also delete the disk files?
When you delete a working directory in the task list, only the directory record in Cherry Studio and the task records under that directory are removed; the actual directory on disk is not deleted. File operations performed by the Agent during task execution are still subject to the selected permission mode.
Will deleting the working directory also delete the disk files?
When you delete a working directory in the task list, only the directory record in Cherry Studio and the task records under that directory are removed; the actual directory on disk is not deleted. File operations performed by the Agent during task execution are still subject to the selected permission mode.
---
# 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=&goal=
```
`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.