> This page is for Workspace app.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cloudraker.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server.

# Agents overview

A **Paperwork agent** (an **agent**, for short) is an AI teammate with a job to
do. You write down the goal, list the outcomes (tasks) you want, and choose
which [actions](/workspace/actions/overview) the agent may run. When someone
starts a run inside a space, the agent works through the tasks toward that
goal. It reads files, searches the knowledge graph, and dispatches actions. It
pauses for your approval at the gates you set.

Agents are **org-level and reusable**. An agent is not tied to one space.
You make it available to a [space type](/workspace/spaces/space-types). Every space
created from that type can run it.

> **Note**
>
> Agent definitions are **admin-only**. The library lives at **Agents** in the
> sidebar. If you are not an admin, you see "You need an admin role to manage
> agents." Running an agent happens inside a space. Anyone who can contribute
> there can run one. See [Run an agent](/workspace/agents/run-an-agent).

## Two run types — keep them straight

A space has both an **Agents** tab and an **Actions** tab. They are not the
same thing.

| Surface         | What it runs                                                                                                    |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| **Agents** tab  | An **agentic run**. The agent pursues a goal across multiple tasks and actions, and pauses for approvals.       |
| **Actions** tab | A **single-action run**. You run one [action](/workspace/actions/run-an-action) over some files, with no agent. |

This page and the rest of this section cover **agent runs** (the Agents tab).
To run one action over some files, see
[Run an action](/workspace/actions/run-an-action).

## The agents library

Open **Agents** to see every agent in your organization. The list has
these columns:

| Column          | What it shows                                                                             |
| --------------- | ----------------------------------------------------------------------------------------- |
| **Name**        | The agent's name. Click it to open the editor.                                            |
| **Status**      | **draft**, **active**, or **archived**.                                                   |
| **Space types** | The space types this agent is bound to, or **All space types** if it is not bound to any. |
| **Actions**     | How many actions the agent may run.                                                       |
| **Updated**     | When the agent last changed.                                                              |

Use **New agent** to start one. See
[Build an agent](/workspace/agents/build-an-agent) for the editor walkthrough.

## The lifecycle

Every agent carries a status. It moves through three states.

#### Draft

Being built. You edit the goal, tasks, and actions freely. A draft cannot
run in a space yet.

#### Active

Runnable. You publish a draft by clicking **Activate** in the editor.
Activation validates the agent first. Only a valid agent can be
activated: it needs a name plus a title on every task. **Only active
agents appear in a space's run picker.**

#### Archived

Retired. The agent is kept for history but is no longer offered for new
runs. Archive an agent from the editor when a process is replaced or no
longer needed.

## Runs are always started by a person

There is **no trigger or scheduling system**. An agent never runs on its own,
on a timer, or in response to an event. A person starts every run from a
space's **Agents** tab.

## Where to go next

#### [Build an agent](/workspace/agents/build-an-agent)

Set the goal, add tasks, choose actions and approvals, then activate.

#### [Run an agent](/workspace/agents/run-an-agent)

Start a run in a space and follow the live timeline.

#### [Approvals and steering](/workspace/agents/approvals-and-steering)

Approve or reject the agent's proposals, steer it mid-run, and control the run.

#### [Actions](/workspace/actions/overview)

The installable work that an agent, or you, can run over files.