Skip to content

Intents

An intent is the starting point of every Zakardo interaction. It expresses what the user wants to accomplish, and the Planner translates it into an executable plan.

Zakardo supports three ways for users to express intent:

ModeDescriptionExample
Natural languageFree-text expressing a goal”Show me all VIP contacts”
Packaged actionPre-defined intent with structured parameters{ action: 'contacts_list', params: { tag: 'VIP' } }
Structured formForm-based input from an anchored view{ capability: 'contacts_create', inputs: { name: 'Alice', email: '[email protected]' } }

Natural language is the primary mode. The Planner interprets the text and generates a plan. Packaged actions and structured forms bypass some reasoning steps since the user’s intent is already partially structured.

When an intent is submitted to the runtime, it flows through the following stages:

  1. Classification — The Planner determines if the intent is actionable, exploratory, or ambiguous
  2. Goal Extraction — For actionable intents, the Planner extracts a structured goal with parameters
  3. Capability Scoring — Available capabilities are scored for relevance to the goal
  4. Plan Generation — The Planner uses backward chaining to assemble a Plan Draft
  5. Enrichment + Validation — The draft is enriched and validated before execution

The Planner classifies every intent into one of three categories:

ClassificationMeaningPlanner Response
ActionableThe intent requires executing capabilitiesGENERATE — produces a Plan Draft
ExploratoryThe intent is a question or informational requestCONVERSE — produces a conversational response
AmbiguousThe intent needs clarification before proceedingCLARIFY — produces a structured question
// Actionable: "Delete the contact named John"
// → GENERATE: Plan with contacts_delete capability
// Exploratory: "What capabilities do I have?"
// → CONVERSE: Lists available capabilities
// Ambiguous: "Update the deal"
// → CLARIFY: "Which deal would you like to update?"

When the Planner returns a CLARIFY response, it includes a structured question with options. The user responds, and the Planner processes the clarification to generate a plan:

// Initial intent: "Send an email"
// Planner: CLARIFY — "Who should receive the email?"
// options: [{ label: "Select from contacts" }, { label: "Enter email address" }]
// User responds with clarification
await client.intent.clarify(intentId, {
response: 'Send it to [email protected] with subject Meeting Follow-up',
});
// Planner now has enough context to GENERATE a plan

For multi-turn interactions, the Planner maintains conversation context. Previous turns inform the current intent classification and plan generation.

import { ZakardoClient } from '@zakardo/client';
const client = new ZakardoClient({ baseUrl: 'http://localhost:3000/zakardo/v1' });
const response = await client.intent.submit({
intent: { expressed: 'Show me all contacts tagged VIP' },
});
console.log(response.mode); // 'GENERATE' | 'CLARIFY' | 'CONVERSE'
console.log(response.intent_id); // Unique intent identifier
  • Planner API Reference — detailed pipeline stages and configuration
  • Plans — what happens after an intent is classified as actionable