Documentation · The Lagstyr handbook

Bringing an agent into service

An agent enters service through five stages, and the kernel rejects every later stage until its predecessors are complete. The console lists them on the agent’s setup page; here they are in the order you will meet them.

A business request or a template selection, completed.
An installation-owned inert proposal, with zero effective authority.
An authorised operator configures the exact authority and runtime envelope.
The trusted evaluator runs every case against the exact configuration pin.
A separate authorised human decides the activation proposal atomically.

Stage 1: a template, or a described job

Agent templates is a catalogue of immutable blueprints. Its banner is the rule: Templates are blueprints, not active agents. Selecting one copies that exact version into a new installation-owned proposal with zero effective authority. A template names no approval policy, accountable human, model, provider, effective authority, scope or active status, and its recommended skills are exactly that: Recommendations explain a least-authority starting point. Selecting this template grants none of them.

Selecting a version asks for one thing, the installation agent name, and creates the proposed agent. The alternative, Describe a custom job, asks for a name and a description of the intended job and the boundaries; it says, before you type, Do not include secrets or personal data, and it carries no field that could configure authority.

Either path can be taken by a business requester who is not an operator; the requester’s console shows only those two doors. The receipt is the same for both: Proposed agent recorded, status proposed, and the banner Zero effective authority. An operator sees a link to governed setup; a requester is told that an authorised operator must now configure and evaluate the proposal.

Stage 2: what a proposed agent is

A proposed agent cannot be admitted, run, or dispatch any skill. Its setup page shows where it came from: the immutable blueprint copy and its content digest, or the words Custom job with the note that the request prose stays in its governed, erasable record and is not repeated in immutable history.

The Activation readiness card is the instrument you will read most. It is in one of four states: ready for an activation proposal; not ready, with every blocker the kernel names; not ready with no detail, which still blocks; or readiness unavailable, which also blocks. Beneath it, the readiness facts pair the current configuration pin with the evaluated one, and the current evaluation-case pin with the evaluated one. When a pair disagrees, the evaluation is stale, and nothing you do in the console can make it current except evaluating again.

One blocker is cleared outside this ceremony. An agent given a skill that acts in another system, such as sending email, delivering a report, posting a journal, collecting or refunding through Stripe, classifying a repository pull request or changing a calendar, is not ready while missing_vendor_effect_executor is listed. Its detail names the skill and the workload role that performs the effect, and it clears only when that role holds a granted, active, unexpired machine credential. Provisioning one is the host operator’s work, not a console form. The check proves the worker can authenticate, not that it is running.

Stage 3: authority, configuration, skills

3a. The native authority foundation. Two proposals. A native mandate is the agent’s authority root, not a skill permission: you name the grantor’s basis, the exact role kind, the scope, the governing policy version and the authority instrument. Installation-wide scope must be chosen explicitly and must leave the legal entity blank. Then a backing authority grant beneath that mandate, for one exact skill, with an action of execute or propose only; this form never offers approve, administer or bind. After approval, the grant’s identifier is what you carry into the skill permission form.

3b. The exact configuration. One proposal that freezes everything together: the instructions, model, provider, sampling, exact skill names, scope, run and cost limits, the native mandate, and the accountable owner and supervisor. It also names one or more closed invocation sources: human, a registered event kind, or a scheduled occurrence task kind. The provider is never preselected. A blank scope never means installation-wide; that option must be chosen. A later change creates a new configuration pin and makes prior evaluation stale, so configure once and carefully.

3c. Normalised skill permissions. One proposal per exact active skill. A read permission leaves the authority grant blank; a write skill names the exact grant from 3a. This form never grants approval power.

Each of these is a proposal and none activates the agent.

Stage 4: evaluation

The console does not run model traffic. What it offers is a handoff. First, a dry-run command that validates the readiness snapshot without issuing a challenge or writing evidence. Then, when the pin and at least one evaluation case exist and no other blocker remains, Issue one-time evaluation job. The kernel binds one short-lived challenge to the exact configuration and case pins and returns its plaintext once, in a page the browser must not store: Copy the challenge now. The console does not log it and refreshing cannot recover it. Issuance rechecks the console’s exact authenticated key, active workload registration and internal_console role in the same transaction; a revoked, rotated or relabelled issuer cannot mint from an earlier login decision. The runner key it pairs with cannot issue a job, dispatch a skill or approve activation, and the challenge is consumed only when evidence for both pins is accepted. The judge is not selected by deployment environment: a separately approved, append-only installation revision fixes its exact provider, model and runtime pin. Every job and accepted result carries that revision and digest; deployment configuration supplies credentials only.

You can also propose an installation-owned evaluation case here, for a custom job with no copied cases or for a governed regression case. The form records no source run or feedback identifier unless one exists; it never fabricates either.

Custom workflows have a separate release qualification. A governed workflow is a flat composition of exact skill revisions, initially inert. Its append-only cases carry controlled step outputs; the kernel replays the mappings and exact input/output schemas, derives the score itself, and requires a perfect score for every critical case. The evaluation runner submits through the same kind of short-lived handoff, pinned to the release, complete case set and current procedure. Only a governed activation of those exact passing pins exposes the composite as one tool to eligible agents. Editing the case set immediately stops new use until the release is evaluated again.

Stage 5: activation

The activation form appears only when readiness is ready and the kernel supplies the exact configuration, case-set and scorecard pins. Those three are filled by the kernel and cannot be typed. You name the accountable owner, the supervisor and the mandate, and propose. Approval of this proposal is the only operation that can activate the agent, and the kernel re-checks the pinned state at the moment a human decides it.

Afterwards

Everything you proposed, and every decision that authorised it, stays on the setup page under Configuration, authority and activation history, including apply attempts and the last error. If an active agent has to be stopped, the Contain it control on its page pauses every active action class it holds; see Agents and their runs.