Durable Agent Runs

Hands-on: author a workflow DAG, start a run, drive it to a human gate, approve, and finish with a report — all against a file ledger that survives any interruption.

Prerequisite: sdtk-agent installed (Installation). Concepts: The Governance Kernel.

1. Initialize the ledger root

sdtk-agent init --project-path ./my-project

Creates .sdtk/agent-runtime/ — the durable home for every run.

2. Author a workflow and runtime map

A workflow is a JSON DAG of task and human_gate stages. A minimal three-stage shape:

{
  "stages": [
    { "id": "draft",   "type": "task",       "role": "author" },
    { "id": "approve", "type": "human_gate", "depends_on": ["draft"] },
    { "id": "publish", "type": "task",       "role": "publisher",
      "depends_on": ["approve"] }
  ]
}

The runtime map binds each role to an adapter for this environment — manual (wait for human evidence), shell (allowlisted binary), sdtk-cli (allowlisted sdtk-* binary), or hermes-kanban (dry-run plan compiler). Stages can also carry skip_when conditional-skip rules and retry/timeout policy.

Validate before running:

sdtk-agent workflow validate --file ./workflow.json

Validation catches cycles, unsafe paths, and schema errors.

3. Start the run (nothing executes yet)

sdtk-agent run start \
  --project-path ./my-project \
  --workflow ./workflow.json \
  --runtime-map ./runtime-map.json \
  --feature-key MY_FEATURE \
  --goal "Draft and publish the release notes" \
  --json

This only creates the ledger at .sdtk/agent-runtime/runs/<run_id>/. Because a run can fan out into many agent tasks, execution is a separate, explicit step.

4. Drive it forward

sdtk-agent run continue --project-path ./my-project --run-id <run_id>

The driver loop dispatches ready tasks through their adapters and stops when the run blocks (a gate or manual evidence), waits, or completes. Check where things stand any time:

sdtk-agent run status --project-path ./my-project --run-id <run_id> --json

Interrupt anything

Close the terminal, reboot, come back tomorrow — state lives in state.json + events.ndjson, not in a process. run continue resumes exactly where it stopped.

5. Decide the gate

When the run reaches approve, everything downstream is blocked until a named person decides:

sdtk-agent gate approve --project-path ./my-project --run-id <run_id> \
  --gate approve --approved-by alice
# or: sdtk-agent gate reject … --approved-by alice

The decision lands in the ledger's approvals/ with attribution. Then run continue again to execute the unblocked stages.

6. Report

sdtk-agent run report --project-path ./my-project --run-id <run_id>

A durable report of every task, gate decision, and evidence file — the audit trail the run leaves behind.

Manual-adapter tasks

If a role uses the manual adapter, a task completes when someone writes an evidence file:

.sdtk/agent-runtime/runs/<run_id>/evidence/<task_id>.evidence.json

This is the escape hatch that keeps humans (or out-of-band agents) first-class workers in a DAG.

Current limits

• run cancel and task retry are Shipped in sdtk-agent-kit@0.4.0.
• The published hermes-kanban adapter is dry-run/mock only; Hermes live dispatch remains Gated — validation-only pending real-box evidence, even though live-mode source ships in sdtk-agent-hermes-adapter@0.2.0. See Hermes Adapter.
• Evidence trust is same-machine in v0.x.

Where to go next

sdtk-agent referenceEvery command and option in detail.

The Governance KernelLedger anatomy and the pure state machine.

Workflows & GatesStage types, dependencies, skip rules, retries.