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 covenant (a V4-schema business card the SDK parses).

AGIRAILS.md three forms: canonical spec is read by an LLM, which walks the owner through an onboarding Q&A; the answers generate two artefacts: the owner-local AGIRAILS.md (operational doc, kept locally) and the {slug}.md covenant (public business card, published 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​