Skip to content

Capabilities

A capability is a typed, versioned, atomic unit of execution with declared inputs, outputs, effect class, and boundary. Capabilities are the instruction set of Zakardo — the building blocks that plans are composed from.

Every capability is a JSON object that declares everything the runtime needs to know:

import type { CapabilityDefinition } from '@zakardo/core';
const listContacts: CapabilityDefinition = {
name: 'contacts_list', // Unique identifier
version: '1.0.0', // Semver version
description: 'List all contacts, optionally filtered by tag.',
effect_class: 'READ', // What it does
boundary: 'LOCAL', // Where it runs
input_schema: { // JSON Schema for inputs
type: 'object',
properties: {
tag: { type: 'string', description: 'Filter by tag' },
},
'x-zakardo': { kind: 'capability-input', version: '1.0.0' },
},
output_schema: { // JSON Schema for outputs
type: 'object',
properties: {
contacts: { type: 'array', items: { type: 'object' }, description: 'Contact list' },
total: { type: 'number', description: 'Total count' },
},
'x-zakardo': { kind: 'capability-output', version: '1.0.0' },
},
interaction_spec: null, // Optional: mid-plan user interaction
anchored_view: null, // Optional: persistent UI view
tags: ['contacts', 'read'], // Discovery tags
metadata: {
author: 'my-app',
created_at: '2026-01-01T00:00:00Z',
deprecated: false,
},
};

Every capability declares its effect class — what side effects it produces:

Effect ClassMeaningExamples
READOnly reads data, no mutationsList contacts, get analytics
WRITE_INTERNALMutates data within the applicationCreate contact, update deal stage
WRITE_EXTERNALProduces side effects outside the systemSend email, call external API
DESTRUCTIVEIrreversible operationsDelete contact, purge data

Effect classes drive governance: DESTRUCTIVE capabilities trigger approval gates by default, and WRITE_EXTERNAL capabilities have their side effects deferred until all plan steps succeed.

See Effect Classes for the full governance matrix.

The boundary declares where the capability executes:

BoundaryMeaning
LOCALRuns within the server process
REMOTECalls an external service (HTTP, gRPC)
USER_ENVExecutes in the user’s environment (browser, device)

The definition declares what a capability does. The implementation is the function that does it:

import type { CapabilityFn } from '@zakardo/core';
const listContactsImpl: CapabilityFn = async (inputs) => {
const tag = inputs['tag'] as string | undefined;
const contacts = await db.contacts.findMany({
where: tag ? { tags: { has: tag } } : undefined,
});
return { contacts, total: contacts.length };
};

Implementations are registered separately from definitions, allowing different implementations per environment (production vs test vs simulation).

Capabilities can declare mid-plan interaction points — moments where the capability needs user input to proceed:

Interaction TypeUse Case
SELECTUser picks one option from a list
COMPAREUser compares options side by side
REVIEWUser reviews and approves data before it is used
INPUTUser provides free-form input
CONFIRMUser confirms a specific action

The runtime pauses execution at interaction points, sends an A2UI message to the frontend for rendering, and resumes when the user responds.

Capabilities follow a three-tier design pattern:

TierDescriptionExample
AtomicSingle operation, immediate resultcontacts_create — create one contact
BatchMultiple operations in one callcontacts_import — import 100 contacts
Async JobLong-running operation with progressreport_generate — generate monthly report

When a capability is blocked by policy (e.g., a user lacks permission to delete), the Planner uses the Request Pattern — instead of including the blocked capability, it includes a request_* capability that submits a request for approval:

User: "Delete all inactive contacts"
→ Policy blocks contacts_delete for this user
→ Planner generates: contacts_delete_request (WRITE_INTERNAL)
→ An admin later approves the request

This ensures plans always succeed — the user gets a valid plan, just with a different path to the goal.

Capabilities are registered with the runtime during server setup:

const { app, runtime } = await createZakardoApp({
config,
capabilities: [listContacts, createContact],
implementations: [
{ name: 'contacts_list', version: '1.0.0', fn: listContactsImpl },
{ name: 'contacts_create', version: '1.0.0', fn: createContactImpl },
],
policies: [],
});