Build

SHIP

Structured Hierarchical Instructional Programs. The agent specification layer underneath the Theseus workspace (THESEUS.md, tools.yaml), lowered to a chain-ready CompiledAgent.

In one paragraph

You author an agent as a small workspace: a THESEUS.md (Theseus YAML frontmatter plus a Markdown system prompt), a tools.yaml tool surface, any number of skills/<name>/SKILL.md procedures, and an agent.rs that the Theseus agent compiler lowers into a canonical CompiledAgent. SHIP is the type layer underneath (ship_types, ship_version): it pins the agent’s metadata, tools, and Agent Behavior Graph (ABG) of model calls, tool calls, routers, and terminal nodes. The compiler emits JSON for tooling and SCALE for on-chain registration; the runtime only ever sees the SCALE-encoded blob.
  • Declarative, not Turing-complete: SHIP describes graph shape and tool schemas, not arbitrary control flow.
  • Compiles to CompiledAgent: a SCALE- and JSON-encoded canonical structure that the chain decodes into ABG nodes on registration.
  • Off-chain authoring: the workspace lives in your repo. The chain only knows about the compiled blob; runtime bounds (max ABG nodes, max tools per agent, etc.) are enforced during decoding.
  • Versioned: 0.x experimental, 1.x stable (backwards-compatible within major).

What an agent workspace contains

An agent is a small workspace of files, not a single blob. Together they capture the four things the chain needs to register an agent and run it.

Agent metadata

Name, id, model, and system prompt from THESEUS.md; version and entry node from agent.rs.

Tool surface

tools.yaml: native tools (on-chain) and opt-in common tools (verified off-chain). The set the runtime enforces.

ABG nodes

Model calls, tool calls, routers, end nodes: the directed graph the runtime executes.

Resolved IDs

Models are named by tag in THESEUS.md; the compiler resolves each to a canonical 32-byte ID baked into the CompiledAgent.

Authoring → on-chain

1

Author

Write the workspace: THESEUS.md, tools.yaml, and any skills/<name>/SKILL.md. The agent.rs glue is boilerplate.

2

Compile

The agent compiler parses THESEUS.md, discovers skills, and lowers the workspace to a CompiledAgent: JSON for tooling/CI, SCALE for on-chain.

3

Register

Submit the SCALE blob to register_ship_agent. The runtime decodes it into ABG nodes and enforces bounds (MaxAbgNodes, MaxToolsPerAgent, …).

4

Run

call_agent triggers the ABG. The source is no longer in the picture; the chain executes the decoded graph.

A canonical example

The Hello Agent workspace. The behavior lives in THESEUS.md and tools.yaml; the agent.rs glue lowers them to a CompiledAgent. This is the exact shape the playground deploys.

THESEUS.md
---
name: Hello Agent
id: hello-agent-v1
model: claude-sonnet-5
---

You are a friendly greeter agent running on the Theseus network.

When the user asks about balance or holdings, use the `check-balance`
skill before replying. Otherwise reply directly. Always answer in a
single warm, witty sentence.
tools.yaml
# Native tools run on-chain and are always available unless you
# restrict to a subset. Common tools are opt-in, off-chain, and
# verifiably executed from a curated registry.

native-tools:
  - tokens.balance
  - chain.transfer

common-tools:
  - web.fetch
agent.rs
use ship_types::{CompiledAgent, ExprSpec, ModelId, Node, StateField /* … */};

const THESEUS_MD: &str = include_str!("THESEUS.md");

pub fn hello_agent(model_id: ModelId) -> CompiledAgent {
    // Parse the frontmatter + system prompt from THESEUS.md, and
    // auto-discover every skills/<name>/SKILL.md next to this crate.
    let config = agent_compiler::parse_theseus_md(THESEUS_MD)
        .expect("THESEUS.md must be well-formed");
    let skills = agent_compiler::skills!();

    CompiledAgent {
        id: config.id,
        name: config.name,
        version: 1,
        ship_version: "1.0".into(),
        active: true,
        entry: 0,
        system_prompt: ExprSpec::String(config.system_prompt),
        // … ABG nodes, state fields, and the tool surface wired below
    }
}

THESEUS.md

YAML frontmatter (name, id, model) plus a Markdown system prompt, stored on-chain so anyone can read exactly what the model is told to do. The model is a tag the compiler resolves to a canonical ID.

tools.yaml

The capability surface. Native tools run on-chain; common tools are opt-in and verifiably executed off-chain. The runtime rejects any call outside this set.

skills/

Each skills/<name>/SKILL.md is a reusable procedure, auto-discovered at build time. Drop in a directory and it is picked up on the next build.

agent.rs → ABG

Lowers the workspace to a CompiledAgent: the Agent Behavior Graph (model calls, tool calls, routers, terminal nodes), the entry node, and ship_version.

Compile and register

The agent compiler lowers the workspace to a canonical CompiledAgent and emits both a JSON artifact (for editors, explorers, CI) and a SCALE blob (for the chain) from it.

terminal
# The workspace is a Cargo crate. Building it runs the agent compiler,
# which lowers THESEUS.md + tools.yaml + skills into a CompiledAgent.
cargo build --release

# In the playground, "Deploy this workspace" does the same lowering and
# submits the SCALE-encoded CompiledAgent to the chain for you.

Registration submits the SCALE blob via the chain’s register_ship_agent extrinsic. The runtime decodes it, applies pallet bounds, and stores AgentInfo + AbgNodes. From that point on, the agent is callable via call_agent.

The runtime doesn’t know about SHIP

On-chain code only ever sees a SCALE-encoded CompiledAgent blob. The workspace, the parser, and the compiler all live off-chain. That separation means new authoring formats can be added without touching consensus; they just need to produce the same canonical structure.

Design principles

Bounded by construction

Max ABG nodes, max tools per agent, max system prompt size: all enforced during SCALE decoding. A SHIP file that exceeds any bound fails registration.

Single source of truth

The same shared types power the compiler’s JSON output and the runtime’s SCALE decoding. They can’t drift.

Auditable

Anyone can inspect a deployed agent: pull AgentInfo + AbgNodes, render the graph, read the system prompt verbatim. Nothing is hidden in compiled bytecode.

Replaceable

The agent compiler is one toolchain, not a requirement. Anything that emits a valid CompiledAgent SCALE blob can register an agent.

Ecosystem examples

Public Theseus repos that ship SHIP-defined agents end-to-end.

proof-of-lobster

Persistent agent identity, scheduled execution, social interaction flows.

View repository →

the-prediction-market

Agent-to-contract calls, contract-to-agent callbacks, resolver workflows.

View repository →

SHIP toolchain

The agent compiler, shared ship_types, runtime helper, and the SHIP spec.

View repository →
Documentation