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.
Intent Input Modes
Section titled “Intent Input Modes”Zakardo supports three ways for users to express intent:
| Mode | Description | Example |
|---|---|---|
| Natural language | Free-text expressing a goal | ”Show me all VIP contacts” |
| Packaged action | Pre-defined intent with structured parameters | { action: 'contacts_list', params: { tag: 'VIP' } } |
| Structured form | Form-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.
Intent Lifecycle
Section titled “Intent Lifecycle”When an intent is submitted to the runtime, it flows through the following stages:
- Classification — The Planner determines if the intent is actionable, exploratory, or ambiguous
- Goal Extraction — For actionable intents, the Planner extracts a structured goal with parameters
- Capability Scoring — Available capabilities are scored for relevance to the goal
- Plan Generation — The Planner uses backward chaining to assemble a Plan Draft
- Enrichment + Validation — The draft is enriched and validated before execution
Intent Classification
Section titled “Intent Classification”The Planner classifies every intent into one of three categories:
| Classification | Meaning | Planner Response |
|---|---|---|
| Actionable | The intent requires executing capabilities | GENERATE — produces a Plan Draft |
| Exploratory | The intent is a question or informational request | CONVERSE — produces a conversational response |
| Ambiguous | The intent needs clarification before proceeding | CLARIFY — 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?"Multi-Turn Clarification
Section titled “Multi-Turn Clarification”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 clarificationawait client.intent.clarify(intentId, {});// Planner now has enough context to GENERATE a planConversation History
Section titled “Conversation History”For multi-turn interactions, the Planner maintains conversation context. Previous turns inform the current intent classification and plan generation.
Submitting Intents via the API
Section titled “Submitting Intents via the API”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 identifierFurther Reading
Section titled “Further Reading”- Planner API Reference — detailed pipeline stages and configuration
- Plans — what happens after an intent is classified as actionable