;
Most of what a gavAI workspace does is request-shaped — a visitor hits a page, a handler runs, a response goes back. Agents are the part of the platform that runs without a request behind it. An agent is a workspace-defined automation that the runtime drives on a schedule or on a trigger, holds a long-lived session for, and pauses for human sign-off at sensitive steps. By the end of this page you will know what an agent is, how it differs from a webhook handler, what it can and cannot reach, and how approval gates fit in.
## A first agent
Conceptually, an agent is a name plus a recipe. The name is how operators identify it in the console and the API; the recipe is the ordered set of steps it takes when it runs. A minimal one looks like this:
```json agent.json theme={null}
{
"name": "Weekly digest",
"trigger": { "kind": "schedule", "cron": "0 9 * * 1" },
"steps": [
{ "read": "runQuery", "args": { "table": "orders", "since": "7d" } },
{ "read": "computed", "args": { "expression": "summarize(rows)" } },
{ "write": "sendEmail","args": { "template": "weekly-digest" } }
]
}
```
Three things are happening. A schedule trigger fires the run; the run performs ordered steps; each step is either a read (against the workspace's data or a computed expression) or a write (a capability invocation with the steps above as input). The runtime owns the session, the audit trail, and the failure handling — the recipe just declares the shape of the work.
## The mental model: scheduled session
Think of an agent as a **scheduled session against the runtime**. When the trigger fires, the platform opens a session for the agent, authenticates it as a workspace-scoped principal, and feeds it the steps in order. Each step runs inside the same isolation boundary as a normal page request — the agent reads from the same workspace database, dispatches the same capabilities, hits the same rate limits.
```mermaid theme={null}
sequenceDiagram
participant T as Trigger
participant R as Runtime
participant C as Capabilities
participant A as Audit log
T->>R: schedule fires
R->>R: open agent session
R->>C: step 1 (read)
C-->>R: rows
R->>A: append audit entry
R->>C: step 2 (read)
C-->>R: computed value
R->>A: append audit entry
R->>C: step 3 (write — needs approval)
R-->>R: create approval record, pause
Note over R: ... operator approves ...
R->>C: dispatch write
C-->>R: result
R->>A: append audit entry
R-->>T: run complete
```
Two properties fall out of that shape:
* **An agent has no privileges beyond the workspace.** It cannot reach another workspace's data; it cannot mint a token for itself; it cannot bypass policy. The same boundaries that hold for a human caller hold for the agent's session.
* **Every step is auditable.** Reads and writes both append to the workspace's audit log under the agent's principal. The log records what the agent looked at, not only what it changed.
## What an agent can do
An agent's recipe is built from a small set of *agent capabilities*. They split into reads (gather context without changing state) and writes (dispatch a side effect or change state).
The split between reads and writes is the basis for the approval system below — writes are the steps that get gated.
## Triggers
An agent fires on a trigger. Triggers are declarative and live on the agent definition; you do not write listener code.
Cron-style schedule expression evaluated in the workspace's configured timezone.An event family from the platform's event stream — `forms.submitted`, `payments.succeeded`, and the others listed in the [event catalogue](/webhooks/events).Operator-initiated. The agent is dormant until a human starts a run from the console or the API.Implicit — fires when an approval the agent created earlier is decided. The next steps run inside the original session.
A single agent can declare multiple triggers. The runtime opens a separate session per fired trigger, so two concurrent triggers do not race against each other's state.
## Sessions, runs, and replay
A *run* is one execution of the agent's recipe. The runtime gives each run a stable id, a session token scoped to that run, and a position cursor that advances as steps complete. If the session is disconnected mid-run — a deploy, a transient network failure — the run resumes from the cursor on reconnect rather than restarting from step one. Steps that already wrote are not re-dispatched; the runtime knows because the audit chain already recorded the result.
This matters for two reasons:
**Long-running agents are safe.** A run that spans hours of operator review at an approval gate does not lose progress when infrastructure churns underneath it.**Replay is a debugging tool.** Operators can fetch a finished run, replay the read steps against current state, and see how the agent would behave today without dispatching any writes. Useful for diagnosing why an agent made a decision a week ago.
## Approval gates
Writes can be gated. A step marked `requires_approval` does not dispatch when the run reaches it — instead, the runtime opens an [approval record](/concepts/approvals), pauses the session, and waits. An operator approves or denies; the run continues or stops accordingly.
The decision is recorded in the run's audit chain alongside the principal who made it. That is the surface a workspace owner uses to answer "did anyone authorize this?" after the fact.
## When to use an agent (and when not to)
Use an agent when:
The work is **periodic** (a nightly report) or **event-shaped** (handle the submission stream from a high-volume form). Both fit the trigger model cleanly.The work needs **stateful progress** across multiple capability calls — gather context, decide, then dispatch. A webhook handler that has to re-fetch context on every retry is doing this manually.A step needs **human review** before it dispatches. Agents are the only surface where the platform owns the approval gate; everywhere else you would build the queue yourself.
Don't use an agent when:
The work is **request-shaped**. A capability call on a page submission is simpler — let the page invoke the capability directly.The work is **outside the workspace**. Agents cannot reach across workspaces; orchestration that needs to coordinate two workspaces belongs in your own code, calling the API as two separate clients.The work is **fire-and-forget with no review**. A webhook subscription is the simpler surface — agents pay for the session and audit overhead that you don't need in that case.
## Related
The action-graph surface agents invoke for multi-step writes.
How agents pause for human sign-off and how policy decides which steps need it.
Endpoints to create, activate, deactivate, and inspect agents and their runs.
The event families an agent can trigger off of.