Skip to content

Zakardo Documentation

Welcome to the Zakardo documentation. Zakardo is an agent-native full-stack application framework that introduces a new execution model: agent behavior is expressed as structured, versioned, validated programs called plans, composed of governed, typed units of execution called capabilities, triggered by user intents.

Current AI agent frameworks treat agent behavior as an emergent property of prompt engineering and tool calling. This model has fundamental issues:

  • No inspectable program — There is no versioned, testable artifact describing what an agent will do before it does it
  • No governance — Side effects are fire-and-forget with no policy layer
  • No learning loop — Successful agent behavior is not captured as a reusable artifact
  • No auditability — Logs are unstructured and not replayable
  • No composability — Every framework defines its own incompatible tool interface
  • No frontend model — No architecture exists for intent-driven, plan-aware user interfaces

The gap is not “better tools for agents.” The gap is a missing execution model.

Zakardo asks: How do I build, govern, validate, and trust the programs that agents execute?

Every Zakardo application runs through the same core loop:

Intent → Planner → Plan Draft → Enrichment → Full Plan IR → Validator → Execution Engine → Trace
  1. Intent — The user expresses a desired outcome in natural language
  2. Planner — An LLM-powered, policy-aware planner generates a minimal Plan Draft via backward chaining
  3. Enrichment — A deterministic 8-step pipeline converts the draft into a fully typed Plan IR
  4. Validator — 10 structural and policy checks verify the plan is safe to execute
  5. Execution Engine — A durable state machine runs the plan with checkpointing, retry, and governed side effects
  6. Trace — An immutable, append-only record captures everything for auditing, replay, and learning
ConceptWhat It Is
IntentUser request (natural language, packaged action, or structured form) — the entry point
PlanStructured, versioned program of capability invocations with typed data flow
CapabilityTyped, versioned unit of execution with declared inputs, outputs, effect class, and boundary
Effect ClassWhat a capability does: READ, WRITE_INTERNAL, WRITE_EXTERNAL, DESTRUCTIVE
TraceImmutable, replayable record of every execution event
Policy / GateGovernance rules that pause execution for human approval
A2UIGoogle’s Agent-to-UI protocol — declarative, streaming frontend rendering

Zakardo has completed 8 implementation phases with 1,140+ tests across all packages:

PhaseDeliverables
1Type system, capabilities, Plan IR, enrichment pipeline, validator
2Execution engine, policy engine, trace system, data layer, gate/interaction/retry handlers
3LLM provider abstraction, prompt architecture, planner pipeline, plan library
4Config system, runtime bootstrap, Hono server, REST + SSE endpoints, client SDK
5CLI (zakardo), scaffolding tool (create-zakardo), dev server, validators, generators
6A2UI composition engine, standard catalog, React renderer (@zakardo/a2ui-react)
7Training datasets, result comparison, regression detection, lifecycle management
8Zakardo Studio, enhanced testing utilities, reference CRM app
PackagePurpose
@zakardo/coreCore runtime — types through server
@zakardo/clientZero-dep typed TypeScript client SDK (HTTP + SSE)
@zakardo/a2uiFramework-agnostic A2UI v0.8 client core
@zakardo/a2ui-reactReact renderer, hooks, lifecycle components, Zakardo Catalog
@zakardo/cliDeveloper tooling — dev, validate, build, migrate, generate, training, trace
create-zakardoProject scaffolding — npx create-zakardo my-app
@zakardo/studioVisual dev tool — capability browser, intent playground, trace viewer
@zakardo/testingTest utilities — factories, mocks, test runtime, custom matchers

New to Zakardo?

  • Introduction — What Zakardo is and how it differs from other frameworks
  • Installation — Set up Zakardo in your project
  • First Project — Create your first agent-native app in minutes

Scaffold a full project:

Terminal window
npx create-zakardo my-app

Key topics:

  • Concepts — Intents, plans, capabilities, effect classes, traces, policies, A2UI
  • Architecture Overview — System design, two-layer backend, execution loop
  • Building a CRM — End-to-end guide with 10 capabilities and governance policies
  • API Reference — Core types, enrichment pipeline, validator, execution engine, runtime API, and more