The AXIOM Language
Write agents you can govern.
.axiom is a declarative language for specifying AI agents — what they
receive, what they may emit, and above all what they can never change about
themselves. No Python, no procedural code: an agent is a contract you can read,
diff, sign, and enforce.
Everything here is taken from the canonical spec, axiom_files/core/axiom_language.axiom
— which is itself written in AXIOM, using only the constructs it defines.
01 Your first agent
Every .axiom file declares exactly one agent, and AGENT must be
the first line. Five constructs give you a complete, valid agent:
AGENT InvoiceReader
VERSION 1.0
TRUST_LEVEL 2
PURPOSE Extract totals and due dates from supplier invoices
GOAL Read an invoice and return its structured fields
Never guess a number that is not present on the page
AGENT- Names the agent. One per file, required, first line.
VERSION- Semantic version —
major.minorormajor.minor.patch. TRUST_LEVEL- An integer trust tier. Delegation flows downward only, never upward — a level-2 agent cannot hand work to a level-4 one.
PURPOSE- A one-line mission statement.
GOAL- The multi-line objective. Indented lines below the first are continuation lines that extend the value.
02 Contracts: what goes in, what comes out
RECEIVES and EMITS declare the agent's interface as
name: type pairs. This is the boundary the runtime checks.
RECEIVES document: string, page_count: int, locale: string
EMITS total: float, due_date: string, confidence: float
Declaring confidence as an output is idiomatic AXIOM: an agent states how
sure it is, and a CONSTRAINT can cap that number so it may never claim certainty.
03 Immutability — the point of the language
This is what separates .axiom from a prompt. MUTATES lists the
fields an agent may change at runtime. CANNOT_MUTATE lists fields that are
permanently locked — the parser enforces it, so the agent cannot rewrite
its own purpose, escalate its trust level, or edit away its own limits.
MUTATES cache, retry_count
CANNOT_MUTATE agent, purpose, version, trust_level
CANNOT_MUTATE cannot_mutate_fields_are_permanent
04 Invariants: what a CONSTRAINT is
A CONSTRAINT is a condition that must be true of every output.
It is not a step and it is not a preference. If it fails, the output is invalid. The other
behavioural constructs build on it:
CONSTRAINT- What must always hold. It can't be broken.
RULES- What to prefer when several outputs are allowed. Rules can be traded against each other.
CHECK- How you tell whether a constraint holds.
FAILURE- What happens when a check fails.
The one-line form states the condition, one invariant per line and never bundled, so each can be cited and violated independently:
CONSTRAINT Write the test before the implementation — always
CONSTRAINT Confidence ceiling 0.85 — never claim certainty
CONSTRAINT Human review required before any production promotion
Don't: CONSTRAINT Test first and cap confidence and require review
— three invariants in one line cannot be individually enforced or reported.
Where specs blur these
- Mixed kinds. "Do not invent facts" is a real constraint. "Consider whether
the answer may confuse…" is an action, so it belongs in
PROCESS. "Prioritize relevant, accurate…" is a ranking, so it belongs inRULES. - No way to test it. "Provide specific answers" has no pass condition, so
nothing in
CHECKcan decide it. - No links. A
CHECKthat lists Tone and Empathy when no constraint asks for them, and aFAILURElist that doesn't say which constraint each response belongs to. - No order for conflicts. "Be concise" can clash with completeness, and nothing in the spec decides which one wins.
The named form
Give each constraint a name, the condition it must meet, a severity, a check and a failure
response. Then order them with PRECEDENCE:
CONSTRAINT NoFabrication
HOLDS every claim traces to source or known fact
SEVERITY hard
CHECK claim lacks support
FAILURE state uncertainty; withhold claim
CONSTRAINT IntentPreserved
HOLDS output answers the request as asked
SEVERITY hard
CHECK output scope differs from request scope
FAILURE specify the gap; ask for missing information
CONSTRAINT Specificity
HOLDS answer includes concrete values when available
SEVERITY soft
CHECK answer generalizes where specifics exist
FAILURE add specifics or state they are unavailable
PRECEDENCE
NoFabrication > IntentPreserved > Specificity > Concision
HOLDS- The condition itself. A condition, not an action and not a ranking.
SEVERITYhardcan never be traded away.softgives way to anything higher inPRECEDENCE.CHECK- What, seen in the output, means the constraint failed.
FAILURE- The response when that check fails, bound to this constraint.
PRECEDENCE- Who wins a conflict, highest first. Nothing soft may rank above a hard constraint, and two hard constraints never trade: an output that can't meet both is invalid.
05 Exercise: untangle a spec
Every line below comes from one real agent spec, where they all sat under
CONSTRAINT, CHECK and FAILURE with nothing to tell
them apart. Work through three steps. Nothing you type leaves this page.
Step 1 · Sort each line
Pick the construct each line belongs in. A CONSTRAINT is a condition true of
every output, RULES rank, PROCESS acts, CHECK detects
a failure, FAILURE responds to one.
-
Every claim traces to the source material or to established fact
-
Consider whether the answer may confuse, mislead, or distress the user
-
Prioritize relevant, accurate, complete, and respectful content
-
A claim has no supporting source or established fact
-
State the uncertainty and withhold the claim
-
Response length across demographic variants of the same task differs by no more than 15%
-
Prefer clear answers over vague ones
-
Identify missing information
-
The scope of the output differs from the scope of the request
Answer key
1 CONSTRAINT · 2 PROCESS · 3 RULES · 4 CHECK · 5 FAILURE · 6 CONSTRAINT · 7 RULES · 8 PROCESS · 9 CHECK
Step 2 · Make "Provide specific answers" testable
That line has no pass condition, so no CHECK can decide it. Rewrite it as a
named constraint. The checker applies the validator's own rules as you type.
Show a model answer
CONSTRAINT Specificity
HOLDS the answer gives concrete values wherever the task supplies them
SEVERITY soft
CHECK the answer generalizes where specific values exist
FAILURE add the specific values or state that they are unavailable
Why soft: an answer can stay valid without every specific, so this one
may give way to a higher constraint. Fabricating a value to be specific would break
NoFabrication, which is hard.
Step 3 · Put them in order
Two hard constraints and two soft ones. Arrange them in PRECEDENCE order,
highest first.
ConcisionsoftIntentPreservedhardSpecificitysoftNoFabricationhard
Show the reasoning
Both hard constraints go above both soft ones: nothing soft may outrank a hard
constraint (the validator reports AX-C022). Between the two hard ones the
order is yours to state, and it never trades either away. Between the soft ones,
Specificity > Concision means a concrete value stays in even when it
lengthens the answer:
PRECEDENCE
NoFabrication > IntentPreserved > Specificity > Concision
06 Flow sections
A bare UPPERCASE word on its own line opens a section; the bullets below belong to it. Five sections describe how the agent runs, in order:
RULESoperational commands the agent followsPROCESSordered steps, executed sequentiallyCHECKquality gates, evaluated after PROCESSFAILUREwhat to do when a CHECK gate failsOUTPUTthe shape of the responsePROCESS
- Read the document and locate the totals block
- Extract the currency and amount as separate fields
- Compute confidence from how many fields were found verbatim
CHECK
- Every emitted number appears literally in the source document
- Confidence is at or below the declared ceiling
FAILURE
- Emit the fields that did pass and mark the rest unknown
- Never substitute an inferred number for a missing one
07 Scoring, routing, and hard limits
SUCCESS takes field: weight pairs, and the weights
must sum to 1.0 — the parser rejects anything else, so "success" is always
a fully-allocated definition rather than a vibe.
SUCCESS
- accuracy: 0.5
- calibration: 0.3
- latency: 0.2
SECURITY
- Never write outside the workspace directory
- Never transmit document contents to a third-party endpoint
DELEGATES
- InvoiceReader to Sandbox on untrusted_attachment
HUMAN_REVIEW
- Any invoice above 50000 in any currency
SECURITY- Hard rules that override
RULES. When they conflict, security wins. DELEGATES- Routing:
Agent to Target on trigger— and remember trust flows downward only. TOOLS- Declares an available tool with its permissions and sandbox flag.
HUMAN_REVIEW- Conditions that require a person to approve before proceeding.
CONCEPT/WHEN- A named sub-spec (with
APPLIES WHEN,NOT WHEN,PRIORITY,REQUIRES,EFFECT), plus a decision table that activates it. HISTORY- Timestamped change-log entries.
08 Every construct
The complete set, as defined by the canonical spec (v1.3), plus bounded agency and named constraints.
| Construct | Kind | What it does |
|---|---|---|
AGENT | field | Names the agent — one per file, required, first line |
VERSION | field | Semantic version, major.minor[.patch] |
TRUST_LEVEL | field | Integer trust tier; delegation flows downward only |
SANDBOX_AGENT | field | Names the sandbox delegate for isolated execution |
PURPOSE | field | One-line mission statement |
GOAL | field | Multi-line objective (indented continuation lines) |
RECEIVES | contract | Input contract as name: type pairs |
EMITS | contract | Output contract as name: type pairs |
MUTATES | governance | Fields this agent may modify at runtime |
CANNOT_MUTATE | governance | Permanently locked fields — parser-enforced |
CONSTRAINT | governance | A condition true of every output. One line per invariant, or the named form with HOLDS / SEVERITY / CHECK / FAILURE |
PRECEDENCE | governance | Orders named constraints for conflicts: A > B > C. Hard constraints are never outranked |
RULES | section | Operational commands the agent follows |
PROCESS | section | Ordered steps executed sequentially |
CHECK | section | Quality gates evaluated after PROCESS |
FAILURE | section | Behaviour when CHECK gates fail |
OUTPUT | section | Format and structure of the response |
SUCCESS | section | field: weight pairs — must sum to 1.0 |
CONCEPT | block | Named sub-spec with its own PURPOSE / APPLIES WHEN / NOT WHEN / PRIORITY / REQUIRES / EFFECT |
WHEN | section | Decision table mapping a condition to a concept activation |
SECURITY | section | Hard rules that override RULES |
TOOLS | section | Available tools with permissions and sandbox flags |
DELEGATES | section | Routing: Agent to Target on trigger |
HUMAN_REVIEW | section | Conditions requiring human approval |
HISTORY | section | Timestamped change-log entries |
BOUNDS | agency | How much an agent may do before it stops: steps, tool calls, tokens, spend, time, failures |
SUBAGENTS | agency | Which agents it may start, how many, and with which tools |
SANDBOX | agency | What its tools are confined to: filesystem, network, execution, secrets |
Plus three grammar rules: any unrecognised uppercase word on its own line opens a generic
section; - begins a bullet; indentation continues the previous value.
Blank lines are cosmetic and carry no meaning.
09 Check your work
A spec is only governance if something enforces it. Two tools read .axiom
files directly:
# structural lint — grammar, unknown constructs, malformed contracts
python axiom_cli.py lint my_agent.axiom
# full validation — immutability, trust-level flow, SUCCESS weights,
# named constraints and PRECEDENCE
python -c "import json,sys; from axiom_files.validator import validate_source; print(json.dumps(validate_source(open(sys.argv[1]).read()), indent=1))" my_agent.axiom
Both are also exposed as MCP tools (axiom_lint, axiom_validate),
so an editor or another agent can check a spec as it is written.
Where to go next
- Policy Studio — build and test a policy visually, no install
- CheckMyLLM — see governance measured against real models
- Read
axiom_files/core/axiom_language.axiom— the spec, in its own language - Read
axiom_agent.axiom— a real, complete agent withKNOWN_BUGS