How Zakardo Works
A plain-English walkthrough of the core ideas. No jargon walls. Whether you're a backend engineer, a frontend dev, or someone building AI apps on weekends — this is for you.
The Big Idea
Most AI agent frameworks work like this: you give an LLM some tools, a prompt, and a goal. The LLM reasons about what to do, calls tools in a loop, and hopefully produces a useful result. The problem? There is no program. The agent's behavior is whatever the LLM decides at inference time. You can't inspect it, test it, or approve it before it runs.
Zakardo flips this model. Instead of letting the AI improvise, Zakardo makes it write a program first. That program is called a Plan. The Plan is validated, enriched, and then executed by a deterministic engine. The AI is the author. Your runtime is the executor.
The Execution Loop
Everything in Zakardo follows one loop. Here's the full journey of a user request:
Intent
A user says something. "Show me all VIP contacts" or "Send the Q4 report to the team." This is an Intent — the entry point. It can be natural language, a button click, or a structured form.
Planner
The Planner (powered by an LLM) looks at the intent, checks what capabilities are available, and produces a Plan Draft — a structured JSON document listing exactly which capabilities to call, in what order, with what inputs. Think of it like a recipe.
Enrichment
The Plan Draft is minimal (that's by design — we want the LLM to produce as little as possible). Your runtime then enriches it: resolves schemas, computes dependencies, assigns metadata, adds error policies. This is 100% deterministic. No LLM involved.
Validation
The enriched Plan goes through 11 validation checks: structural integrity, capability availability, schema compatibility, dependency graph analysis, policy compliance, and more. If any check fails, the plan is rejected. Nothing runs until it passes.
Execution
A durable state machine runs each step of the plan. After every step, it checkpoints its state. If the process crashes mid-execution, it resumes exactly where it left off. External side-effects (API calls, emails) are staged in an outbox and only committed after all steps succeed.
Rendering
Results stream to the user in real time as the plan executes. The UI updates live via SSE using a protocol called A2UI (Agent-to-User Interface). Your React components render what the agent is doing as it happens — not after it's done.
Capabilities: What Agents Can Do
A Capability is a single thing your agent can do. "Look up a contact." "Send an email." "Generate a report." Each capability is a TypeScript definition with:
Typed inputs and outputs — JSON Schema. The runtime knows exactly what data flows in and out.
An effect class — Does this capability only read data? Does it write to your database? Does it call an external API? Is it destructive (deletes data)?
A boundary — Does it run locally, call a remote service, or execute in the user's environment?
A version — Capabilities are versioned with semver. You can run v1 and v2 side by side.
You write the capability definition (the "what"). You also write the implementation (the "how"). Zakardo connects them. The Planner sees the definitions. The Execution Engine runs the implementations.
Plans: Programs, Not Prompts
A Plan is a structured, versioned, executable program. It's JSON. It lists capability invocations in order, with typed data flowing between them. Here's what a simple plan looks like in plain English:
Plans go through a lifecycle: Candidate (new, unproven) → Shadow (running alongside proven plans) → Promoted (trusted, preferred by the Planner) → Deprecated or Quarantined (retired or failed). Plans that work well get promoted. Plans that fail get quarantined. Your agents get better over time.
Governance: Nothing Runs Without Permission
Zakardo has a built-in Policy Engine that evaluates rules at three points:
Before generation — The Planner checks policies before even building a plan. If a capability is policy-blocked, the Planner finds an alternative.
Before execution — The full plan is checked against policies before any step runs.
Per step — Each capability invocation is checked individually at runtime.
When a plan includes a destructive action (deleting records, sending external emails), Zakardo inserts a Gate — a pause point that requires human approval. The execution halts, the user sees what's about to happen, and explicitly approves or rejects it. No surprises.
Every execution produces an immutable Trace — a complete record of what happened: every step, every input, every output, every gate, every decision. Replayable. Auditable.
The Stack
Zakardo is a full-stack framework. Here's what ships in v1.0:
Runtime
Hono server with REST + SSE endpoints. Config system, auth middleware, runtime bootstrap.
Planner
LLM-powered plan generation with 4 provider options (OpenAI, Anthropic, Gemini, Ollama). Backward chaining algorithm.
Execution Engine
Durable state machine with checkpointing, retry, gates, interaction points, and deferred side-effect outbox.
Frontend
React renderer with 30+ components that update live over SSE. Light and dark themes. Based on Google's A2UI spec.
CLI
13+ commands. Code generators for capabilities, routes, policies. Dev server, build, validate, migrate, seed.
Studio
Visual dev tools: capability browser, intent playground, plan explorer, trace viewer, training dashboard.
Testing
Training datasets, regression detection, plan lifecycle automation. Custom Vitest matchers.
Client SDK
Zero-dependency TypeScript SDK. Typed HTTP + SSE clients. Works in any frontend.
TL;DR
- 1. User submits an Intent (natural language or structured input)
- 2. The Planner (LLM) writes a structured Plan using your declared Capabilities
- 3. The runtime validates the plan (11 checks) and enriches it with schemas and metadata
- 4. A durable Execution Engine runs it step by step with checkpoints, gates, and retries
- 5. Results stream to the UI in real time as each step completes
- 6. An immutable Trace records everything. Plans that work get promoted. Agents improve over time.
Interested? Get notified when v1.0 launches.
Join the Waitlist →