Agents on the canvas
By the end of this page you will know every setting on a step, including the two that behave differently from how most people expect.
Prerequisites
- A graph with at least two connected agents (Canvas tour).
- Admin or Developer role.
Click an agent on the canvas to open its settings.
Step label
A readable name for this step. It appears in the plan card, the live step group and any approval prompt. Leave it empty to fall back to the step’s own id.
Output key
Where this agent’s result is stored in the shared scratchpad. Later agents read it, and conditions reference it as stm.<key>.
Each step gets a sensible key automatically. Change it when a clearer name would make your conditions easier to read — stm.risk_verdict tells you more than stm.step_2_output.
Two steps must not share an output key. If they do, the later one overwrites the earlier, and the editor blocks the save with “Two nodes write the output key … — the later one would overwrite the earlier.”
If this agent fails
What the turn does when this step errors.
| Option | What happens |
|---|---|
| Stop the turn | The whole turn ends. This is the default. |
| Skip what follows | This step and everything downstream of it are skipped; other branches carry on. |
| Carry on anyway | The turn continues as though the step had succeeded. Later steps read an empty value where its output would have been. |
Choose Skip what follows for an optional branch, and Carry on anyway only when a later step genuinely copes with a missing input.
What this step reads
This is the setting that most often surprises people.
By default, qRaptor works out a step’s input automatically:
- A starting step reads the user’s message.
- Any other step reads the outputs of the steps immediately before it — and not the user’s original message.
A step in the middle of a graph does not see what the user asked, only what the previous agent wrote. If a detail from the request has to reach it — a format, a language, a constraint — you must pass it deliberately.
Click Customise to take control. You can then:
- Tick The user’s original message to pass it through.
- Tick which upstream outputs this step should read, rather than all of them.
- Write a template, when you want to phrase the input rather than hand over raw values. Reference an output as
{output_key}and the user’s message as{message}.
Reset to automatic puts it back.
A warning appears if a step ends up reading nothing at all, or reads a key that no step writes.
Incoming paths
This control appears only when a step has two or more connections coming into it, because it is meaningless otherwise.
| Option | What it means |
|---|---|
| Wait for all paths | The step waits for every incoming path to finish, then runs once with all their results. |
| Run when any path reaches this node | The step runs as soon as one incoming path reaches it. |
The right answer depends on whether those paths are conditional.
- All paths always run → Wait for all paths. Every result is collected before the agent starts.
- The paths are conditional, so only one of them is expected to run → Run when any path reaches this node.
In the market-analysis flow, Report Builder is the step with two incoming paths — one from the legal branch, one from the writing branch. A run takes exactly one of them, so it needs Run when any path reaches this node.
This is the one setting whose wrong value fails silently. If every path into a step is conditional and you leave it on Wait for all paths, the step waits for paths that will never arrive — so it never runs, and neither does anything after it. You get no error — only a branch that quietly does nothing.
The panel detects the shape and tells you which option it chose and why. When it spots the dangerous combination it turns red and says to switch. Read that note rather than only the radio buttons.
Removing a step
The settings panel has a remove action at the bottom. Removing a step also removes its connections. Anything that only reached the graph through it becomes unreachable, which the validator will tell you about on save.
Save your changes
Click Save in the header. The preview runs the saved graph.
Common issues
- A step reads an empty value — Its upstream step did not run, or you customised its input to read a key nothing writes.
- A later step ignores what the user asked — It does not receive the message by default. Customise What this step reads and tick the user’s original message.
- A whole branch never runs — Check Incoming paths on the step where the branches meet.
- Save is blocked over output keys — Two steps write the same one. Rename one.