Skip to main content
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:
agent.json
{
  "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. 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. 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:

​
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, 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: Don’t use an agent when: