<div align="center">

Aielia · Build A Harness

Build a harness around your agent — the open-source control layer that makes AI agents reliable.

Aielia, the everyday AI assistant you can hand real work to, is built with it.

English · 中文

</div>

---

A harness is a governance and reliability control plane around an autonomous agent: the agent has intelligence, the harness has authority. The agent proposes; the harness decides what's allowed to happen next; evidence decides whether the result is accepted. Build A Harness is an open-source visual canvas and runtime for that layer — draw the 11 layers, compile the same FlowSpec to LangGraph / CrewAI / Mastra / MS Agent Framework, and trace every decision in Langfuse.

Aielia is the everyday assistant built with it, and the reference application: an agent you can hand real, multi-step work — research across a list, files to go through, a message to draft and send — while the full 11-layer harness controls what it may do, what it may believe, and what a job may cost, on every turn. Anything that can't be undone (writing a file, running a command, sending an email) is staged for your approval first, and a classifier that errors out requires approval rather than sailing through as safe.

Sites: buildaharness.com — the developer site · myaielia.com — Aielia, for everyone else.

---

1 · Build your own harness

A workflow routes prompts from node to node. A harness governs belief, permission, self-correction, and learning. Build A Harness delivers the complete 11-layer architecture as a visual builder.

Canvas  →  flow.json  →  LangGraph · CrewAI · Mastra · MS Agent Framework  →  Langfuse

The spec is the contract. The canvas is the editor. The adapters are the compilers.

| Simple Agent Loop | Full Harness — Implemented | |:--|:--| | Input / Caller | Caller State — constraints · clarification | | ↓ | World Model — beliefs · contradictions · generation_id | | LLM Call | Reasoning — evidence · hypotheses (4 sources) · VOI | | ↓ | Control ← key — 5-tier resolver · ALLOW/DENY permission · NORMAL/CAUTIOUS/RECOVERY mode | | Tool Call ↺ loop | Planning — task graph (6-state) · parallel concurrency | | ↓ | Execution + Verification — VOI gate · 9 layers | | Output | Recovery + Memory — 6 strategies · compression | | | Learning — experience store · warm start (optional) | | | Output & Reviewer Pass — contract · 3-lens review | | prompt in → answer out | 27 nodes · 11 layers |

<table> <tr valign="top"> <td width="50%">

Canvas & execution layer

• ✅ Canvas with 27 node types (14 execution + 13 harness)
• ✅ 4 framework adapters — LangGraph, CrewAI, Mastra, MAF
• ✅ Langfuse observability — harness traces across all runtimes
• ✅ HITL pause/resume · REST / MCP / A2A deploy
• ✅ FlowSpec v1.0.0 — open, portable JSON format
• ✅ Process concepts — pre-seeded task graph scaffolds

</td> <td width="50%">

Reasoning & control layer

• ✅ World model · typed beliefs · contradiction detection
• ✅ 5-tier control state resolver · deadlock detection
• ✅ Pre-execution review gate · 9-layer verification
• ✅ 6 named recovery strategies · typed failure library
• ✅ Experience store — cross-run structural reuse
• ✅ Adversarial reviewer pass · output contract validation

</td> </tr> </table>

The full node palette and schema-sync mechanics live in docs/nodes.md; the field-level FlowSpec reference is docs/flowspec.md.

Frameworks

All four runtimes compile from the same flow.json — no rewriting. /compile checks the target runtime's actual capabilities first: a FlowSpec requiring something the runtime doesn't support (durable checkpointing, token streaming) fails fast with a clear error instead of silently degrading.

| Runtime | Language | HITL | Key integration | |:--|:--|:--|:--| | LangGraph | Python | interrupt() | @observe · harness child spans | | CrewAI | Python | — | context_from → Task.context · tier-aware memory | | Mastra | TypeScript | suspend()/resume() | Node.js sidecar | | MS Agent Framework | Python | _HitlPause | AgentGroupChat native · OTel → Langfuse |

Compile: POST /compile?runtime=langgraph. Deploy as a REST endpoint, MCP tool, or A2A agent in one step.

Observability

Self-hosted Langfuse starts with docker compose up — no extra config. Per-node child spans across all four runtimes, token/latency/cost per node via LiteLLM, a live View trace → link in the canvas after each run, and managed prompts via the Langfuse prompt API (prompt_ref on any llm_call node).

---

2 · The reference application — Aielia

An agent you can hand real, multi-step work to, held in bounds by the harness — website and demo at myaielia.com.

npx @buildaharness/aielia

First run walks you through picking a provider (OpenRouter, Anthropic or OpenAI) and pasting an API key, which it checks before saving. Already logged in to the claude CLI? Skip the key with ASSISTANT_LLM_BACKEND=claude-cli npx @buildaharness/aielia. Then just talk to it.

import { LLMClient } from '@buildaharness/runtime'
import { PersonalAssistant } from '@buildaharness/aielia'

const aielia = new PersonalAssistant({ llmClient: new LLMClient({ proxyUrl, authToken }) })

await aielia.turn('What time zone is Tokyo in?')
// { status: 'ok', reply: '…', riskLevel: 'LOW', stepsUsed: 1 }

await aielia.turn('Send an email to my boss saying I quit.')
// { status: 'needs_approval', reason: '…', riskLevel: 'HIGH' }  — nothing sent, no reply generated

await aielia.turn('Send an email to my boss saying I quit.', { approved: true })
// approved — proceeds and runs the harness normally

Try it in your browser → myaielia.com/try — bring your own key (stored only in your browser), or see the approval gate fire before you add one.

One core, three front ends: terminal CLI, browser (@buildaharness/chat-ui), and native desktop (@buildaharness/desktop).

---

3 · What the harness controls in Aielia

The /harness-comparison page maps the three most-used open agents (Hermes Agent, Kilo Code, OpenClaw) against this architecture. None of them ships both a tiered Control State resolver and a reviewer/output gate. Aielia ships the following, all enforced in code rather than in a prompt:

• Live per-tool-call ControlState gate — every read-only tool call is checked against a per-turn ControlState before it runs (deterministic ALLOW / DENY / REQUIRE_APPROVAL, not advisory), so a developing failure pattern can trip a real deny mid-turn.
• Bounded jobs — for an explicit list of items, each gets its own bounded sub-search (budget calibrated on the first items), three dead ends in a row stop that item, a large batch asks for confirmation before it runs, and a hard per-turn ceiling caps total tool calls. Every item ends found, not_found, or truncated_while_productive; the reply never silently omits one.
• Fail-safe risk classification — a classifier error or unparseable response returns UNKNOWN → requires approval, never a silent default to low-risk.
• Reviewer Pass — a 3-lens review (consistency, adversarial, abstraction fit) and output-contract validation run in the harness on every turn; the reviewer's findings only revise a reply when the opt-in reviewer-revision layer is on.
• Typed fact provenance — facts you actually state promote to durable memory; model-inferred facts promote only at high confidence, medium-confidence ones wait for /memory confirm, and low-confidence ones stay session-scoped.
• AnswerClaim — replies distinguish "verified against evidence" from "found this but couldn't independently confirm it," surfaced in the chat's "Why?" panel.
• Crash-safe mid-turn resume — a turn that dies mid-flight resumes from its last checkpoint instead of silently starting over; a checkpoint that keeps crashing on replay is discarded automatically after two attempts.
• Untrusted-content boundary — web results and shell output are wrapped as data the model is instructed never to follow as commands.

Full write-up: packages/aielia/README.md.

---

Quick start

Just want to try Aielia? Nothing to clone:

npx @buildaharness/aielia          # terminal
# or open https://myaielia.com/try         # browser, bring your own key

Building and compiling harnesses needs the full stack (canvas + adapter API

• Langfuse):

./scripts/setup-env.sh   # generate secrets, write .env
docker compose up        # start all 11 services

| Service | URL | |:--|:--| | Canvas | http://localhost:3000 | | Adapter API | http://localhost:8000/health | | Langfuse | http://localhost:3001 |

<details> <summary>Without Docker</summary>

./scripts/setup-env.sh && source adapter/.venv/bin/activate
npm install && npm run dev        # canvas → localhost:3000
cd adapter && python main.py      # adapter → localhost:8000

</details> <details> <summary>Running tests</summary>

npm test                                         # Vitest — schema, canvas store and every package
pytest adapter/tests/ -v                         # adapter unit + integration
pytest adapter/tests/test_maf_adapter.py -v     # MAF suite (42 tests)

</details>

New here? Start with docs/getting-started.md · Startup errors? docs/troubleshooting.md · Real-time collaboration: docs/collab.md · On-prem / Kubernetes: docs/deployment.md

---

LLM providers

The assistant reaches a model directly (Anthropic, OpenAI, OpenRouter, or a claude CLI login). The full stack routes every call through LiteLLM — add the key to .env:

| Provider | Env var | Example models | |:--|:--|:--| | OpenAI | OPENAI_API_KEY | gpt-4o, gpt-4o-mini | | Anthropic | ANTHROPIC_API_KEY | claude-sonnet, claude-opus | | Ollama (local) | — | mistral, qwen3, qwen2.5-coder |

No API key? Install Ollama, run ollama pull mistral, then ./scripts/setup-ollama.sh — tests all four frameworks with no paid account.

Full setup: docs/llm-setup.md

---

Embed the canvas

npm install @buildaharness/canvas

import { BuildAHarnessCanvas } from '@buildaharness/canvas'
import '@buildaharness/canvas/styles.css'

<BuildAHarnessCanvas
  initialSpec={mySpec}
  onSpecChange={(updated) => save(updated)}
  execStats={runState.nodeStats}
  theme="dark"
/>

Full props reference: packages/canvas/README.md

---

Documentation

| | | |:--|:--| | docs/getting-started.md | Fresh clone → secrets → LLM → first run | | docs/nodes.md | The 27-node palette + schema-sync mechanics | | docs/flowspec.md | FlowSpec v1.0.0 — all 27 node types, edges, fields | | docs/architecture.md | System design, service interactions, data flows — the 11 layers as implementations of 5 primitives (State, Evidence, Policy, Effect, Recovery) | | docs/api.md | REST API reference — compile, execute, deploy, HITL resume | | docs/llm-setup.md | LLM provider setup — OpenAI, Anthropic, Ollama, custom | | docs/qdrant.md | Qdrant vector store — seeding, collections, production | | docs/env-vars.md | All environment variables across all services | | docs/collab.md | Real-time collaboration — Yjs setup and internals | | docs/deployment.md | Docker, Helm, SSO/OIDC | | docs/troubleshooting.md | Common startup errors | | docs/threat-model.md | The assistant's trust boundaries + accepted non-goals | | SECURITY.md | Supported versions + how to report a vulnerability | | CONTRIBUTING.md | How to contribute |

---

<div align="center">

Apache 2.0 — see LICENSE.

</div>