Starts a new instance of a published workflow and returns the first agent-facing instruction.
Parameters
| Name | Type | Required | Meaning |
|---|---|---|---|
workflow_id |
string | yes | The published workflow's name or id, from ccw_list. |
input |
object | no | Instance input. Validated against the workflow's inputSchema. |
Returns
The engine runs through every engine-executed step — start, set_variable, task-list bookkeeping, sub-workflows — until it reaches a step that needs the agent, and returns:
| Field | Meaning |
|---|---|
instanceId |
The running instance. Every later call uses it. |
status |
continue — a step is ready for the agent. Can also be waiting (an approval gate), completed, failed or stopped if the workflow got there without needing the agent. |
stepId, stepType |
The step the agent is being asked to perform: instruction, decision, shell, review or gate. |
instruction |
The author's prompt, with interpolated data wrapped in <user-data name="…"> tags so the agent can tell instructions from runtime data. |
systemGuidance |
Engine-generated guidance, kept separate from the prompt so the agent can hold it at a higher trust level: the allowed branch labels for a decision, the reporting contract for a shell command, the output-location block, and whether to run the step in a subagent. |
message |
For waiting, completed, failed and stopped: the gate's question, the completion summary, or the reason. |
taskProgress |
Inside a task loop: list name, completed and total counts, and the current task. |
Example
The tool call the agent makes:
{ "workflow_id": "Clean Code Assessment", "input": { "target": "/srv/repo", "reportPath": "docs/clean-code.md" } }You rarely write that yourself. In a project where the engine is configured, typing the tool name and the workflow into your agent's chat is enough:
ccw_start Clean Code Assessment
The agent recognises the tool, asks for any required input the workflow's schema declares — or takes it from the rest of your sentence — and makes the call. From there it follows the instructions each step returns.
Notes
input is validated before anything runs. A missing required field or a value outside an enum fails the call, not the run.
If the first agent-facing step is a gate, the response is status: "waiting" with the gate's message — see ccw_continue for how the answer goes back.