Planning

PlanNotebook provides planning capabilities for agents, helping them break down complex tasks into structured subtasks and execute them step by step.

Enable Planning

Option 1: Use Default Configuration (Recommended)

ReActAgent agent = ReActAgent.builder()
        .name("Assistant")
        .model(model)
        .toolkit(toolkit)
        .enablePlan()  // Enable planning
        .build();

Option 2: Custom Configuration

PlanNotebook planNotebook = PlanNotebook.builder()
        .maxSubtasks(10)  // Limit number of subtasks
        .build();

ReActAgent agent = ReActAgent.builder()
        .name("Assistant")
        .model(model)
        .toolkit(toolkit)
        .planNotebook(planNotebook)
        .build();

Usage Example

// Create an agent with planning support
ReActAgent agent = ReActAgent.builder()
        .name("PlanAgent")
        .sysPrompt("You are a systematic assistant that breaks down complex tasks into plans.")
        .model(model)
        .toolkit(toolkit)
        .enablePlan()
        .build();

// Assign a complex task to the agent
Msg task = Msg.builder()
        .role(MsgRole.USER)
        .content(List.of(TextBlock.builder()
                .text("Build a simple calculator web app with HTML, CSS and JavaScript.")
                .build()))
        .build();

// Agent will automatically create a plan and execute it step by step
Msg response = agent.call(task).block();

Planning Tools

When planning is enabled, the agent automatically gets access to these tools:

Tool Name	Purpose
`create_plan`	Create a new plan
`revise_current_plan`	Revise the current plan
`update_subtask_state`	Update subtask state (todo/in_progress/abandoned)
`finish_subtask`	Mark subtask as done
`view_subtasks`	View subtask details
`finish_plan`	Complete or abandon the entire plan
`view_historical_plans`	View historical plans
`recover_historical_plan`	Recover a historical plan

The agent will call these tools automatically based on the task - no manual intervention needed.

Workflow

Create Plan: Agent analyzes the task and calls create_plan to create a plan with multiple subtasks
Execute Subtasks: Execute each subtask in sequence
Update Status: Call finish_subtask to update status after completing each subtask
Complete Plan: Call finish_plan after all subtasks are done

During execution, the system automatically injects plan hints before each reasoning step to guide the agent.

Complete Example

See agentscope-examples/documentation/quickstart/src/main/java/io/agentscope/examples/quickstart/PlanNotebookExample.java

Configuration Options

User Confirmation (needUserConfirm)

Controls whether the agent needs to wait for user confirmation before starting execution after creating a plan. Default Value: true (user confirmation required) When enabled, the agent will display the plan content and ask the user whether to proceed (e.g., “Should I proceed with this plan?”) after creating a plan. It will only start executing subtasks after the user explicitly confirms (e.g., replying “yes”, “go ahead”). If the user’s message already implies execution intent (e.g., “execute the plan”), confirmation is skipped and execution begins directly. When disabled, the agent will immediately start executing after creating the plan, without waiting for user confirmation.

// Require user confirmation (default behavior)
PlanNotebook planNotebook = PlanNotebook.builder()
        .needUserConfirm(true)
        .build();

// No confirmation needed, execute immediately after creating plan
PlanNotebook planNotebook = PlanNotebook.builder()
        .needUserConfirm(false)
        .build();

Note: When subtasks are already in execution (status is in_progress), confirmation rule hints will not be injected regardless of the needUserConfirm setting.

Limit Subtask Count

PlanNotebook planNotebook = PlanNotebook.builder()
        .maxSubtasks(10)  // Maximum 10 subtasks
        .build();

Custom Storage

PlanNotebook planNotebook = PlanNotebook.builder()
        .storage(new InMemoryPlanStorage())  // Default in-memory storage
        .build();

Custom Hint Generation

PlanNotebook planNotebook = PlanNotebook.builder()
        .planToHint(new DefaultPlanToHint())  // Custom plan-to-hint strategy
        .build();

Quick Start

Features

Multi Agent

Harness

Enable Planning

Option 1: Use Default Configuration (Recommended)

Option 2: Custom Configuration

Usage Example

Planning Tools

Workflow

Complete Example

Configuration Options

User Confirmation (needUserConfirm)

Limit Subtask Count

Custom Storage

Custom Hint Generation

​Enable Planning

​Option 1: Use Default Configuration (Recommended)

​Option 2: Custom Configuration

​Usage Example

​Planning Tools

​Workflow

​Complete Example

​Configuration Options

​User Confirmation (needUserConfirm)

​Limit Subtask Count

​Custom Storage

​Custom Hint Generation

Enable Planning

Option 1: Use Default Configuration (Recommended)

Option 2: Custom Configuration

Usage Example

Planning Tools

Workflow

Complete Example

Configuration Options

User Confirmation (needUserConfirm)

Limit Subtask Count

Custom Storage

Custom Hint Generation