Skip to content

First Project

This tutorial walks you through building a minimal Zakardo application from scratch. You will define a capability, configure the runtime, start the server, submit an intent, and inspect the trace.

A simple note-taking service with two capabilities:

  • notes_list — list all notes (READ)
  • notes_add — add a new note (WRITE_INTERNAL)
Terminal window
mkdir my-notes-app && cd my-notes-app
pnpm init
pnpm add @zakardo/core hono @hono/node-server better-sqlite3 ajv ajv-formats semver
pnpm add -D typescript @types/node @types/better-sqlite3 @types/semver tsx

Create a tsconfig.json:

{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"esModuleInterop": true,
"outDir": "dist",
"rootDir": "src"
},
"include": ["src"]
}

Add "type": "module" to your package.json.

Create src/capabilities.ts:

import type { CapabilityDefinition, CapabilityFn } from '@zakardo/core';
// In-memory store for this tutorial
const notes: Array<{ id: string; title: string; body: string; created_at: string }> = [];
// --- List Notes ---
export const listNotesCapability: CapabilityDefinition = {
name: 'notes_list',
version: '1.0.0',
description: 'List all notes, optionally filtered by title keyword.',
effect_class: 'READ',
boundary: 'LOCAL',
input_schema: {
type: 'object',
properties: {
keyword: { type: 'string', description: 'Filter notes by title keyword' },
},
'x-zakardo': { kind: 'capability-input', version: '1.0.0' },
},
output_schema: {
type: 'object',
properties: {
notes: {
type: 'array',
description: 'List of notes',
items: {
type: 'object',
properties: {
id: { type: 'string' },
title: { type: 'string' },
body: { type: 'string' },
},
},
},
count: { type: 'number', description: 'Total notes returned' },
},
'x-zakardo': { kind: 'capability-output', version: '1.0.0' },
},
interaction_spec: null,
anchored_view: null,
tags: ['notes', 'read'],
metadata: { author: 'tutorial', created_at: '2026-01-01T00:00:00Z', deprecated: false },
} as CapabilityDefinition;
export const listNotesImpl: CapabilityFn = async (inputs) => {
const keyword = inputs['keyword'] as string | undefined;
let results = [...notes];
if (keyword) {
results = results.filter((n) => n.title.toLowerCase().includes(keyword.toLowerCase()));
}
return { notes: results, count: results.length };
};
// --- Add Note ---
export const addNoteCapability: CapabilityDefinition = {
name: 'notes_add',
version: '1.0.0',
description: 'Add a new note with a title and body.',
effect_class: 'WRITE_INTERNAL',
boundary: 'LOCAL',
input_schema: {
type: 'object',
required: ['title', 'body'],
properties: {
title: { type: 'string', description: 'Note title' },
body: { type: 'string', description: 'Note body content' },
},
'x-zakardo': { kind: 'capability-input', version: '1.0.0' },
},
output_schema: {
type: 'object',
properties: {
id: { type: 'string', description: 'Created note ID' },
title: { type: 'string', description: 'Note title' },
created: { type: 'boolean', description: 'Whether the note was created' },
},
'x-zakardo': { kind: 'capability-output', version: '1.0.0' },
},
interaction_spec: null,
anchored_view: null,
tags: ['notes', 'write'],
metadata: { author: 'tutorial', created_at: '2026-01-01T00:00:00Z', deprecated: false },
} as CapabilityDefinition;
export const addNoteImpl: CapabilityFn = async (inputs) => {
const id = `note_${crypto.randomUUID().slice(0, 8)}`;
const note = {
id,
title: inputs['title'] as string,
body: inputs['body'] as string,
created_at: new Date().toISOString(),
};
notes.push(note);
return { id, title: note.title, created: true };
};

Each capability declares:

  • effect_class — what it does (READ vs WRITE_INTERNAL)
  • boundary — where it runs (LOCAL means within the server process)
  • input_schema / output_schema — typed JSON Schemas with x-zakardo extensions
  • tags — for discovery and filtering

Step 3: Describe Your Application to the Planner

Section titled “Step 3: Describe Your Application to the Planner”

Before starting the server, you need to tell the AI planner what your app does. This is the most important configuration in any Zakardo application. Without it, the planner has no context about your domain and will produce poor or unusable plans.

The application_prompt is injected into every planner LLM call as system context. It should describe:

  • What your app does — the domain and purpose
  • Who the users are — their roles and what they care about
  • Key domain concepts — the entities and relationships
  • Business rules — constraints the planner should respect

You can also add planning_hints — short, targeted rules for specific situations.

Create src/server.ts:

import { Hono } from 'hono';
import { serve } from '@hono/node-server';
import { createZakardoApp, mountStudio, type ZakardoConfig } from '@zakardo/core';
import {
listNotesCapability,
listNotesImpl,
addNoteCapability,
addNoteImpl,
} from './capabilities.js';
const config: ZakardoConfig = {
name: 'my-notes-app',
version: '0.0.1',
llm: {
providers: [{ name: 'mock', type: 'mock' as const, models: ['mock-model'] }],
default_model: 'mock-model',
routing: {},
// Tell the planner what your app does (Layer 2)
application_prompt: `
This is a personal note-taking application.
Users create and search through text notes.
Notes have a title and a body. Notes are never deleted, only archived.
Keep responses concise and helpful.
`,
// Domain-specific hints for the planner (Layer 4)
planning_hints: [
'When a user asks to "find" or "search" notes, use notes_list with a keyword filter.',
'When a user asks to "write" or "create" a note, use notes_add.',
],
},
execution: { timeout_ms: 30_000, step_timeout_ms: 5_000 },
trace: { level: 'full' },
auth: { required: false },
};
async function main() {
const { app: zakardoApp, runtime } = await createZakardoApp({
config,
capabilities: [listNotesCapability, addNoteCapability],
implementations: [
{ name: 'notes_list', version: '1.0.0', fn: listNotesImpl },
{ name: 'notes_add', version: '1.0.0', fn: addNoteImpl },
],
policies: [],
});
const app = new Hono();
app.route('/zakardo', zakardoApp);
mountStudio(app, { basePath: '/studio' });
serve({ fetch: app.fetch, port: 3000 });
console.log('Notes app running at http://localhost:3000');
console.log('API: http://localhost:3000/zakardo/v1/health');
console.log('Studio: http://localhost:3000/studio');
}
main().catch(console.error);

Start the server:

Terminal window
npx tsx src/server.ts

Check the health endpoint:

Terminal window
curl http://localhost:3000/zakardo/v1/health

List registered capabilities:

Terminal window
curl http://localhost:3000/zakardo/v1/capabilities

You should see both notes_list and notes_add in the response.

Use the client SDK or curl to submit an intent:

Terminal window
curl -X POST http://localhost:3000/zakardo/v1/intent \
-H "Content-Type: application/json" \
-d '{"intent": {"expressed": "Show me all my notes"}}'

The planner will classify the intent, generate a plan using notes_list, and return the result.

For a typed experience, use @zakardo/client:

Terminal window
pnpm add @zakardo/client
import { ZakardoClient } from '@zakardo/client';
const client = new ZakardoClient({
baseUrl: 'http://localhost:3000/zakardo/v1',
});
// Submit an intent
const result = await client.intent.submit({
intent: { expressed: 'Add a note titled Meeting Notes with body Discuss Q1 roadmap' },
});
console.log('Response mode:', result.mode);
// List capabilities
const caps = await client.capabilities.list();
console.log(
'Capabilities:',
caps.map((c) => c.name),
);

Open http://localhost:3000/studio in your browser to access Zakardo Studio:

  • Capability Browser — see your registered capabilities with their schemas
  • Intent Playground — submit intents and watch the planner pipeline
  • Trace Viewer — inspect execution traces step by step