Skip to content
Developer docs

Architecture

The control-plane model behind Promptsheon: immutable agent specifications, evidence-producing execution, and bounded adaptation.

The system in one sentence

Promptsheon is an adaptive agent engineering platform for building, executing, evaluating, and continuously improving AI agents and multi-agent systems.

The product model

An agent is not just a prompt attached to a model. It is an immutable, content-addressed executable specification composed of role, objective, prompts, guardrails, capabilities, tools, permissions, context, model and routing policies, execution rules, evaluation intent, budgets, and lifecycle.

AgentSpec = role + objective + prompt + guardrails + tools
          + permissions + context + model + routing
          + execution + evaluation + budget + lifecycle

Create → Execute → Observe → Evaluate → Compare
       → Learn → Mutate → Validate → Promote

Four control-plane responsibilities

Architect

Translates an objective into an executable organization: agent responsibilities, topology, interfaces, capabilities, and evaluation strategy.

Operator

Executes the specification: scheduling, parallelism, model routing, tools, retries, state, caching, and result materialization.

Evaluator

Measures quality and efficiency before, during, and after execution, then turns observations into comparable evidence.

Governor

Enforces hard limits for context, tokens, models, latency, cost, concurrency, tools, permissions, memory, and execution.

Four boundaries

Domain

Types, invariants, transitions, hashes, and policy concepts. No Fastify or SQLite dependency.

Application

Use cases such as release transitions, schedules, approvals, identity, and evaluation orchestration.

Infrastructure

SQLite repositories, CAS, vault/KMS adapters, LLM providers, schedulers, and observability.

Interface

Fastify routes, validation, HTTP error contracts, SSE, CLI, SDK, and the Next.js console.

Dependency direction

interface / route  →  application service  →  port / repository
       ↓                         ↓
   validation              domain invariant
       ↓                         ↓
 infrastructure adapter  →  SQLite, vault, provider

Routes parse and translate. Services decide. Repositories persist. Domain code owns rules. When a route needs to construct a database repository or reach into a provider directly, that is a boundary smell.

Release lifecycle

Draft, review, approval, canary, active, and rollback are explicit transitions. The release service checks the current state, approval requirements, authorization, and audit side effects before changing persistence. Consumers should use the service rather than duplicating transition rules.

Why content addressing matters

A manifest’s hash gives the team a stable identity for the exact content that was evaluated and released. It makes diffs reviewable, rollback deterministic, and audit records meaningful even when names or labels change.

Adding a feature

  1. Define the domain concept and invariant.
  2. Expose the smallest application service or port needed.
  3. Add the infrastructure adapter and repository mapping.
  4. Add a validated interface route and typed client contract.
  5. Cover the invariant, failure path, integration boundary, and browser-critical flow.