Get Started

Introduction

NILScript is a server-side governed-action contract for AI agents: the agent proposes intent, a deterministic kernel is the only component that commits, and an action a backend never declared is unexpressible rather than filtered. It is the governed action layer that tool-integration standards leave undefined.

Why agents need a safe contract

The last two years solved conversation. Tool-calling and MCP gave models a clean way to read the world and call functions. But the moment an agent has to change a business, the problem stops being about language and starts being about consequences.

The three gaps

Every backend is a bespoke API. Shopify’s GraphQL, WooCommerce’s REST, Stripe’s payment intents, ERPNext’s documents. An agent that works across systems must learn, and re-learn, N incompatible surfaces and state machines.
The agent is probabilistic; the business is not. A model can hallucinate an amount, an identifier, or a customer.
There is no safe contract. Today you either hardcode workflows in the backend, or hand a stateless chatbot unbounded power and zero human visibility. Neither is auditable; neither scales past one integration.

The cost of a wrong guess

A hallucinated amount in chat is a typo. Against a ledger it is a loss.

NILScript at a glance

NILScript is the governed action layer that tool-integration standards leave undefined. MCP and OpenAPI standardize what an agent can reach; NIL governs what an agent can author. NIL composes with them; it does not replace them. It rests on four structural guarantees:

No side effects on propose. An agent emits intent, not an action. Proposing leaves the backend byte-identical; only an approved commit changes state.
Skeleton-bounded. An agent can only name verbs and targets the backend has declared. An undeclared verb has no representation to send, so advertised equals committable.
Honest, bounded reversibility. Every write declares whether it is reversible, compensable, or irreversible, and a rollback runs a real compensation. The system never pretends an irreversible effect can be undone.
Earned, not asserted. A success envelope is confirmed by reading the record back; a reversibility tier is confirmed by a conformance run. An adapter that claims a property its run does not honour fails admission.

USB for systems, with governance. One adapter per backend; any agent can then operate it without being trusted.

The two layers

NILScript is two layers plus a neutral spec, both deliberately constrained to stay safe:

NIL — the Network Intent Layer. A closed wire protocol: seven speaker-plane performatives (plus DECIDE on the owner plane). The kernel is SEQRD-PC.
The NILScript DSL. A declarative JSON DAG of typed nodes that an agent writes at runtime. A validator admits or rejects the whole plan before any side effect.

plan.nil.json

{
  "wosool": "0.1",
  "workspace": "ws_demo",
  "locale": "ar",
  "entry": "step_1",
  "pipeline": [
    { "id": "step_1", "type": "query",  "verb": "commerce.product",
      "args": { "sku": "TSHIRT-01" }, "next": "step_2" },
    { "id": "step_2", "type": "condition",
      "expression": "$.step_1.output.stock < 10",
      "on_true": "step_3", "on_false": "step_4" },
    { "id": "step_3", "type": "action", "skill": "product",
      "verb": "commerce.create_purchase_order",
      "args": { "sku": "TSHIRT-01", "qty": "100" }, "next": "step_4" }
  ]
}

The ceiling is the guarantee

The DSL is deliberately incomplete — no unbounded loops, no file access, no eval, no user-defined functions. It can express any business automation a merchant can describe in words, and nothing else.

Safe by construction

Safety is structural, not bolted on after the fact:

Hallucinations die at the server. Previews come from system-resolved facts, never from agent-supplied values.
Tiered approval. LOW executes immediately, MEDIUM notifies, HIGH parks for approval, CRITICAL adds a 300-second cooling delay.
Refusals are answers. Ambiguous requests return up to eight candidates for a human to choose — not a guess.

Proof it works

A standard is only worth the reality it survives contact with.

Calibrated against 18 production platforms across e-commerce, ERP, billing, and scheduling — 90 documented rows, each backed by a vendor’s own API docs.
Proven self-adoptable. An independent ERPNext adapter was built from the published standard and CLI alone — no privileged knowledge of the reference implementation.
Running in production. The reference implementation operates the standard today. The spec is extracted from running code, never the reverse.

Where to go next

What is NILScript? — the full overview of the standard.
Quickstart — install, explore the CLI, and write your first plan.
Architecture — the Generation → Validation → Runtime machine.
Safety Model — grants, tiers, previews, refusals, and audit.