#Agent Guardrails

Legra is built to support AI agents, but an agent should not normally receive unrestricted database credentials. The safer model is simple:

Give an agent a job description, not database credentials.

In Legra, that job description can be modeled as a Use Case, a persona, and a finite set of tested Stories. A Story is a typed business capability: it defines what can be done, which inputs and outputs are expected, how it is implemented, and how its behavior is tested. The agent chooses among approved Stories instead of inventing arbitrary queries and updates against live data.

Legra is the governed data and work substrate around the agent. It does not replace the model or agent runtime.

#The preferred boundary

The strongest agent session is bound to one root Use Case and its explicitly defined sub-use-cases, one persona, one workspace deployment, one task, and one branch. Those bindings determine:

• the expected business outcomes;
• the instructions and skills for the persona;
• the exact Stories the agent can invoke;
• the typed concepts the Stories accept and return;
• the data sources the deployment is allowed to reach;
• the authority, token budget, deadline, and contract for the work.

A token budget is the maximum Legra-token spend authorized for the task across positively priced data, compute, storage, custody, transport, rights, and services. It is not a generic dollar-budget field. Zero is a valid explicit token budget for work whose composed price is zero. See The Legra data economy for the price components that can consume that budget.

The agent does not get direct access to SPARQL, Cypher, or GQL, the full Story catalogue, statement storage, or workspace administration. Hiding those tools in a prompt is not enough: the credential itself must be unable to reach them.

#Four levels of isolation

The modes below are ordered from strongest to weakest.

Levels 1 and 2 constrain an agent through modeled business capabilities. Level 3 is also safe for autonomous work: the agent has full freedom in its sandbox and staging branch, but its credential cannot switch branches, touch the default branch, or merge. A human or a separately authorized approval agent must review and promote the work. Level 4 is broad operator access and should be treated as an explicit high-risk exception.

High risk does not mean untraceable or irreversible graph data. Level 4 still records activity in the Task tree and Journal, connects changes to actors and provenance, and preserves the full Git-like history of every branch. Operators can inspect what happened and restore affected graph data to its original state without erasing the history of the incident. That recovery cannot retract information already disclosed or undo every external side effect, so evidence and rollback complement rather than replace least privilege.

A VM or container is useful, but it cannot decide which business action is legitimate. In levels 1 and 2, Legra supplies that semantic boundary. In level 3, the branch and the absence of merge authority provide the graph-integrity boundary while deliberately leaving the agent free inside it. Internet access is a separate sandbox choice because branch isolation does not govern disclosure to external systems.

#From action to reviewed knowledge

A governed agent workflow can follow the same pattern that made AI work well in software repositories:

1. Legra creates a task-specific branch.
2. The agent receives its persona, outcomes, concepts, and Story tools.
3. Every Story call attaches to the same Task and Journal evidence tree.
4. The agent writes proposed knowledge to its branch, not directly to the production branch.
5. Story tests, data validation, policies, contracts, and budgets are checked.
6. A person or authorized approval persona reviews the graph diff.
7. Approved work is merged; rejected work never reaches production.

The branch records what changed. The Task tree records how the work was performed. The Journal provides durable evidence of activity and priced items. Together they make agent work attributable, reviewable, and reproducible.

#What these guardrails address

This design reduces the blast radius of prompt injection, hallucinated operations, accidental privilege expansion, cross-use-case access, unreviewed production writes, unexpected external calls, and runaway cost. It does not claim that a model can never be wrong. It constrains what a wrong answer can cause and preserves the evidence needed to review and improve the result.

If an external model provider performs inference, it may see the context sent to it. Local inference, confidential computing, and provider terms are separate confidentiality decisions.

#Production and operator boundaries

The dedicated persona-bound Use Case harness is the production boundary for autonomous agents. It derives a generated persona package from the permitted Use Case tree, exposes only the applicable Stories, binds a task branch and token budget, and records execution in the Journal. The CLI’s embedded MCP server exposes the broader operator and development surface. It is useful for supervised work, but it is not the production boundary for an autonomous agent.

For the operator MCP interface and its safety controls, see the MCP Server guide. For the underlying branch workflow, see Branching and Merge Workflows, and for data rules, see Data Validation.