OpenSeal Agent Architecture Deep Dive: Persistent Orchestration and Approval Governance

Open-source AI agent platforms are proliferating, but few actually deliver on "resumable tasks, auditable actions, and traceable state" in a rigorous way. OpenSeal answers a core question with an explicit persistent execution model: when an agent has prepared a draft and needs human approval before sending, where exactly does that task live, how does a worker pick up the next step, and what happens to the system while a human is reviewing?

This article follows the lifecycle of a real task to break down OpenSeal's architectural design — examining how it builds a reliable orchestration and governance layer on top of model inference.

Persistent Execution Path: From Prompt to Skill Invocation

OpenSeal's main sequence is a clear chain: prompt or event → Agent or Team → Objective → Run → Turn → Skill action.

Understanding this chain requires grasping the responsibility of each layer. An Agent or Team owns an Objective; the Objective describes a desired outcome; the Objective produces a Run; and the Run advances step by step in units called Turns. When a capability beyond model inference is needed, a Turn triggers a Skill action.

Take a draft task as an example: the goal of the draft is always stored in the Objective, while the Run records the act of "attempting to achieve the goal." The key insight is — if work must wait (say, for human approval), you can read the state of that Run at any time without keeping the original API request hanging. This is precisely what "persistent" means: the task exists independently of the request connection's lifecycle.

Recovering Interrupted Work with Leases

One of the trickiest problems in distributed systems is a worker dying mid-execution. OpenSeal's solution is the lease mechanism.

A worker "claims" a Turn for a set period of time — that claim is called a lease. If the worker stops renewing its lease, it expires, and the Turn becomes available for another worker to pick up. When a worker task stops partway through, inspecting the lease record pinpoints the problem.

Every phase is saved before it executes, and the awaiting-approval state is saved as well. This gives both execution and review a shared storage location that survives process restarts.

However, OpenSeal's documentation specifically calls out a common misread: don't treat this as an exactly-once guarantee for external tools. The side effects of each Skill and the services it calls must be evaluated independently. A proper restart test should verify both the saved Run state and the real-world external outcome — only when both are correct can you consider the recovery successful.

The lease mechanism stems from a classic distributed systems problem: how do you tell whether a worker node is "running slowly" or "has crashed"? Since you can't directly distinguish between the two from the outside, leases use a time window as a proxy for certainty — workers must actively renew within the allotted time, or the system assumes failure. This is conceptually identical to Kubernetes Pod liveness probes, ZooKeeper ephemeral nodes, and database row-level lock timeouts.

It's worth noting that a lease expiring doesn't mean the task definitely wasn't executed — the original worker may have completed some operations but crashed before writing the state back. This is precisely why OpenSeal explicitly warns against "exactly-once guarantees for external tools": leases only guarantee that a task will be retried, not that already-produced side effects can be rolled back. For irreversible operations like sending emails or processing payments, idempotency checks must be implemented at the business layer.

Check Capabilities Before Routing Calls

A practical design detail: two OpenSeal service instances at the same version number may expose entirely different sets of operations. The available API surface depends on the storage contract, connected components, and full configuration.

curl http://127.0.0.1:8080/api/v1/capabilities

Specifically, creating a Run requires a dispatcher; resolving approvals requires an authorizer; authoring a Workforce requires a complete model endpoint, credentials, and model name. There's an important principle here: missing capabilities aren't just hidden from the client — the corresponding operations simply aren't served.

This design lets a "thin client" work against both a local service and a larger embedded host. The terminal client only reads what the server declares as available and has no authoritative state of its own — so shutting down the client leaves the persistent work running in the background.

By comparison, the health endpoint is a much weaker check. It returns a fixed response and doesn't prove that the database, workers, or model providers can actually complete your task.

Keeping Orchestration State Explicit

OpenSeal deliberately distinguishes waiting states in fine-grained detail. A Run might be waiting on a dependency, waiting on another agent, waiting for approval, or waiting for an inbound event — these are different states by design, because they require different responses. Waiting for another Run to complete is fundamentally different from waiting for a human decision.

Agents can request work from each other via saved requests. These exchanges go through creation, response, completion, and an optional completion review. Because these records are stored, a request can outlive the Run that initiated it.

Agent and Team definitions have immutable saved versions, and deployments can switch versions, enabling rollback to earlier ones. A change proposal goes through distinct steps — proposal, review, decision, and activation. Crucially, saving a decision is not the same as activating the change. This explicit step-by-step governance dramatically reduces the risk of accidental changes in production.

Governing Actions at the Skill Boundary

The Skill boundary is OpenSeal's governance core. Registering a Skill makes its definition known to the system, while a binding grants it to a specific Agent or Team deployment. Team-level authorization and member-level authorization are separate.

When policy requires review, an action invocation pauses at a persistent approval checkpoint. There's a key safety floor here: a missing approval authorizer does not degrade into auto-approve permission. In local mode, a standalone operator flag enables local decisions, and it requires a loopback address.

Activity events and the state changes they describe are saved in the same transaction. Credential values are resolved at action runtime and are excluded from saved state, prompts, and terminal clients.

Host boundary responsibilities are equally non-negotiable: the standalone API provides neither authentication, request authorization, nor TLS — these must be supplied by the host or a proxy. Local approval records use user:local, so they don't tell you which specific person clicked approve — worth noting in scenarios that require audit accountability.

The design of "saving activity events and state changes in the same transaction" resolves a classic distributed systems consistency problem: if you write state first then emit an event, a crash leaves the state changed but observers unaware; if you emit the event first then write state, the event describes a change that hasn't actually happened yet. OpenSeal binds both to the same database transaction, ensuring that "recorded events" and "persisted state" are in strict correspondence — downstream consumers or audit logs that see an event are guaranteed to reflect real state. In Event Sourcing architectures, this pattern is a variant known as the "Transactional Outbox" pattern, and it's a foundational building block for auditable systems.

Putting Model Routing at the Right Layer

Workforce authoring accepts an OpenAI-compatible endpoint, which can point to a compatible LLM gateway that exposes multiple models. The path is OpenSeal authoring → gateway → model provider.

The authoring setup described in the documentation selects one endpoint, one credential, and one model name. This does not mean the core automatically picks different models for different tasks — gateway routing and fallback rules must be configured and tested separately.

This boundary separates "provider access" from the "persistent work model." To test a different supported model, change the model setting and compare results, while confirming that proposals still go through the full review and application flow.

Know Which Execution Path You're On

This is the easiest place to trip up. The standalone service uses SQLite; PostgreSQL requires the Go embedding layer and is not a supported storage option for standalone. Projects group objectives for source tracking and outreach, and the Run command lets teams pause, resume, cancel, or intervene.

More critically, OpenSeal has a separate HCL runbook path executed via openseal run. It runs a typed graph inside a single process and does not share the persistent Run lifecycle, approvals, or activity streams. Do not assume that runbook commands inherit the guarantees described by the persistent core.

HCL (HashiCorp Configuration Language) is a structured configuration language designed by HashiCorp, widely used in Terraform, Packer, and similar tools. OpenSeal's runbook path borrows this format to describe step dependencies in a directed graph (DAG) and executes them in topological order within a single process. The fundamental difference from the persistent core lies in the execution model: runbooks are "one-shot, synchronous, in-process" task runners, similar to a CI/CD pipeline; the persistent core is an "asynchronous, cross-process, interruptible-and-resumable" state machine. Neither is inherently superior — they target completely different scenarios. The former suits scripted batch tasks; the latter is the right choice for agent workflows that require human approval and long-term tracking. Conflating the two paths leads to serious misjudgments about system guarantees.

A Minimal Evaluation Plan

To genuinely validate OpenSeal, work through a minimal closed loop:

1. Read capabilities, connect the required workers, create a small objective;
2. Observe its Run and individual Turns;
3. Try an allowed action first, then one that requires review;
4. Restart the service while a review is pending;
5. Simultaneously check the saved approval state and what the action changed outside of OpenSeal.

Record the state before and after the restart and compare — this comparison will tell you whether the task recovered as expected and where you still need more test coverage.

For teams using agents in production, OpenSeal's value isn't in "what the agent can do" — it's in explicitly modeling the engineering hard parts: task persistence, recovery, approval, and auditing. These are precisely the pieces that most rapid-prototyping frameworks skip.