Agents & Models
A four-file workspace that compiles into an on-chain entity with its own keys, balance, and state.
In one paragraph
THESEUS.md (frontmatter + system prompt), tools.yaml (tool surface in three optional blocks), skills/<name>/SKILL.md (activatable procedures), and agent.rs (SHIP IR boilerplate users rarely edit). The workspace compiles into an on-chain entity with its own seus balance, its own state, and a static Agent Behavior Graph (ABG). Agents are event-driven, not always-on: they wake on triggers (events, schedules, or external call_agent), execute their ABG until an inference or tool call suspends them, and resume in a later block when the verified result lands.- ABG = bytecode: static, versioned, capped at 256 nodes per agent. Encodes both control flow and the agent’s declared capability surface.
- AKG = execution log: dynamic graph of runs, steps, and observations. Mostly DA-backed via pallet_store with on-chain anchors.
- Three-stage execution: queue (call_agent) → prove (submit_inference_result) → resume (inherent hook on next block).
- Reverse gas: the agent pays for its own seus, not the caller. At zero balance it stops; after 90 days at zero its state is reclaimed.
- Sub-agent calls bounded at depth 2: an agent can call another, but the callee can’t call a third.
See an agent in code
The bundled Hello Agent template in the playground is the smallest real example: a minimal THESEUS.md (frontmatter + greeter prompt), a placeholder tools.yaml with the three-block structure commented out, one skill at skills/check-balance/SKILL.md, and a standard agent.rs tool-loop. Browse the live PoA directory for production-shaped examples.
Agent file format
An agent directory holds four files at the workspace root, each with a separate concern. The on-chain parser ( parse_theseus_md in the agent-compiler crate) recognises a small frontmatter schema in THESEUS.md; unrecognised fields are silently ignored.
| File | What it holds |
|---|---|
THESEUS.md | YAML frontmatter ( name, id, model, and an optional schedule: interval_blocks: N that defaults to 30 blocks when absent) followed by the system prompt body. That is the entire frontmatter schema. No models array, no native-tools field, no sovereign / controller / intent_types. Tool permissions live in tools.yaml; control flow lives in agent.rs. |
tools.yaml | Tool surface in three optional blocks: native-tools (allowlist into the on-chain native catalog), common-tools (opt-in to the chain-curated off-chain catalog, currently web_fetch and web_search), and byo-tools (inline JSON-schema for tools you run yourself). |
skills/<name>/SKILL.md | Activatable procedures with frontmatter name / description / allowed-tools / optional auto-activate. When a skill activates its body is injected into the system prompt and its allowed-tools enter the run's effective tool set. |
agent.rs | The SHIP IR program the chain actually compiles. The default template ships a standard tool-loop (init → think → act → loop → done) that reads the other three files at compile time. Edit it only when you need a non-standard graph. |
See /docs/playground for the file shapes in the IDE.
Agent Registration
Deployment is one extrinsic on pallet_agents: register_ship_agent(value, payload, salt). The agent address is derived deterministically from the deployer, the compiled hash, and the salt, so redeploying identical bytes from the same deployer fails on chain with AgentAlreadyExists.
| Argument | What it is |
|---|---|
value | Initial seus endowment transferred from the deployer into the agent's account. The agent spends from this for inference and tool calls. |
payload | SCALE-encoded CompiledAgent: the output of compiling the workspace (THESEUS.md + tools.yaml + skills + agent.rs) with the WASM agent-compiler. |
salt | Per-deployment salt. Rotate it (Playground: Deploy as fresh agent) to mint a new address for the same compiled bytes. |
Address formula: blake2_256(b"theseus_agent_v1" | deployer | compiled_hash | salt). On success the pallet emits Registered { agent_id, owner, name, compiled_hash, evm_address, version, endowment, tools_count, system_prompt_hash, input_schema_hash }.
Model Registration
Models are registered on pallet_models via register_model(model_tag, weights_root). Registration is Root-only at alpha; any agent can then reference the tag from their THESEUS.md model: field.
| Argument | What it is |
|---|---|
model_tag | Bounded UTF-8 tag (max 64 bytes) that agents reference (e.g. claude-sonnet-4-6). Hashed to a 32-byte ModelId used internally by the runtime. |
weights_root | Optional content-addressed root anchoring the model weights in TheseusStore. Lite-prover-only models can omit it; TensorCommitment provers verify against it. |
Inference fees and economics (per-FLOP pricing, payout to provers) are tracked separately via /docs/tokenomics.
Sovereign Agent Inference Loop
How sovereign agents decide when to run inference, without human sign-off or off-chain schedulers:
Wake trigger fires
Scheduled block height, an on-chain event the agent subscribes to, or an external call_agent.
ABG advances
pallet_agents interprets the agent's behavior graph through synchronous nodes (conditions, sequence, parallel) until it hits a model or tool call.
Reverse-gas check
The agent pays from its own seus balance. At zero balance the agent stops running; the call doesn't queue.
Queue + suspend
AIVM queues the inference job and emits InferenceQueued. The agent suspends. A prover picks it up, submits a verified result, and the agent resumes via on_initialize on a later block.
Fully Sovereign
Inter-Agent Interaction
Agents hold their own SS58 account, balance, and on-chain state, so they can call other agents the same way an external caller does: via the call_agent extrinsic, scheduled from a sub-agent node in the calling agent's ABG. The interaction follows the same three-stage queue → prove → resume pattern as any other call.
- Capability surface enforced: the calling agent's ABG declares which other agents it may invoke; calls outside that surface are rejected at compile time.
- Call depth capped at 2: an agent can call another agent, but the callee cannot call a third (
MaxAgentCallDepth = 2in the runtime). Keeps fan-out bounded for block-weight accounting. - Origin preserved: SHIP intents emitted by the callee run under the original caller's origin, so fee accounting and authorization stay coherent across the chain.
Model Usage Fees
Inference is paid for in seus (the USD-denominated gas unit, bought one-way with frxUSD over the Layer0 bridge). The agent spends from its own balance for every model call and tool dispatch; the chain pays out from treasury to provers in frxUSD on a separate cadence.
The $THE staking + slashing token is not live at alpha. Per the roadmap it lands with Beta, when open prover registration introduces economic security. See /docs/tokenomics for the full payout model.