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
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.xexperimental,1.xstable (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
Author
Write the workspace: THESEUS.md, tools.yaml, and any skills/<name>/SKILL.md. The agent.rs glue is boilerplate.
Compile
The agent compiler parses THESEUS.md, discovers skills, and lowers the workspace to a CompiledAgent: JSON for tooling/CI, SCALE for on-chain.
Register
Submit the SCALE blob to register_ship_agent. The runtime decodes it into ABG nodes and enforces bounds (MaxAbgNodes, MaxToolsPerAgent, …).
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.
--- 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.
# 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
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.
# 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
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
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.
The same shared types power the compiler’s JSON output and the runtime’s SCALE decoding. They can’t drift.
Anyone can inspect a deployed agent: pull AgentInfo + AbgNodes, render the graph, read the system prompt verbatim. Nothing is hidden in compiled bytecode.
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.