Agent jobs
Not all agent work is a conversation. Most of it should not be. A job is work submitted to the estate and answered for, whether anyone is watching or not, and it is the unit that makes an agent estate operable rather than interactive.
What a job is
A job carries a specification and acquires a history. The specification names what to run and what it may consume:
| The spec names | Meaning |
|---|---|
| Kind | A single workflow graph, or a team, where a whole formation is compiled into the run |
| What to run | The graph or the formation to execute |
| Initial state | The inputs the run starts from |
| Affinity | A placement hint, for work that wants to be near something |
| Priority | Where it sits against other queued work |
| Retries | How many times a failure is worth repeating |
| Budget | The ceiling on every consumable dimension |
Admission happens before execution, and can refuse
This is the part that distinguishes a governed job plane from a queue.
A submitted job is admitted or rejected before anything runs, and admission consults the same net-potential-gain gate that governs consequential actions elsewhere. A job whose projected cost outweighs its projected value is rejected terminally, with a recorded reason. It does not get queued and quietly starved; it gets an answer.
The cost estimate comes from the job's own declared budget, so the gate is reasoning about the work the submitter actually asked for.
The lifecycle, and why it cannot be skipped
Figure AJ1: the job lifecycle. Rejected, completed, dead letter and cancelled are terminal. Cancellation is reachable from every non-terminal state, so a job is always stoppable. The legal transitions live in one table that the persistence layer itself enforces, which is why an illegal flip cannot be written: the guard is not in the caller's discipline, it is in the write path.
Every transition writes a hash-chained event, so the history of a job is tamper-evident rather than a log someone could quietly tidy.
Placement, and honesty about it
A job is placed before it is dispatched, and placement can choose a peer cell. Where remote enactment is wired, the job moves. Where it is not, the choice is recorded and the job runs locally, rather than the system pretending it dispatched somewhere it did not.
That distinction is worth knowing during an evaluation: the placement decision is always real and always recorded, and whether it is enacted depends on the deployment.
Binding a job to something runnable
Between placement and execution the job is bound to an executable graph:
- A single-graph job resolves its graph from the catalog.
- A team job compiles its formation into a graph.
- A task job (a notebook, a compute step, a SQL statement) is wrapped into a one-node graph so it runs on the same substrate as everything else.
The bound graph's content hash is stamped on the job, and that hash is the replay anchor: what ran is identified by what it was, not by a name that could later point somewhere else. A job whose graph cannot be resolved fails closed rather than running something approximate.
Jobs between entities
An agent can ask another entity to do a job, and that request is a signed envelope rather than an internal call:
- Signed over a canonical encoding, so the request is verifiable by the receiver independently of the transport.
- Chained, each envelope referencing the previous one for a given request, so the exchange cannot be silently reordered or truncated.
- Bounded: a clock-skew window, a hop limit, and a purpose tag, so a stale or looping request is refused rather than honoured.
Message kinds are a closed set: request, accept, reject, progress, result.
The receiving side runs a fixed gate order, envelope, authority, addressing, tenancy, deduplication, delivery, and a failure at any stage refuses the delivery rather than passing a partially-validated request inward.
Scheduled and triggered work
Jobs do not only arrive from a caller. Two other paths start them:
Schedules. Cron-style definitions drive recurring work, and every job type the platform runs can be scheduled: compute, notebooks, SQL, a single agent, and a whole agent team.
A due schedule fires on exactly one cell. In a multi-cell node the firing is deduplicated through a node-converged lease, so it produces one run rather than one per cell. This is one of the places where a naive per-cell lease would silently produce N duplicate runs.
What a fire does next is the part worth understanding, because it is why a scheduled agent run is durable rather than best-effort. A cron tick is synchronous and short; an agent run is asynchronous, priced, and admitted. So the firing cell does not execute the agent inline. It enqueues a durable row, which a dispatcher drains and submits through the same governed path a human submission takes, admission gate and budget included, acting as the principal the schedule resolved to rather than as the scheduler. If the cell dies mid-run, the queued row is re-drained and the in-flight run is adopted on recovery, rather than lost or silently run twice.
A scheduled team is a real crew, not a downgraded agent. A team schedule names a crew, an instance of a formation with its members actually bound, and launches it with the lead's identity, the spawn gate, and the run-budget bracket a hand-launched crew gets. Naming only a formation is refused when the schedule is authored, because a formation with no member bindings is a template that could never run. Refusing at authoring time beats persisting a definition that fails on every fire.
Triggers. A job can start from an observed condition, a metric crossing a threshold or data arriving. The trigger evaluation is deliberately three-valued: fire, hold, or cannot determine, and "cannot determine" is not treated as "fire". A trigger firing still passes the same admission gate and budget check as a submitted job, so an automated path cannot bypass governance a human path respects.
Watching a job
Jobs expose their run journal, a live event stream, and cancellation, through the administrative surface and the console. Because the journal is the same one the workflow runtime writes, watching a job is watching the actual execution record rather than a summary assembled for display.
An event trigger cannot start a crew today. A scheduled team job is wired end to end, but an automation rule's actions are notification and Edge Agent commands, so an observed condition cannot yet launch a team. Use a schedule for recurring crew work; triggers cover the single-agent and compute cases.
Related topics
- What actually executes a job: the workflow graph.
- Assembling a team rather than a single graph: agent teams.
- What a job may spend, and who is charged: agent economics.
- The record a job leaves: observing an agent.