Document fixed-count loops using internal.node_visit_count

Add a new section to the branch-loop tutorial showing how to loop a node
exactly N times using a diamond gate with a visit count condition, and
cross-reference it from the context docs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Bryan Helmkamp 2026-03-11 08:50:17 -04:00
parent 9b74cad56b
commit 86ac0ff394
2 changed files with 32 additions and 0 deletions

View file

@ -94,6 +94,13 @@ gate -> fix [condition="outcome=fail"]
The `context.` prefix is optional — `tests_passed=true` and `context.tests_passed=true` are equivalent.
Engine-managed keys like `internal.node_visit_count` work in conditions too. This is useful for [fixed-count loops](/tutorials/branch-loop#fixed-count-loops):
```dot
gate -> exit [condition="context.internal.node_visit_count >= 5"]
gate -> improve
```
## Fidelity: Controlling agent context
When a new agent or prompt node starts, Arc assembles a **preamble** — a summary of what happened in prior stages. The **fidelity** setting controls how detailed this preamble is.

View file

@ -104,6 +104,30 @@ After 3 visits, Arc terminates the run rather than looping forever. You can also
graph [max_node_visits="20"]
```
## Fixed-count loops
Sometimes you want a node to execute exactly N times before moving on — for example, running an improvement pass 5 times. Use `internal.node_visit_count` in an edge condition:
```dot
digraph FixedLoop {
graph [goal="Run an improvement loop 5 times"]
rankdir=LR
start [shape=Mdiamond, label="Start"]
exit [shape=Msquare, label="Exit"]
improve [label="Improve", prompt="Pick an area and improve it."]
gate [shape=diamond, label="5 Done?"]
start -> improve -> gate
gate -> exit [condition="context.internal.node_visit_count >= 5"]
gate -> improve
}
```
The engine tracks how many times each node has been visited. When `gate` has been visited 5 times, the condition matches and execution advances to `exit`. The unconditional edge back to `improve` serves as the default fallback for earlier visits.
## Node type summary
This workflow uses four node types:
@ -121,6 +145,7 @@ This workflow uses four node types:
- **Conditional nodes** (`shape=diamond`) route execution based on edge conditions
- **Loops** are just edges that point backward — the agent receives prior context on each visit
- **`max_visits`** prevents infinite loops
- **`internal.node_visit_count`** in edge conditions enables fixed-count loops
- Unconditional edges act as default fallbacks
## Next