# Interactive Workflow Builder This doc explains how the interactive workflow builder works now. This is the chat-driven builder experience used from the workflow canvas. Internally it is the `workflow_phase` path with `phase_id = workflow-builder`. ## What It Is The interactive builder is not the same thing as normal workflow execution. - normal execution uses `agent_mode = workflow` - builder chat uses `agent_mode = workflow_phase` - the builder gets a phase-specific system prompt, a restricted tool set, and builder-specific run-folder behavior The main code paths are: - [interactive_workshop_manager.go](../../agent_go/pkg/orchestrator/agents/workflow/step_based_workflow/interactive_workshop_manager.go) - [server.go](../../agent_go/cmd/server/server.go) - [chatSubmitHelpers.ts](../../frontend/src/utils/chatSubmitHelpers.ts) ## Request Shape From the frontend, builder chat is sent as: - `agent_mode = workflow_phase` - `phase_id = workflow-builder` - `preset_query_id = ` The server then: - resolves the workflow manifest - loads phase LLM settings from the manifest when available - converts the request onto the standard chat agent path - overrides the system prompt for the builder phase - registers builder/workshop tools - applies a per-turn tool allow list based on workshop mode This is handled in [server.go](../../agent_go/cmd/server/server.go). ## Core Mental Model The interactive builder is a persistent chat session that can: - inspect the current workflow plan - modify plan structure - modify step configuration - manage groups, workflow config, schedules, and related artifacts - run single steps in the background - run the full workflow in the background in the appropriate modes - inspect run results and logs It is a design-and-operations surface, not just a prompt editor. ## Workshop Modes The builder has multiple workshop modes. Current backend modes: - `builder` - `optimizer` - `run` - `debugger` - `eval` - `output` The most important ones for normal workflow building are: ### `builder` Use this for designing and testing the workflow. Allowed behavior: - add, update, and delete plan steps - update workflow config, variables, groups, schedules - run individual steps - inspect executions - patch scripts and files ### `optimizer` Use this after the basic workflow exists and needs hardening against run/eval/metric evidence. Adds: - `harden_workflow` - `debug_step` - `run_full_workflow` - evaluation helpers - learning and step-hardening workflows ### `run` Use this when the workflow is already built and the user mainly wants operational execution, Slack/WhatsApp answers, or result inspection. Allowed behavior is runtime-focused: - answer directly from workflow state, KB, learnings, db, and latest run artifacts - run normal steps - run orphan utility steps - run the full workflow - inspect executions It is intentionally more operational and less structural. ## Mode Detection If the frontend does not explicitly force a workshop mode, the backend defaults to Builder. Current rule: - default -> `builder` - `optimizer`, `run`, and reporting mode are explicit frontend/user choices or bot-route settings This logic lives in [interactive_workshop_manager.go](../../agent_go/pkg/orchestrator/agents/workflow/step_based_workflow/interactive_workshop_manager.go). Frontend override still wins when provided. ## Tool Gating The builder does not expose all tools all the time. Current behavior: - the server registers a broad set of workshop-capable tools - then applies a workshop-mode allow list - the allow list is recomputed based on the current workshop mode This is how the product enforces boundaries like: - builder can modify the plan - run mode can execute user-facing work, normal steps, orphan utility steps, and full workflows - run mode can read KB/learnings/db/run artifacts, but cannot freely redesign the workflow - debugger is read-heavy The tool allow-list logic is in [interactive_workshop_manager.go](../../agent_go/pkg/orchestrator/agents/workflow/step_based_workflow/interactive_workshop_manager.go). ## Main Builder Tools The interactive builder commonly uses: - `execute_step` - `query_step` - `stop_step` - `stop_all_executions` - `list_executions` - `run_in_background` - `update_step_config` - plan modification tools such as `add_*`, `update_*`, `delete_*` - `update_workflow_config` - `update_variable`, `add_group`, `update_group`, `delete_group` - schedule tools Depending on mode, it may also expose: - `run_saved_main_py` - `debug_step` - `run_full_workflow` - `run_full_evaluation` - `run_full_report` - `harden_workflow` ## Step Execution From Builder The builder can execute steps directly from chat. Key behavior: - `execute_step(...)` runs in background and returns an execution ID - `query_step(...)` is used to inspect progress and live tool calls - `run_in_background(...)` can spawn a side task with the same workspace access In builder mode: - `iteration` is effectively pinned to `iteration-0` - any incoming builder run-folder selection is normalized to `iteration-0` or `iteration-0/` - every execution re-reads the latest plan and config state This means builder testing always operates against the current mutable run, not an archived iteration. ## Full Workflow Runs From Builder In `optimizer` and `run` modes, the workshop agent can execute the entire workflow via `run_full_workflow(...)`. That is still a background workflow execution, not a special toy mode. Important behavior: - it runs the real workflow controller path - it can require `human_inputs` if the workflow has `human_input` steps - it uses the current workflow plan and config from the workspace ## Run Folder Behavior Interactive builder mode is tightly coupled to `iteration-0`. Current rule: - builder mode normalizes run-folder selection to `iteration-0` - if a group path is selected, it becomes `iteration-0/` This is why the builder always feels attached to the latest mutable run. For the broader run-folder model, see [iteration_run_folder_architecture.md](./iteration_run_folder_architecture.md). ## Session Behavior The builder uses a persistent per-session workshop chat session. Current behavior: - the server reuses the workshop session for the same chat session when possible - refreshed manifest settings can be pushed back into the session - background step executions are tracked so the frontend can keep polling and showing status - stop-state checks are wired to avoid orphaned background processes This is one reason builder chat behaves more like an operator console than a plain LLM chat. ## Files And Persistence The interactive builder writes and reads several kinds of state: ### Plan and config state - `planning/plan.json` - `planning/step_config.json` - `workflow.json` - variables/group data ### Builder chat artifacts - `builder/conversation/YYYY-MM-DD/session-{sessionId}-conversation.json` ### Builder phase costs - `costs/phase/token_usage.json` - `costs/phase/daily/YYYY-MM-DD.json` ### Execution artifacts from tested steps - `runs/iteration-0/...` So the builder has both: - phase-level chat state and costs - execution-level run artifacts when it tests or runs workflow steps ## Relationship To Other Modes The same underlying workshop infrastructure also supports adjacent specialized phases: - `eval` - `output` - `debugger` But the primary workflow-builder experience is still `workflow-builder` plus the builder/optimizer/run workshop modes. ## Practical Summary Use this mental model: - interactive builder = `workflow_phase` chat for workflow design and operation - it is sessionful, tool-driven, and workspace-backed - it auto-detects or accepts a workshop mode - tool access changes by mode - single-step testing happens through workshop execution tools - full runs are available in the more operational modes - builder run-folder context is centered on `iteration-0` ## Related Docs - [iteration_run_folder_architecture.md](./iteration_run_folder_architecture.md) - [cost_and_log_measurement.md](./cost_and_log_measurement.md) - [workflow_shell_working_directory.md](./workflow_shell_working_directory.md) - [workflow_manifest_architecture.md](./workflow_manifest_architecture.md)