Skip to navigation

Agents overview

What a Paperwork agent is, how it moves from draft to active, and why every run starts with a person.
View as Markdown

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 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. Every space created from that type can run it.

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.

Two run types — keep them straight

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

SurfaceWhat it runs
Agents tabAn agentic run. The agent pursues a goal across multiple tasks and actions, and pauses for approvals.
Actions tabA single-action run. You run one 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.

The agents library

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

ColumnWhat it shows
NameThe agent’s name. Click it to open the editor.
Statusdraft, active, or archived.
Space typesThe space types this agent is bound to, or All space types if it is not bound to any.
ActionsHow many actions the agent may run.
UpdatedWhen the agent last changed.

Use New agent to start one. See Build an agent for the editor walkthrough.

The lifecycle

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

1

Draft

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

2

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.

3

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