Running example

Countdown is a complete workflow that accepts a non-negative integer and returns zero. At each iteration, an agent proposes the preceding integer, and Python validates the proposal before updating the counter.

This tutorial prepares the project, executes the workflow, and modifies its input. The reference pages use the same example to explain individual language constructs.

Obtain the example

Complete Getting started, then clone the repository:

git clone https://github.com/verdog-ai/verdog-running-example.git
cd verdog-running-example

Open this directory in VS Code. Review the source and trust the workspace to enable extension commands and the Runs view. From the Command Palette, run Verdog: Show Canvas and select Countdown under Subroutines to inspect the graph. Run the following commands in the integrated terminal, from the project root.

Prepare the project

verdog sync
verdog check

verdog sync installs the project's dependencies and prepares its Python environments. Manual environment activation is unnecessary. verdog check checks the graph and the authored Python; it should complete without errors.

Execute the workflow

First, use an input of zero to verify execution without a provider account:

verdog run main -- --input.value 0

The workflow exits without visiting the agent node. The terminal reports a successful run and a result containing Count(value=0). It also prints the run directory under .verdog/runs/main/.

To execute the agent node, install the Codex CLI and authenticate it:

codex login
codex login status

After confirming authentication, run the workflow with an input of one:

verdog run main -- --input.value 1

A valid agent response produces one decrement, from 1 to 0, and the result again contains Count(value=0). Each decrement invokes Codex once and uses the provider account's available quota or billing. Invalid responses fail the run; this example does not contain a repair loop.

The -- separates Verdog options from the workflow's typed arguments. verdog run main -- --help lists those arguments. The original default input is 10, so verdog run main requires ten valid agent responses to complete.

Inspect the execution

Open the Runs view in VS Code and expand main. Use Verdog: Refresh Runs if the latest execution is not yet listed. Select the run and use Open Run Output to inspect its directory:

File	Contents
config.md	Input values used for the run.
trace.log	Visits in execution order, with their status and duration.
stats.md	Execution statistics.

The agent visit's directory also contains its prompt and response. For the one-step run, the trace includes decrement, update_counter, and a final visit to exit. The workflow's return value is printed in the terminal. See Logging for the complete artifact layout.

Modify the input

Open src/demo/countdown/subroutines/main/impl.py and change the default value in the Count dataclass:

-    value: int = 10
+    value: int = 2

Save the file, check the project, and run it without an explicit input:

verdog check
verdog run main

With valid responses, the workflow now performs two decrements, 2 → 1 → 0, and returns Count(value=0). Verdog: Run Workflow uses the same Python default. An explicit --input.value overrides it for a single execution. Changing this authored Python value requires no dependency synchronization.

Execution semantics

The graph below shows the original input of ten. Its structure is unchanged by the preceding modification.

Node	Behavior
initialize_counter	Assigns the input value to the numerical feature counter.
check_counter	Selects exit when the counter is zero and decrement when it is positive.
decrement	Invokes the agent to propose the next integer.
update_counter	Requires next == current - 1 and updates the counter.

The counter? effect permits the initial assignment. This edge has no condition: conditions observe the feature state before the source visit, when counter is still undefined. The loop returns to check_counter, so initialization occurs only once.

For initial input $n\in \mathbb{N}$, each accepted proposal satisfies $c_{i+1}=c_i-1$, with $c_0=n$. Provided that each invocation returns a valid response, the workflow therefore reaches $c_n=0$ after exactly $n$ decrements. The ports enter and exit transfer control; they are not executable nodes. The required failure port has no incoming edge and is omitted from the diagram.

Run the structural termination analysis with:

verdog analyze

The analysis certifies termination from the graph's declared conditions and strict decrease of a non-negative integer feature. The exact decrement of one is enforced separately by the authored Python. The certificate does not establish that an individual provider request or Python visit terminates.

For subsequent modifications, see Visits for Python behavior, Features for conditions and effects, and Project structure for the distinction between authored and generated files.