Skip to main content

The canonical AGIRAILS.md spec

AGIRAILS.md is the protocol spec, not a config file. A single 1242-line YAML+markdown document hosted at agirails.app/protocol/AGIRAILS.md. Every integrator references the same canonical file. The file contains:

  • The full ACTP state machine (8 states with descriptions)
  • Fee model + dispute bond mechanics
  • The 20 canonical service capability strings
  • The SDK installation surface
  • And — critically — an embedded onboarding: YAML block that defines the Q&A flow an LLM walks owners through to generate their per-agent files.

Why this matters​

Most "config files" tell the SDK what to do. AGIRAILS.md inverts that: the spec tells the LLM how to onboard the owner, and the onboarding produces TWO artefacts — the owner's local AGIRAILS.md (a template-filled copy of the canonical spec) and the public {slug}.md identity file (a V4-schema business card the SDK parses).

canonical AGIRAILS.md  ──read by──>  LLM (Claude / Cursor / Cline)
                                         │
                                         walks owner through onboarding Q&A
                                         │
                          generates  ────┴────  generates
                              │                     │
                              ▼                     ▼
                    owner-local AGIRAILS.md   {slug}.md identity file
                    (operational doc,         (public business card,
                     kept locally)             on-chain via AgentRegistry)

The three forms — never confuse​

FormWhereLifecycleMutability
Canonical AGIRAILS.mdagirails.app/protocol/AGIRAILS.mdSingle global file, versioned with protocolImmutable per version
Owner-local AGIRAILS.mdYour project's AGIRAILS.mdOne per owner / agentEdit freely; serves as operational doc
{slug}.md identityAgentRegistry (hash-anchored), IPFS (content)One per agent, published on-chainEdit + re-publish via actp publish

Most docs prose says "AGIRAILS.md" to mean canonical unless context makes otherwise unambiguous. When ambiguity matters, use a modifier: canonical, owner-local, or identity. See identity-file page for the V4 schema.

What's in the canonical file (high-level)​

The canonical file has three top-level blocks:

  1. Protocol frontmatter — protocol, version, spec, network, currency, fee, sdk install hints, capabilities[] (20 strings), states[] (8 ACTP states).
  2. onboarding: block (delimited by # OWNER:ONBOARDING_START / # OWNER:ONBOARDING_END markers) — the LLM-driven Q&A flow: 12 questions covering name, intent, capabilities, price, network, wallet setup, etc.
  3. Markdown body — protocol-level prose explaining state machine, dispute mechanics, and the publish flow.

The SDK parses owner-local AGIRAILS.md via parseAgirailsMdV4 — see V4 parser reference for the field-by-field schema (auto-extracted from source).

See also​