Workflow Scripts
Create, run, inspect, and repair durable TypeScript programs that coordinate repeatable work.
#When to use a Workflow Script
Many automations combine predictable work with a smaller amount of judgment. A weekly sales report, for example, may need to collect calls, filter and organize records, identify important themes, and generate a finished report.
You can describe the entire process as step-by-step Skill instructions. As those instructions grow, however, they become difficult for an agent to follow consistently and burn tokens every time the process runs. Writing and maintaining enough instructions for a complex task can also take significant effort.
Once the process and its rules are understood, move the predictable work into a Workflow Script. The script controls the repeatable process and delegates only the steps that require judgment to an agent. For a weekly report, it can query permitted Connections, prepare the data, ask an agent to identify themes and write a summary, then validate, format, and save the result.
Start with Skill instructions while you are still discovering the process. Convert the stable steps into a Workflow Script after the Skill works and you can clearly separate deterministic operations from reasoning.
- The process has known, repeatable rules.
- Skill instructions are becoming long, expensive, or fragile.
- The agent produces inconsistent results from the same instructions.
- Much of the work is querying, filtering, transforming, or formatting data.
- Only specific steps require judgment or language-model reasoning.
- The task runs often enough that speed, cost, and reliability matter.
- The execution needs validated inputs, visible steps, recoverable failures, or structured outputs.
#Ask your agent to create a Workflow Script
Make the BotDojo Core Skills collection available to the workspace. Its botdojo-core-workflows skill teaches the agent how to author, run, inspect, and repair Workflow Scripts.
Give the agent the existing Skill or a representative description of the working process. Ask it to identify which steps are deterministic and which require agent reasoning before it writes code.
- 01
Prove the process first
Complete a representative version in the workspace so the expected input, rules, result, Connections, and quality checks are clear.
- 02
Ask for the Workflow Script
Tell the agent to use the botdojo-core-workflows skill, keep deterministic orchestration in code, and call an agent only where reasoning adds value.
- 03
Set the execution boundary
Name the permitted Connections, expected artifacts, validation rules, approval points, and any limits the script must respect.
- 04
Require a real verification run
Have the agent start the Workflow Run with representative input, wait for it to finish, inspect the result and at least one artifact, and repair any failure.
#Example: prepare an opportunity brief
This example turns notes for the fictional Northstar Paper Co. opportunity into a small account brief. The input includes the company, sales stage, and notes. The script normalizes that input, drafts a predictable brief, saves it as a run artifact, records progress, and returns a structured result.
Save reusable source under the workspace’s workflows folder with a .workflow.ts suffix. The visible source remains available beside the run so a user or agent can inspect and repair it.
- 01
Normalize opportunity
Trim and validate the company, stage, and notes supplied to the run.
- 02
Draft account brief
Create the summary, risks, and next action as a repeatable structured result.
- 03
Save brief
Write the JSON artifact, read it back for verification, and record the saved path.
#Understand the Workflow Script contract
| Export | What it controls |
|---|---|
| inputSchema | The JSON Schema for accepted run input. A run does not start when required input is missing or invalid. |
| outputSchema | The JSON Schema for the final result. Keep it focused on the fields a user or later step needs. |
| workflow(ctx) | The asynchronous entry point. It reads ctx.input, records durable work, and returns the final structured result. |
| resultCard(ctx) or a TSX UI | Optional presentation for a completed result or a richer live status view. The workflow still owns the execution and result. |
#What a Workflow Script can do
The ctx object is the script’s runtime interface. Its capabilities stay inside the Workflow Run and the permissions of the workspace agent that started it.
ctx.tool does not bypass Connection access. It can call only the Model Context Protocol (MCP) tools available to the runner, so the same Connection security boundary still applies.
| Runtime helper | Use it for |
|---|---|
| ctx.input | Read the input that passed inputSchema validation. |
| ctx.step | Create a durable named step whose result can be inspected and reused during recovery. Use stable keys and friendly labels. |
| ctx.storage | Read, write, and check files that belong to this run, including intermediate JSON and final artifacts. |
| ctx.log | Publish structured progress, completion details, and useful result metadata to the run. |
| ctx.tool | Call an approved MCP tool from an available Connection, such as reading a permitted record or creating an allowed result. |
| ctx.agent | Run a foreground child agent for a bounded reasoning task and validate its structured output. |
| ctx.parallel | Run independent work concurrently when the operations do not depend on one another. |
| ctx.halt and ctx.resume | Pause at an approval or missing-input boundary, then continue with the resume payload supplied to the run. |
#Include the Workflow Script in a Skill
A Workflow Script can be included in a Skill. Keep the script beside the instructions and supporting documentation that explain when the process applies, the expected inputs and result, its permitted resources, and the quality checks the agent should perform.
The Skill gives the agent enough context to operate and maintain the script instead of treating it as an opaque automation. The script handles repeatable execution; the surrounding Skill explains the purpose and how to judge whether it worked.
#Open current and previous Workflow Runs
Choose Workflow Runs from the workspace panel to see current and previous executions. Open a run to review its source reference, input, visible step history, current state, and output. Stop a run only when continuing would be unsafe, unnecessary, or based on invalid input.
#Start a Workflow Run
Open botdojo://core/workflow-runs/TOOLS.md when an agent needs to start or discover runs. workflow_run_start accepts a workspace-relative sourceFile such as workflows/northstar-opportunity-brief.workflow.ts, an optional title and description, and input that must satisfy the script’s inputSchema.
After the tool returns a run ID, use the scoped resource botdojo://core/workflow-runs/<run-id>/TOOLS.md for status, waiting, resume, abort, read, or fork actions tied to that run.
#Follow the Workflow Run
workflow_run_show_progress opens the Workflow Run Status experience in the conversation. The header shows the Workflow Script title, current state, and elapsed or completion time. The Summary view follows recent durable steps as they run and shows the completed result or first useful error.
Choose Details to inspect the complete step history, run metadata, output, and available step files. Select an individual step when you need to verify its output or find where a failed run first diverged from the expected process.
- Running work updates automatically while the run is active.
- Waiting runs identify the approval or input needed before they can continue.
- Completed runs preserve their result and durable step history.
- Failed runs keep the visible error and completed work needed for diagnosis.
#Read the Workflow Run state
| State | What to do |
|---|---|
| Running | Follow the current step and wait while progress is still changing. |
| Waiting | Review whether the run needs input, access, or an external result. |
| Completed | Open and verify the full result or artifact. |
| Failed | Inspect the first useful error and correct the input, access, or program. |
| Aborted | Confirm why the run was stopped before starting another one. |
#Build a custom view for a Workflow
The standard Workflow Run Status view is appropriate when users primarily need progress, step details, errors, and the final output. When the workflow has a task-specific experience, it can render a custom view through the same Model Context Protocol (MCP) App surface.
Use resultCard(ctx) for a self-contained HTML summary that appears after a successful run. Use uiSourceFile when the run needs a custom live TSX status view. The TSX component owns the main Workflow canvas while BotDojo keeps Workflow Details available from the information control.
A custom view can turn low-level run state into the information a user cares about. The Northstar opportunity example can show the company and stage, progress through its three durable steps, and then present the summary, risks, next action, and saved report without requiring the user to interpret raw output.
- Use bridge.onContext(...) to receive updated status, steps, halts, input, and results.
- Use bridge.callTool(...) only for the scoped Workflow Run tools, such as status, read, resume, and abort.
- Use bridge.openLink(...) to open a report or another permitted destination outside the view.
- Use bridge.sendUiMessage(...) or bridge.prompt(...) to continue the work in chat.
- Use bridge.resize(...) after the custom view changes size.
- Call external Connection tools from the Workflow Script, not from its UI.
| Presentation | Use it when | Behavior |
|---|---|---|
| Standard Workflow Run Status | Users need general progress, step inspection, errors, and output. | BotDojo renders the normal Summary and Details experience. |
| resultCard(ctx) | The run needs a tailored completed summary but no live interaction. | The returned HTML replaces the completed result body after the run finishes. |
| uiSourceFile | Users need a live, task-specific status or review experience. | A workspace-relative TSX component renders for the entire run and receives current Workflow context. |
#Control and inspect Workflow Runs
These are the current public Workflow Run tools. workflow_run_show_progress is the only one that opens the inline progress view; the other tools return structured data an agent can inspect or use in later work.
| Tool | What it does |
|---|---|
| workflow_run_start | Starts source from a saved file, saved source reference, or small inline script and returns the new run ID. |
| workflow_run_list | Lists recent runs and can filter by status, workspace, session, agent, or resource group. |
| workflow_run_status | Returns the latest run, job, step, halt, result, and error state without opening the progress view. |
| workflow_run_wait | Waits for a bounded time until the run completes, fails, is aborted, is cancelled, or needs input. |
| workflow_run_show_progress | Opens the live Workflow Run view and can optionally wait for progress before returning. |
| workflow_run_read | Reads the run manifest, a run artifact, or the output or error recorded for one durable step. |
| workflow_run_resume | Continues a waiting run and supplies the payload returned by the matching ctx.halt call. |
| workflow_run_fork | Creates a new run from the original, latest, or overridden source without changing the original run. |
| workflow_run_abort | Stops a running or waiting run and records the reason it was cancelled. |
#Diagnose a failure and verify the repair
- 01
Open the failed run
Find the first failed step and read its visible error and input context.
- 02
Locate the source
Open the Workflow Script referenced by the run and the Skill documentation that explains the intended process.
- 03
Choose the correct fix
Correct invalid input or access when the script is sound; repair the source when its behavior does not match the Skill.
- 04
Start a new Workflow Run
Use representative input and verify the repaired step, remaining steps, and final result.