Developers

Step config format

📋 Overview

The step_config.json file stores step-specific agent configurations (LLM models, tool selections, execution settings) separate from the main plan structure. This separation allows plan.json to focus on workflow structure while step_config.json manages execution details.

Key Benefits:

• Separation of concerns: Plan structure vs execution configuration
• Consistent format: Object format with steps array (both frontend and backend)
• Backward compatibility: Legacy array format supported during migration

📁 Key Files & Locations

📂 File Locations

The step_config.json file can exist in two locations (with priority):

1. Run-specific config (highest priority): {workspacePath}/runs/{runFolder}/planning/step_config.json

   • Used when a specific run folder is selected
   • Allows different configs for different execution runs

2. Default config (fallback): {workspacePath}/planning/step_config.json

   • Used when no run folder is selected or run-specific config doesn't exist
   • Shared across all runs

Source: view on GitHub

The backend automatically checks run-specific config first, then falls back to default config.

🔄 Format Structure

Object Format (Only Supported Format)

Both frontend and backend read and write only the object format with steps field:

{
  "steps": [
    {
      "id": "step-id-here",
      "title": "Optional step title",
      "agent_configs": {
        "selected_servers": ["server1", "server2"],
        "selected_tools": ["server1:tool1", "server1:tool2", "server2:*"],
        "enabled_custom_tools": ["workspace_browser:agent_browser"],
        "execution_llm": {
          "provider": "openai",
          "model_id": "gpt-4o"
        },
        "use_code_execution_mode": true,
        "disable_validation": false,
        "llm_validation_mode": "skip",
        "learnings_access": "read-write",
        "learning_objective": "Capture target-system selectors, auth flow quirks, and session-expiry signals",
        "enable_context_offloading": true,
        "enable_prerequisite_detection": true,
        "prerequisite_rules": [
          {
            "depends_on_step": "step-0",
            "description": "If login session is missing or expired, go back to step 0"
          }
        ]
      }
    }
  ]
}

Field Structure

🔄 Implementation Details

Frontend Implementation

File: usePlanData.ts

Read:

function normalizeStepConfigFile(rawContent: unknown): StepConfig[] {
  // Handles object format: { "steps": [...] }
  if (rawContent && typeof rawContent === 'object' && !Array.isArray(rawContent)) {
    const obj = rawContent as Record<string, unknown>
    if ('steps' in obj && Array.isArray(obj.steps)) {
      return obj.steps as StepConfig[]
    }
  }
  // Legacy array format support (with warning)
  if (Array.isArray(rawContent)) {
    return rawContent as StepConfig[]
  }
  return []
}

Write:

const content = JSON.stringify({ steps: stepConfigs }, null, 2)
await agentApi.updatePlannerFile(stepConfigPath, content, `Updated step config for step ${stepId}`)

Backend Implementation

Source: view on GitHub

Read:

type StepConfigFile struct {
    Steps []StepConfig `json:"steps"`
}

func ParseStepConfigContent(content string) ([]StepConfig, error) {
    var file StepConfigFile
    if err := json.Unmarshal([]byte(content), &file); err != nil {
        return nil, err
    }
    return file.Steps, nil
}

Write:

file := StepConfigFile{Steps: configs}
content, err := json.MarshalIndent(file, "", "  ")

⚙️ Configuration Fields

Source: view on GitHub — AgentConfigs struct

LLM Configuration

Turn Limits

Per-step and workflow-default turn-limit properties are retired. Legacy execution_max_turns values are ignored on load and omitted from typed config saves; execution uses the shared runtime limit.

Tool & Server Configuration

Validation Configuration

Learning Configuration

Execution Mode Configuration

Prerequisite Detection Configuration

🛠️ Common Issues & Solutions

🔍 For LLMs: Quick Reference

Constraints:

• ✅ Allowed: Object format { "steps": [...] }
• ✅ Allowed: Empty steps array []
• ✅ Allowed: Missing agent_configs (uses defaults)
• ❌ Forbidden: Root-level array format (legacy, deprecated)
• ❌ Forbidden: Missing id field in step config

Example:

{
  "steps": [
    {
      "id": "step-1",
      "agent_configs": {
        "selected_servers": ["aws"],
        "execution_llm": {
          "provider": "openai",
          "model_id": "gpt-4o"
        }
      }
    }
  ]
}

File Operations:

• Read: Always parse object format, extract steps array
• Write: Always write object format: JSON.stringify({ steps: stepConfigs }, null, 2)
• Update: Find step by id, update agent_configs, save entire file
• Config Priority: Run-specific config (runs/{runFolder}/planning/step_config.json) takes precedence over default config (planning/step_config.json)

Field Notes:

• All boolean fields use nil (undefined) to mean "use default/preset value"
• enabled_custom_tools uses unified format: "category:tool" or "category:*". Current categories include workspace_advanced, workspace_tools, workspace_browser, and human_tools; use execute_shell_command / diff_patch_workspace_file for file access instead of legacy basic workspace tool names.
• learning_detail_level accepts "exact", "general", or "none" (default: "exact")

📖 Related Documentation

• Workflow Docs - Overall workflow architecture
• Learn Code and Code Execution Modes - Scripted execution configuration and flow
• Step Config Matching - Type definitions and matching logic