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.
The Problem Zakardo Solves
Section titled “The Problem Zakardo Solves”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?
How Zakardo Works
Section titled “How Zakardo Works”Every Zakardo application runs through the same core loop:
Intent → Planner → Plan Draft → Enrichment → Full Plan IR → Validator → Execution Engine → Trace- Intent — The user expresses a desired outcome in natural language
- Planner — An LLM-powered, policy-aware planner generates a minimal Plan Draft via backward chaining
- Enrichment — A deterministic 8-step pipeline converts the draft into a fully typed Plan IR
- Validator — 10 structural and policy checks verify the plan is safe to execute
- Execution Engine — A durable state machine runs the plan with checkpointing, retry, and governed side effects
- Trace — An immutable, append-only record captures everything for auditing, replay, and learning
Key Concepts
Section titled “Key Concepts”| Concept | What It Is |
|---|---|
| Intent | User request (natural language, packaged action, or structured form) — the entry point |
| Plan | Structured, versioned program of capability invocations with typed data flow |
| Capability | Typed, versioned unit of execution with declared inputs, outputs, effect class, and boundary |
| Effect Class | What a capability does: READ, WRITE_INTERNAL, WRITE_EXTERNAL, DESTRUCTIVE |
| Trace | Immutable, replayable record of every execution event |
| Policy / Gate | Governance rules that pause execution for human approval |
| A2UI | Google’s Agent-to-UI protocol — declarative, streaming frontend rendering |
What’s Built
Section titled “What’s Built”Zakardo has completed 8 implementation phases with 1,140+ tests across all packages:
| Phase | Deliverables |
|---|---|
| 1 | Type system, capabilities, Plan IR, enrichment pipeline, validator |
| 2 | Execution engine, policy engine, trace system, data layer, gate/interaction/retry handlers |
| 3 | LLM provider abstraction, prompt architecture, planner pipeline, plan library |
| 4 | Config system, runtime bootstrap, Hono server, REST + SSE endpoints, client SDK |
| 5 | CLI (zakardo), scaffolding tool (create-zakardo), dev server, validators, generators |
| 6 | A2UI composition engine, standard catalog, React renderer (@zakardo/a2ui-react) |
| 7 | Training datasets, result comparison, regression detection, lifecycle management |
| 8 | Zakardo Studio, enhanced testing utilities, reference CRM app |
Packages
Section titled “Packages”| Package | Purpose |
|---|---|
@zakardo/core | Core runtime — types through server |
@zakardo/client | Zero-dep typed TypeScript client SDK (HTTP + SSE) |
@zakardo/a2ui | Framework-agnostic A2UI v0.8 client core |
@zakardo/a2ui-react | React renderer, hooks, lifecycle components, Zakardo Catalog |
@zakardo/cli | Developer tooling — dev, validate, build, migrate, generate, training, trace |
create-zakardo | Project scaffolding — npx create-zakardo my-app |
@zakardo/studio | Visual dev tool — capability browser, intent playground, trace viewer |
@zakardo/testing | Test utilities — factories, mocks, test runtime, custom matchers |
Get Started
Section titled “Get Started”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:
npx create-zakardo my-appKey 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