> For the complete documentation index, see [llms.txt](https://docs.zerve.ai/zerve-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zerve.ai/zerve-docs/agents-in-the-workspace/agent-modes.md).

# Agent modes

Choose how much Zerve's agent does on its own, from answering questions to running whole projects.

Zerve's agent has four modes. Each one gives the agent a different amount of independence, from answering questions without changing anything to planning and running a whole piece of work.

| Mode            | What the agent does                                                                                   | Use it when                                                                                |
| --------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Ask**         | Answers questions about your notebook, its code and its data, without changing anything               | You want an explanation or a quick answer                                                  |
| **Plan**        | Writes a step-by-step plan for you to review, and makes changes only after you approve it             | You want to agree the approach before anything changes                                     |
| **Build**       | Makes changes and runs them directly                                                                  | The task is clear and you're happy for the agent to get on with it                         |
| **Evolve Mode** | Plans the work, delegates it to specialist agents in parallel, checks the results and keeps learnings | The task is substantial: research, modeling, data pipelines or anything with several steps |

## Choosing a mode

Select a mode from the mode selector in the agent composer, or press **Shift+Tab** to cycle through them. Zerve remembers the mode you used last.

You can't change mode while the agent is working. Wait for it to finish or stop it first.

| Where             | Default mode |
| ----------------- | ------------ |
| **New threads**   | Evolve Mode  |
| **New notebooks** | Build        |

Ask isn't offered in threads, since there's no notebook for it to answer questions about.

## Ask

Ask mode is read-only. The agent can read your notebook's code, variables and outputs and answer questions about them, but it can't change anything.

If you only have view access to a notebook, the agent always works in Ask mode there.

## Plan

In Plan mode, the agent writes a plan as a list of steps for you to review before it makes any changes.

* To approve the plan, reply briefly, for example "Looks good" or "Go ahead."
* To change it, reply with what you'd like done differently. The agent revises the plan.

The agent reads your reply to decide which you meant: short replies are taken as approval, and longer, detailed replies as requests for changes.

## Build

In Build mode, the agent makes and runs changes directly, without a plan to approve first. It suits clear, well-defined tasks.

Scheduled agent runs use Build mode, since there's nobody there to approve a plan.

## Evolve Mode

Evolve Mode is the most capable mode. The agent acts as a researcher and quality checker: it plans the work, delegates it to specialist agents working in parallel, checks their results and keeps [learnings](/zerve-docs/agents-in-the-workspace/learnings.md) that persist across sessions.

Evolve Mode is also the agent every [superagent](/zerve-docs/superagents/superagents.md) worker uses.

See [Evolve Mode](/zerve-docs/agents-in-the-workspace/evolve-mode.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.zerve.ai/zerve-docs/agents-in-the-workspace/agent-modes.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.