Skip to main content
Advanced Planning Mode enables your agents to create and manage structured execution plans, providing transparent task tracking and systematic progress through complex workflows. When enabled, agents must define a comprehensive plan before execution, ensuring organized and accountable task completion by your agents.

​
Overview

Structured Tasks

Break down goals into discrete, trackable tasks

Progress Tracking

Monitor completion status for each plan item

Dynamic Updates

Add, modify, or remove tasks as work progresses

Automatic Retries

System retries until all tasks complete (up to 3 attempts)

​
When to Use

Advanced planning is ideal for:
  • Multi-Step Workflows - Tasks requiring coordinated execution across multiple phases
  • Complex Implementations - Feature development, migrations, or system integrations
  • Audit Requirements - Scenarios requiring documented execution trails

​
Configuration

  1. Open agent settings
  2. Navigate to Agent Configuration
  3. Enable Advanced Planning Mode
  4. Save and deploy

​
How It Works

​
Execution Lifecycle

When deep planning is enabled:
  1. Execution Blocks - Agent execution pauses until a plan is created
  2. Plan Creation - Agent must use xpcreate-agent-plan (a built in xpander tool provided to the agent) to define tasks
  3. Task Execution - Agent works through tasks, marking them complete
  4. Progress Updates - Plan changes stream to UI in real-time via PlanUpdated events
  5. Automatic Retries - If tasks remain incomplete, system retries (up to 3 times)
Agent Start → Create Plan → Execute Tasks → Mark Complete → Verify → Done
                    ↓                                               ↑
                   Block                                      Auto-Retry

​
Plan Structure

Each plan contains a list of tasks: 
{
  "enabled": true,
  "tasks": [
    {
      "id": "uuid-1234",
      "title": "Analyze requirements",
      "completed": false
    },
    {
      "id": "uuid-5678",
      "title": "Design database schema",
      "completed": false
    }
  ]
}

​
Planning Tools

Advanced Planning provides six built-in tools that agents use to manage their execution plans:

​
Create Plan

Tool: xpcreate-agent-plan Creates the initial execution plan. Required before any other operations. 
# Agent creates plan at execution start
{
    "tasks": [
        {"title": "Gather user requirements", "completed": false},
        {"title": "Design database schema", "completed": false},
        {"title": "Implement API endpoints", "completed": false},
        {"title": "Write tests", "completed": false},
        {"title": "Deploy to staging", "completed": false}
    ]
}

​
Get Current Plan

Tool: xpget-agent-plan Retrieves the current execution plan with all task statuses. 
# Agent checks current progress
current_plan = xpget_agent_plan()
# Returns full plan object with completion status

​
Add New Task

Tool: xpadd-new-agent-plan-item Dynamically adds tasks discovered during execution. 
# Agent discovers additional work needed
{
    "title": "Handle edge case in authentication flow",
    "completed": false
}

​
Update Task

Tool: xpupdate-agent-plan-item Modifies task title or completion status. 
# Agent refines task description
{
    "id": "task-uuid",
    "title": "Implement OAuth 2.0 endpoints with PKCE flow",
    "completed": false
}

​
Complete Task

Tool: xpcomplete-agent-plan-item Marks a specific task as done. 
# Agent finishes a task
{
    "id": "task-uuid"
}
# Task updated to completed: true

​
Delete Task

Tool: xpdelete-agent-plan-item Removes tasks that are no longer relevant. 
# Agent removes unnecessary task
{
    "id": "task-uuid"
}

​
Real-Time Updates

The platform UI displays plans with:
  • Progress Indicators - Visual completion badges for each task
  • Real-Time Updates - Live refresh as agents complete tasks
  • Task Details - Full task descriptions and IDs
  • Completion Summary - Overall progress percentage

​
Tracking Execution Plans

The platform provides two ways to view and track execution plans:

​
Chat Interface View

When testing your agent in the chat interface, the execution plan appears directly in the conversation, allowing you to monitor progress in real-time as you interact with your agent.
Planning view in chat interface
This view shows:
  • Current task status with completion indicators
  • Task list with checkmarks for completed items
  • Real-time updates as the agent progresses through the plan

​
Monitoring View

For reviewing past executions, the Workbench monitoring view displays the complete execution plan with full task history. This is useful for auditing, debugging, or reviewing how the agent approached a complex task after completion.
Planning view in monitoring dashboard
This view provides:
  • Complete plan overview with all tasks
  • Final completion status for each task
  • Historical context for understanding agent execution flow
  • Detailed task breakdown for post-execution analysis

​
Retry Logic

The system automatically retries executions with incomplete plans:
ConditionBehavior
All tasks completeExecution succeeds
Tasks remain incompleteRetry execution (max 3 attempts)
Max retries reachedExecution fails with incomplete tasks
Execution timeoutCurrent attempt ends, retry if attempts remain
# Automatic retry flow
Attempt 1: 3/5 tasks complete → Retry
Attempt 2: 4/5 tasks complete → Retry
Attempt 3: 5/5 tasks complete → Success

​
Sub-Agent Planning

When agents create sub-tasks, the sub-agent can inherit deep planning settings. Each sub-agent maintains its own independent plan, allowing for nested planning structures in complex workflows.

​
Comparison: Reasoning vs Planning

FeatureAdvanced ReasoningAdvanced Planning
PurposeDeeper thinking about problemsStructured task execution
OutputThought process & conclusionsTask list & progress
Best ForAnalysis, decisions, complex problemsMulti-step workflows, implementations
VisibilityReasoning steps in logsTask checklist in UI
CompletionSingle responseMultiple tracked tasks
Use Together✓ Combine for complex projects requiring both deep analysis and structured execution

Advanced Reasoning

Extended thinking for complex problems

Observability

View plans in activity logs

Agent Memory

Persistent state across executions

Tool Calling

Custom tool integration