Running and debugging
Debugging a run
Every step of every run keeps what it was given, what it did and what it handed back. When a run surprises you, the answer is almost always in one of its steps.
Where problems show
- On the board: a failed process turns red, a skipped one grey and dashed, and one that hit a duplicate purple.
- In the process's settings panel: Last run failed in red, Skipped, or Already processed; the run was terminated, next to Last run output.
- In the run panel: the step's red Error block.
- Under the toolbar: a banner for a request the app couldn't carry out. Click it to dismiss it.
Reading a step
Open the run, then the step. From top to bottom it shows:
| Section | What it tells you |
|---|---|
| Status and time | When it started, and the tokens and cost an agent used. |
| Model: … · thinking: … | Which model an agent ran on, and its pi session. |
| Worked on the branch | The git branch, and per repository the commits it made, from one commit to another, and whether it left changes uncommitted. |
| Input | Each object it took, in its state. For a review: what it reviewed and who marked it. |
| Prompt sent to the agent | The whole prompt as the engine built it (or Script it ran, Request sent to Sentry). Check here first when an agent misunderstood. |
| What the agent did | The live transcript: its thinking, each tool it called and what came back, and what it said. |
| Decision | For a human step: who decided, and what. |
| Error | Why it failed: the error, a script's stderr, a timeout. |
| Output | What it handed in, and each object it generated, in its state. |
| Files | Download links for the files it wrote. |
JSON is shown as fields, with Raw and Formatted to switch, and Markdown is rendered. A procedure's step says Ran its board as run #N; click it to open that run.
Inspecting a process or object
While a run is shown, double-click any process or object to focus the run panel on it. For an object you see each value it took in the run, made by which step, its files, and which processes took it. For a process that didn't run, the panel says so, with Show all to go back to every step.
Retries and re-asks
Two different things can look like “it tried again”:
- Retries (set on the process) are steps of their own, so each try shows as a separate step in the list.
- Try N inside one transcript means the agent didn't hand in its output in the right shape, so it was asked again within the same step.
Common symptoms
| Symptom | Likely cause | Fix |
|---|---|---|
| An agent works on an empty input | Nothing generates the object it takes, so it exists empty from the start. | Have a person fill it in, or a script or Sentry step fetch it, before the agent. |
| A process never runs | It has an event link, so it runs only on its events; or it takes plainly the object it is meant to write. | Make it the start, or split it into a writer and a reviser that takes the object in the send-back state. |
| A join after a branch never runs | The branch not taken never generates its object. | Give the join a quorum (Needs) of 1, or build the branches with condition links. |
| A script’s output is in no state | Scripts and Sentry steps can’t decide states. | Add state rules to the object. |
| An object never reaches the last state | A state without a rule never matches, so a rule-less catch-all is never chosen. | Give the catch-all a rule that always holds. |
| A reviewer fails after a few rounds | It used up its rounds and sent work back again. | Raise Rounds, or add a failure handler to the reviewer. |
| Scheduled runs are skipped | The flow starts with a person, and the last run is still waiting for them. | Start a scheduled flow with a script or Sentry step. |
| A procedure doesn’t see the caller’s changes | A procedure runs in a workspace of its own, on its own branch. | Push or finish the work in the caller, and hand the procedure only what needs no checkout. |
| The run ends terminated | A step generated a unique value another run already stored. | Expected when deduplicating; otherwise check the Unique attributes. |
| Nothing runs at all | The Start node isn’t connected. | Drag from Start to the first process; the Run button stays disabled until then. |
Check the OPL
Many mistakes show up before a run as a missing or surprising sentence. Open OPL and read it through:
The flow starts with Pick release.
Draft takes Release.
Pick release has a person fill in Release.
No The flow starts with… means no start. An agent that takes an object no sentence says is generated or filled in will get it empty. A process whose every input reads entering … triggers runs only on those events. When you have found the cause, fix the board and use Re-run from here rather than starting over.