realm
sensigo-hq/realm
Make AI agents follow instructions reliably and prove what they did. State machine engine with evidence chains, multi-agent delegation, human gates, and auditable execution — via MCP or CLI.
Instalação
npx convez-ai sensigo-hq/realm1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Realm
The agent calls Realm. Every other tool calls the agent.
Most AI workflow platforms orchestrate LLMs as services: the platform decides when to call the model, what to send, and what to do with the result. Realm inverts this. The agent calls execute_step via MCP. Realm's state machine responds with the current step's task and schema. The agent executes. It cannot skip steps, produce malformed output, or proceed past a human gate — not because of instructions it might ignore, but because the state cannot change until valid output is submitted.
If your skill file has grown a list of "Do NOT" rules, each one is a scar from a failure the agent invented. Realm replaces those rules with structure: wrong behaviour becomes impossible rather than prohibited.
You define workflows in YAML. The engine enforces step order, validates every agent output against a JSON schema, captures tamper-evident evidence at each step, and pauses at human gates until a person approves. The result is not just a log of what ran — it is a cryptographically verifiable record that every step ran correctly. For developers building AI workflows for clients, that record is the deliverable.
Packages
Installation
CLI (global)
npm install -g @sensigo/realm-cli
MCP server (global, for AI agent connections)
npm install -g @sensigo/realm-mcp
Programmatic use
npm install @sensigo/realm
Testing utilities
npm install --save-dev @sensigo/realm-testing
Quick Start
1. Scaffold a workflow
realm workflow init my-workflow
This creates my-workflow/ with workflow.yaml, schema.json, .env.example, and a README.md.
2. Edit my-workflow/workflow.yaml
id: my-workflow
name: 'My Workflow'
version: 1
steps:
gather_input:
description: 'Agent collects the required information'
execution: agent
depends_on: []
input_schema:
type: object
required: [summary]
properties:
summary:
type: string
finalize:
description: 'Human reviews and approves the submitted summary'
execution: auto
depends_on: [gather_input]
trust: human_confirmed
3. Validate, register, and run
realm workflow validate ./my-workflow # check the YAML
realm workflow register ./my-workflow # register with the local store
realm workflow run ./my-workflow # run interactively (development mode)
realm workflow run drives the workflow step by step, prompting you for simulated agent output and pausing at human gates.
Connect an AI Agent via MCP
Start the MCP server (built into the CLI — no extra install needed):
realm mcp
Claude Desktop — claude_desktop_config.json
{
"mcpServers": {
"realm": {
"command": "realm",
"args": ["mcp"]
}
}
}
Cursor — ~/.cursor/mcp.json
{
"mcpServers": {
"realm": {
"command": "realm",
"args": ["mcp"]
}
}
}
Hosted agent platforms (OpenClaw, Claude.ai, custom backends) that cannot spawn a local subprocess use realm serve instead:
REALM_SERVE_TOKEN=<secret> realm serve --port 3001
This starts an HTTP MCP server protected by Bearer token authentication. Use --dev to skip auth during local development.
Once connected the agent has access to 9 tools: list_workflows, get_workflow_protocol, start_run, start_run_batch, execute_step, submit_human_response, get_run_state, create_workflow, and list_runs.
The agent calls list_workflows to discover registered workflows, then get_workflow_protocol for the matched workflow to receive explicit step-by-step instructions. It cannot execute a step out of order or submit output that fails schema validation.
When no registered workflow matches the task, the agent calls create_workflow with a steps array to register a dynamic workflow and immediately start a run — no YAML file or realm workflow register required. The run proceeds identically to a YAML workflow from that point.
Multiple workflows: register as many as you need with realm workflow register. The agent discovers them all via list_workflows and picks the right one by ID. Add a skill.md alongside each workflow for workflow-specific agent behaviour.
CLI Reference
| Command | Description |
|---|---|
realm workflow init <name> | Scaffold a new workflow project directory |
realm workflow validate <path> | Validate a workflow YAML without registering it |
realm workflow register <path> | Register a workflow in the local store |
realm workflow watch <path> | Watch a workflow YAML and re-register on every change |
realm workflow run <path> | Run a workflow interactively (development mode) |
realm agent | Run a workflow autonomously with an LLM — no MCP client or IDE required |
realm workflow test <path> | Run fixture-based tests against a workflow |
realm run list | List all runs; filter by --workflow <id> or --status <phase> |
realm run resume <run-id> | Resume a paused run |
realm run respond <run-id> | Submit a response to a human gate |
realm run inspect <run-id> | Print the full evidence chain for a run |
realm run replay <run-id> | Re-evaluate preconditions with modified step outputs |
realm run diff <run-a> <run-b> | Compare evidence chains of two runs side by side |
realm run cleanup | Mark idle non-terminal runs as abandoned |
realm workflow migrate | Back-fill provenance fields on local workflow definitions from earlier versions |
realm mcp | Start the MCP server over stdio (for local AI agents) |
realm serve | Start the MCP server over HTTP with Bearer token auth (for hosted platforms) |
realm webhook | Start a webhook server that creates runs from GitHub events |
Run realm <command> --help for full options on any command.
Documentation
- Getting Started — end-to-end walkthrough including service adapters, human gates, and step handlers
- YAML Schema Reference — all step fields, execution modes, transitions, trust levels, agent profiles
- Handler Authoring Reference —
StepHandlerinterface,StepContextfields, primitives catalogue, built-in handlers, registration - MCP Protocol Reference — tools, response envelope, next_action, agent_action
- CLI Reference — all commands with options
- Built-in Service Adapters —
FileSystemAdapter,GitHubAdapter,GenericHttpAdapter— config, operations, response shapes - Testing Reference —
@sensigo/realm-testingfull API: fixture runner, mocks, assertions, GitHub mock server - Examples — working workflow examples
Development
Prerequisites: Node.js 22+, npm 10+
npm install # install all workspace dependencies
npm run build # compile all packages
npm run test # run all tests
npm run lint # lint all packages
License
Apache 2.0