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.

Start Lesson 1 Construct reference

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.minor or major.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.

Syntax, in three rules. Constructs are UPPERCASE words at the start of a line. A line starting with - is a bullet belonging to the section above it. An indented line continues the previous value. That is the whole grammar.

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

Read that second line again. cannot_mutate_fields_are_permanent is itself locked. The immutability rule protects itself — an agent cannot unlock its own locks. Self-improving agents in this codebase all carry it.

04 Invariants: one `CONSTRAINT` at a time

A CONSTRAINT is a single-line invariant. The spec is explicit that they are never bundled — one invariant per keyword, so each can be cited, tested, 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.

05 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 follows

PROCESSordered steps, executed sequentially

CHECKquality gates, evaluated after PROCESS

FAILUREwhat to do when a CHECK gate fails

OUTPUTthe shape of the response

PROCESS
- 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

Any unrecognised uppercase word on its own line becomes a generic section collecting bullets — so the language extends without a parser change. KNOWN_BUGS in axiom_agent.axiom works exactly this way.

06 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.

07 Every construct

The complete set, as defined by the canonical spec (v1.3).

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	One single-line invariant, never bundled
`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

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.

08 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 -m axiom_lint my_agent.axiom

# full validation — immutability, trust-level flow, SUCCESS weights summing to 1.0
python -m axiom_validate 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 with KNOWN_BUGS

Write agents you can govern.

01 Your first agent

02 Contracts: what goes in, what comes out

03 Immutability — the point of the language

04 Invariants: one CONSTRAINT at a time

05 Flow sections

06 Scoring, routing, and hard limits

07 Every construct

08 Check your work

Where to go next

04 Invariants: one `CONSTRAINT` at a time