Skip to main content

Overview

The Planner engine creates a structured plan with defined subtasks before execution. The agent first decomposes a complex goal into manageable steps, then executes each step systematically. This approach is particularly effective for:
  • Complex multi-stage projects
  • Tasks requiring clear sequencing
  • Scenarios where planning upfront improves efficiency
  • Projects with multiple dependencies

How It Works

  1. Planning Phase: Agent analyzes the goal and creates a structured plan with subtasks
  2. Execution Phase: Agent works through each subtask in order
  3. Tracking: Progress is tracked against the original plan
  4. Adaptation: Can revise the plan if needed during execution

Complete Example

This example shows a Planner agent that researches frameworks and writes a report:
import "dotenv/config"

import {  createAgent, AgentInstance, defineTool, ReasoningStep  } from '@agentlib/core'
import { openai } from '@agentlib/openai'
import { PlannerEngine } from '@agentlib/reasoning'

const model = openai({ apiKey: process.env['OPENAI_API_KEY']!, model: process.env['OPENAI_MODEL']!, baseURL: process.env['OPENAI_BASE_URL']! })

const searchTool = defineTool({
    schema: {
        name: 'search',
        description: 'Search the web for information',
        parameters: {
            type: 'object',
            properties: { query: { type: 'string' } },
            required: ['query'],
        },
    },
    async execute({ query }) {
        return { results: [`Result for: ${query}`] }
    },
})

const writeFileTool = defineTool({
    schema: {
        name: 'write_file',
        description: 'Write content to a file',
        parameters: {
            type: 'object',
            properties: {
                path: { type: 'string' },
                content: { type: 'string' },
            },
            required: ['path', 'content'],
        },
    },
    async execute({ path }) {
        console.log(`Writing to ${path}...`)
        return { success: true }
    },
})

async function main() {
    const agent = createAgent({ name: 'planner-agent' })
        .provider(model)
        .tool(searchTool)
        .tool(writeFileTool)
        .reasoning(new PlannerEngine({ maxExecutionSteps: 15 }))

    agent.on('step:reasoning', (step: ReasoningStep) => {
        if (step.type === 'plan') {
            console.log('📋 Plan:')
            step.tasks.forEach((t) => console.log(`  [${t.id}] ${t.description}`))
        }
        if (step.type === 'thought') {
            console.log('▶', step.content)
        }
    })

    const result = await agent.run(
        'Research the top 3 JavaScript frameworks in 2025 and write a comparison report to /tmp/frameworks.md'
    )
    console.log('Final output:', result.output)
}

main().catch(console.error)

Configuration Options

  • maxExecutionSteps: Maximum number of execution steps allowed (default: 20)

Monitoring the Plan

Listen to planning and execution events:
agent.on('step:reasoning', (step: ReasoningStep) => {
    if (step.type === 'plan') {
        console.log('📋 Plan created:')
        step.tasks.forEach((task) => {
            console.log(`  [${task.id}] ${task.description}`)
        })
    }
    if (step.type === 'thought') {
        console.log('Executing:', step.content)
    }
})

Example Output

For the framework research task:
📋 Plan:
  [1] Search for top JavaScript frameworks in 2025
  [2] Research React features and popularity
  [3] Research Vue.js features and popularity
  [4] Research Svelte features and popularity
  [5] Compile comparison report
  [6] Write report to /tmp/frameworks.md

▶ Executing task 1: Searching for top frameworks...
▶ Executing task 2: Researching React...
...

When to Use Planner

Use the Planner engine when:
  • Tasks are complex and benefit from upfront planning
  • Multiple subtasks have clear dependencies
  • You need visibility into the planned approach before execution
  • The agent should work methodically through a structured workflow
  • You want to optimize task ordering for efficiency

Build docs developers (and LLMs) love