Planner Mode

Planner mode gives an agent systematic planning capabilities. When the agent receives a complex or multi-step task, it will create a structured plan, track each step's progress, and verify completion before finishing.

This mode is ideal for tasks that require methodical execution: code generation with multiple files, research with several phases, or any workflow where step-by-step transparency matters.

See the Planner Mode Example for a complete, runnable implementation.

Enabling Planner Mode

import { Agent, TAgentMode } from '@smythos/sdk';

const agent = new Agent({
    name: 'Code Assistant',
    behavior: 'You are a senior developer who writes clean, well-tested code.',
    model: 'gpt-4o',
    mode: TAgentMode.PLANNER,
});
Copy

How It Works

When a user sends a complex request, the agent will:

1. Analyze the request and reason about the approach (in <thinking> tags)
2. Plan the steps needed (in <planning> tags)
3. Register the plan as tracked tasks via the internal _sre_Plan_Tasks skill
4. Execute each step sequentially, updating task status along the way
5. Verify that all tasks are completed before finishing

The agent communicates its reasoning transparently using <thinking> tags, and uses <planning> tags to outline its approach. These tags allow the LLM to separate internal reasoning from user-facing output.

Events

Planner mode emits events on the agent object so you can build UIs that reflect the agent's progress in real time.

TasksAdded

Fired when the agent creates a new plan.

agent.on('TasksAdded', (tasksList, allTasks) => {
    // tasksList: the newly added tasks
    // allTasks: all tasks in the planner (cumulative)
    for (const [id, task] of Object.entries(allTasks)) {
        console.log(`${task.status}: ${task.summary || task.description}`);
    }
});
Copy

Payload:

Parameter	Type	Description
tasksList	object	The tasks that were just added
allTasks	object	All tasks in the planner

Each task object has the shape: { description: string, summary: string, status: 'planned' | 'ongoing' | 'completed' }

SubTasksAdded

Fired when the agent breaks a task into smaller subtasks.

agent.on('SubTasksAdded', (parentTaskId, subTasksList, allTasks) => {
    console.log(`Task ${parentTaskId} broken into subtasks:`, subTasksList);
});
Copy

Payload:

Parameter	Type	Description
parentTaskId	string	The ID of the parent task
subTasksList	object	The subtasks that were added
allTasks	object	All tasks in the planner

TasksUpdated

Fired when a task or subtask changes status.

agent.on('TasksUpdated', (taskId, status, allTasks) => {
    const icon = status === 'completed' ? '✅' : status === 'ongoing' ? '⏳' : '📝';
    console.log(`${icon} Task ${taskId}: ${status}`);
});
Copy

Payload:

Parameter	Type	Description
taskId	string	The task ID (for subtasks: "parentId.subtaskId")
status	string	New status: 'planned', 'ongoing', or 'completed'
allTasks	object	All tasks in the planner

TasksCompleted

Fired when the agent verifies that all tasks and subtasks are completed.

agent.on('TasksCompleted', (allTasks) => {
    console.log('All tasks completed!', allTasks);
});
Copy

TasksCleared

Fired when the agent clears the planner to start a new plan.

agent.on('TasksCleared', (allTasks) => {
    console.log('Planner cleared');
});
Copy

Events Summary

Event	Payload	When
TasksAdded	(tasksList, allTasks)	Agent creates a new plan
SubTasksAdded	(parentTaskId, subTasksList, allTasks)	Agent decomposes a task into subtasks
TasksUpdated	(taskId, status, allTasks)	A task or subtask changes status
TasksCompleted	(allTasks)	All tasks verified as completed
TasksCleared	(allTasks)	Planner is reset for a new plan

Full Example with Chat

import { Agent, TAgentMode, TLLMEvent } from '@smythos/sdk';
import * as readline from 'readline';

const agent = new Agent({
    name: 'Code Assistant',
    behavior: 'You are a senior developer.',
    model: 'gpt-4o',
    mode: TAgentMode.PLANNER,
});

// Track planning events
agent.on('TasksAdded', (_, tasks) => {
    console.log('\n📋 Plan:');
    for (const [id, task] of Object.entries(tasks) as any) {
        console.log(`   📝 ${task.summary || task.description}`);
    }
});

agent.on('TasksUpdated', (taskId, status) => {
    const icon = status === 'completed' ? '✅' : '⏳';
    console.log(`   ${icon} ${taskId}: ${status}`);
});

agent.on('TasksCompleted', () => {
    console.log('   🎉 All tasks completed!');
});

// Start a chat session
const chat = agent.chat({ persist: false });

const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    prompt: 'You: ',
});

chat.on(TLLMEvent.Content, (content) => {
    process.stdout.write(content);
});

chat.on(TLLMEvent.End, () => {
    console.log('\n');
    rl.prompt();
});

rl.on('line', (input) => {
    chat.prompt(input).stream();
});

rl.prompt();
Copy

Combining with Worker Mode

Planner mode pairs naturally with Worker mode. The agent plans the work and dispatches complex subtasks to background workers:

const agent = new Agent({
    name: 'Research Assistant',
    model: 'gpt-4o',
    mode: [TAgentMode.PLANNER, TAgentMode.WORKER],
});
Copy

See the Combined Example for a full implementation.

Next Steps

• Worker Mode - Background task delegation
• Agent Modes Overview - All available modes
• Chat - Maintaining conversations with context