Documentation · The Lagstyr handbook

Commissioning agents and retrieval

An installed kernel, an available model endpoint and an authorised agent are three different states. Commission them separately. The reference configuration boots without hosted model or embedding credentials: records, the console, local document parsing and explicit full-text search remain available. Agents require their own model configuration; semantic and hybrid search require an admitted embedding stack.

Approve and pin the processor

Declare the exact model/provider, endpoint, credential source, processor-policy identity, permitted purposes, workloads and data classes. Record retention, region and approval choices in the customer contract. A locally hosted endpoint still needs an approved processor policy. External model, embedding and search providers are explicit installation opt-ins.

Optional managed local agent serving uses services.localModel and the module’s manageModel selection, which must agree. Its closed configuration pins the native runtime and weights, literal loopback endpoint, credential and token prices. The release imports an immutable offline runtime; preflight, service confinement, socket ownership and a metered native canary are checked. Managed clients require root-issued runtime admission immediately before local sends.

Keep native runtime checks, licence/rights review, model qualification and business authority as separate evidence. A healthy local server does not grant an agent permission or establish that its answers meet your task’s acceptance criteria.

Configure and qualify the agent

Use Bringing an agent into service for the console ceremony, and Defining and promoting action classes for the bounded work it may perform. Pin model/provider, invocation triggers, scope, wording, tool schemas and evaluation cases. Give the agent only selected skills and review any executor-label assignment separately from that executor’s machine-role grant. A custom composite workflow is another governed release: qualify its exact plan and case set before activation, then re-run the agent’s own configuration evaluation because the newly available composite changes its pinned tool surface.

A vendor effect skill, such as email or report delivery, journal posting, Stripe collection or refund, repository pull-request classification or calendar changes, also needs the worker that performs it. Until every workload role that executes the effect holds a granted, active, unexpired machine credential, readiness reports missing_vendor_effect_executor and runs are refused admission. Provision and grant those roles before activation, and treat their expiry or revocation as an agent-readiness event. The check proves a provisioned, authenticating executor, not a running one.

The operator CLI supports a reviewable configuration plan and governed proposals:

lagstyr-install-bootstrap --manifest /secure/config/agents.json plan
lagstyr-install-bootstrap --manifest /secure/config/agents.json propose
lagstyr-install-bootstrap --manifest /secure/config/agents.json \
  approve --operator-email [email protected]

Supply LAGSTYR_KERNEL_URL, LAGSTYR_OPERATOR_KEY and, for approve, LAGSTYR_OPERATOR_PASSWORD through the CLI’s documented private environment. Keep the installation-authored manifest and ledger. An executor label derives its workload from an existing compiled run-loop role; a manifest cannot grant that role. Additional skills require selected authority before use.

Run the exact versioned evaluations and review the results before activation. The measuring judge is itself an append-only governed installation revision: approve its exact provider, model and runtime pin separately, keep credentials in deployment secrets, and expect a successor revision to make old qualification stale. Include refusals, missing evidence, provider failure and instruction-like content in retrieved material. Model output and external documents remain untrusted inputs; deterministic kernel validation and approval apply at the effect boundary. T3 promotion needs the action class’s own evidence, limits, sampling and automatic pause controls. A model replacement requires new review and qualification.

Configure document ingestion and retrieval

Document indexing and structured extraction are distinct local Python workloads. The indexer uses release-pinned parsing/OCR; extracted candidates enter typed kernel seams. Original bytes remain in object storage with their source identity. Parsing a document does not promote every statement in it to an authoritative fact.

The example selects retrieval.profile: null. Without an embedding configuration, semantic readiness is not_configured, explicit FTS works, and vector/hybrid requests refuse. Stub embeddings are development/test only and cannot establish production readiness.

Production semantic preflight requires an exact profile marked qualified in the release’s evidence/retrieval/qualification-matrix.json, including its native weight/server pins. At this review, the matrix admits no production profile and names no default. The candidate names in the kit are candidates, not a choice of already qualified services.

Once a release admits a profile, follow its infra/install/README.md semantic contract. Local profiles need the managed embedding service, separate document/query processes, bounded registry, credentials, runtime admission and native canaries. A hosted profile additionally requires its explicit provider approval and credential. Activation requires the exact generation tuple, usable partial HNSW index and complete chunk coverage; an inference process alone is insufficient.

Change a populated generation through governed backfill and activation. Retain existing vectors until the new generation is complete and accepted. Test representative customer retrieval quality and latency/capacity where your acceptance contract requires them. Customer calibration can inform tuning, but it cannot turn an unqualified release profile into an admitted one.

Verify the operating state

Run setup diagnostics for unpinned agents, inactive action-class bindings, missing AI-system operating contracts, erased fallback/runbook evidence and broken selected authority. Confirm the expected provider/model, agent lifecycle, executor assignment, evaluation result and search mode in the installed deployment. Exercise refusal when a required dependency or approval is removed.

During service, monitor provider failures, token/cost limits, queues, retrieval freshness and action-class pauses alongside human review results. A healthy HTTP service does not establish working delegated authority. Continue with Monitoring and routine operations.